接口介绍
MetadataClient 提供以下 Agent 管理接口，用于创建、查询、更新、删除、列出和归档 Agent 资源。Agent 是 Memory 系统中执行任务的智能体实体。
create_agent：创建 Agent，指定名称、所属团队和模型等属性。
get_agent：按 Agent ID 查询详细信息。
update_agent：更新 Agent 属性（如模型、名称等）。
delete_agents：批量硬删除 Agent（不可恢复）。
list_agents：按条件列表查询 Agent。
archive_agent：归档 Agent（软删除，可恢复）。
导入
from tencentdb_agent_memory.v3 import MetadataClient
方法签名
def create_agent(self, p: Dict[str, Any]) -> Dict[str, Any]
def get_agent(self, agent_id: str) -> Dict[str, Any]
def update_agent(self, p: Dict[str, Any]) -> Dict[str, Any]
def delete_agents(self, agent_ids: List[str]) -> Dict[str, Any]
def list_agents(self, p: Dict[str, Any]) -> Dict[str, Any]
def archive_agent(self, agent_id: str) -> Dict[str, Any]
使用示例
create_agent
from tencentdb_agent_memory.v3 import MetadataClientmetadata = MetadataClient(endpoint="https://memory.tdai.tencentyun.com",api_key="sk-xxxxxxxxxxxxxxxx",service_id="tdai-mem-xxxxxxxx",)resp = metadata.create_agent({"name": "sql-helper", # 必填，Agent 名称"team_id": "team-abc", # 必填，所属团队 ID"model": "gpt-4o", # 可选，Agent 使用的模型"description": "SQL 查询助手", # 可选，Agent 描述"metadata": {"version": "1.0"}, # 可选，自定义元数据})print(resp)
get_agent
resp = metadata.get_agent("agt-xyz789")print(resp)
update_agent
resp = metadata.update_agent({"agent_id": "agt-xyz789", # 必填，待更新的 Agent ID"model": "gpt-4.1", # 可选，更新后的模型"name": "sql-helper-v2", # 可选，更新后的名称"description": "升级版 SQL 助手", # 可选，更新后的描述})print(resp)
list_agents
resp = metadata.list_agents({"team_id": "team-abc"})for agent in resp["items"]:print(agent["name"])
delete_agents
resp = metadata.delete_agents(["agt-xyz789"])print(resp)
archive_agent
resp = metadata.archive_agent("agt-xyz789")print(resp)
请求参数
create_agent
参数名 | 类型 | 必填 | 描述说明 |
name | str | 是 | Agent 名称 |
team_id | str | 是 | 所属团队 ID |
model | str | 否 | Agent 使用的模型名称 |
get_agent
参数名 | 类型 | 必填 | 描述说明 |
agent_id | str | 是 | Agent ID |
update_agent
参数名 | 类型 | 必填 | 描述说明 |
agent_id | str | 是 | 待更新的 Agent ID |
name | str | 否 | 更新后的名称 |
model | str | 否 | 更新后的模型 |
delete_agents
参数名 | 类型 | 必填 | 描述说明 |
agent_ids | List[str] | 是 | 待删除的 Agent ID 列表 |
list_agents
参数名 | 类型 | 必填 | 描述说明 |
payload | Dict | 是 | 查询条件，含 team_id 等字段 |
archive_agent
参数名 | 类型 | 必填 | 描述说明 |
agent_id | str | 是 | 待归档的 Agent ID |
响应示例
create_agent
{"agent_id": "agt-550e8400-e29b-41d4-a716-446655440000","name": "sql-helper","team_id": "team-abc","model": "gpt-4o","created_at_ms": 1723968000000}
get_agent
{"agent_id": "agt-xyz789","name": "sql-helper","team_id": "team-abc","model": "gpt-4o","status": "active","created_at_ms": 1723900000000,"updated_at_ms": 1723968000000}
list_agents
{"items": [{"agent_id": "agt-xyz789","name": "sql-helper","model": "gpt-4o","status": "active","created_at_ms": 1723900000000}],"total": 1}
响应参数说明
参数名 | 类型 | 参数含义 |
agent_id | str | Agent 唯一标识 ID |
name | str | Agent 名称 |
team_id | str | 所属团队 ID |
model | str | 使用的模型名称 |
status | str | Agent 状态，如 active、archived |
created_at_ms | int | 创建时间，Unix 时间戳，单位为毫秒 |
updated_at_ms | int | 最后更新时间，Unix 时间戳，单位为毫秒 |
items | List[Dict] | Agent 列表 |
total | int | 符合条件的 Agent 总数 |
错误码
错误码 | 触发场景 | 处理建议 |
400 | 请求参数不合法（如 name 为空） | 检查参数是否符合约束条件 |
401 | API Key 无效或缺失 | 检查 Bearer Token 配置 |
404 | 指定 Agent 不存在 | 确认 Agent ID 是否正确 |
500 | 服务内部错误 | 稍后重试 |
