Only the Chinese version of this page is provided currently. The English version will be provided soon.
Help & Documentation>腾讯云数据库 AI 服务>Memory 应用指南>开发者参考>V3 版本>HTTP>Metadata>Agent 管理

Agent 管理

Last updated: 2026-09-23 21:01:01

On this page:

接口介绍

Metadata Agent 管理接口用于创建、查询、更新、删除、列出和归档 Agent 资源。Agent 是 Memory 系统中执行任务的智能体实体。共6个接口：
接口
方法
功能
/v3/agent/create
POST
创建 Agent
/v3/agent/get
POST
获取 Agent 信息
/v3/agent/update
POST
更新 Agent
/v3/agent/delete
POST
批量删除 Agent
/v3/agent/list
POST
列出 Agent
/v3/agent/archive
POST
归档 Agent

创建 Agent

创建一个新 Agent，指定名称、所属团队和模型等属性。
POST /v3/agent/create

请求参数

字段
类型
必选
说明
name
string
是
Agent 名称
team_id
string
是
所属团队 ID
model
string
否
Agent 使用的模型名称
description
string
否
Agent 描述
metadata
object
否
自定义元数据

请求示例

curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer *********************************' \\
  -H "x-tdai-service-id: tdai-mem-xxxxxxxx" \\
  https://memory.tdai.tencentyun.com/v3/agent/create \\
  -d '{"name":"sql-helper","team_id":"team-abc","model":"gpt-4o"}'

响应示例

{
  "code":0,
  "message":"ok",
  "request_id":"req-7fd3b2dd",
  "data":{
    "agent_id":"agt-xyz789",
    "name":"sql-helper",
    "team_id":"team-abc",
    "model":"gpt-4o",
    "created_at_ms":1758096000000
  }
}

响应 data

字段
类型
说明
agent_id
string
新创建的 Agent 唯一标识 ID
name
string
Agent 名称
team_id
string
所属团队 ID
model
string
使用的模型
created_at_ms
int
创建时间

获取 Agent 信息

按 Agent ID 查询详细信息。
POST /v3/agent/get

请求参数

字段
类型
必选
说明
agent_id
string
是
Agent ID

请求示例

curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer *********************************' \\
  -H "x-tdai-service-id: tdai-mem-xxxxxxxx" \\
  https://memory.tdai.tencentyun.com/v3/agent/get \\
  -d '{"agent_id":"agt-xyz789"}'

响应示例

{
  "code":0,
  "message":"ok",
  "request_id":"req-7fd3b2dd",
  "data":{
    "agent_id":"agt-xyz789",
    "name":"sql-helper",
    "team_id":"team-abc",
    "model":"gpt-4o",
    "status":"active",
    "created_at_ms":1758096000000,
    "updated_at_ms":1758182400000
  }
}

响应 data

字段
类型
说明
agent_id
string
Agent ID
name
string
Agent 名称
team_id
string
所属团队 ID
model
string
使用的模型
status
string
Agent 状态（active/archived）
created_at_ms
int
创建时间
updated_at_ms
int
最后更新时间

更新 Agent

更新 Agent 属性（如模型、名称等）。
POST /v3/agent/update

请求参数

字段
类型
必选
说明
agent_id
string
是
待更新的 Agent ID
name
string
否
更新后的名称
model
string
否
更新后的模型
description
string
否
更新后的描述

请求示例

curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer *********************************' \\
  -H "x-tdai-service-id: tdai-mem-xxxxxxxx" \\
  https://memory.tdai.tencentyun.com/v3/agent/update \\
  -d '{"agent_id":"agt-xyz789","model":"gpt-4.1"}'

响应示例

{
  "code":0,
  "message":"ok",
  "request_id":"req-7fd3b2dd",
  "data":{
    "agent_id":"agt-xyz789",
    "updated_at_ms":1758268800000
  }
}

响应 data

字段
类型
说明
agent_id
string
已更新的 Agent ID
updated_at_ms
int
最后更新时间

批量删除 Agent

批量硬删除 Agent，操作不可恢复。
POST /v3/agent/delete

请求参数

字段
类型
必选
说明
agent_ids
string[]
是
待删除的 Agent ID 列表

请求示例

curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer *********************************' \\
  -H "x-tdai-service-id: tdai-mem-xxxxxxxx" \\
  https://memory.tdai.tencentyun.com/v3/agent/delete \\
  -d '{"agent_ids":["agt-xyz789"]}'

响应示例

{
  "code":0,
  "message":"ok",
  "request_id":"req-7fd3b2dd",
  "data":{
    "deleted":true
  }
}

响应 data

字段
类型
说明
deleted
bool
删除是否成功

列出 Agent

按条件列表查询 Agent。
POST /v3/agent/list

请求参数

字段
类型
必选
说明
team_id
string
否
按团队 ID 筛选
status
string
否
按状态筛选（active/archived）
limit
int
否
每页返回数量
offset
int
否
分页偏移量

请求示例

curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer *********************************' \\
  -H "x-tdai-service-id: tdai-mem-xxxxxxxx" \\
  https://memory.tdai.tencentyun.com/v3/agent/list \\
  -d '{"team_id":"team-abc"}'

响应示例

{
  "code":0,
  "message":"ok",
  "request_id":"req-7fd3b2dd",
  "data":{
    "items":[
      {
        "agent_id":"agt-xyz789",
        "name":"sql-helper",
        "team_id":"team-abc",
        "model":"gpt-4o",
        "status":"active",
        "created_at_ms":1758096000000
      },
      {
        "agent_id":"agt-abc123",
        "name":"data-analyst",
        "team_id":"team-abc",
        "model":"gpt-4.1",
        "status":"active",
        "created_at_ms":1758182400000
      }
    ],
    "total":2
  }
}

响应 data

字段
类型
说明
items
array
Agent 列表
total
int
符合条件的 Agent 总数

归档 Agent

归档 Agent（软删除，可恢复）。
POST /v3/agent/archive

请求参数

字段
类型
必选
说明
agent_id
string
是
待归档的 Agent ID

请求示例

curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer *********************************' \\
  -H "x-tdai-service-id: tdai-mem-xxxxxxxx" \\
  https://memory.tdai.tencentyun.com/v3/agent/archive \\
  -d '{"agent_id":"agt-xyz789"}'

响应示例

{
  "code":0,
  "message":"ok",
  "request_id":"req-7fd3b2dd",
  "data":{
    "agent_id":"agt-xyz789",
    "status":"archived",
    "updated_at_ms":1758268800000
  }
}

响应 data

字段
类型
说明
agent_id
string
已归档的 Agent ID
status
string
Agent 状态，归档后为 archived
updated_at_ms
int
最后更新时间

错误码

HTTP 状态码
错误信息
说明
400
request: Invalid input
请求参数不合法。
401
Missing or invalid Authorization header
Bearer API Key 缺失或格式不正确。
Missing x-tdai-service-id header
请求头中未携带 x-tdai-service-id。
404
AGENT_NOT_FOUND
指定 Agent 不存在。
500
Internal error
服务内部错误，可有限重试。
中国站 - English