Skip to main content

获取 Agent

根据 Agent ID 返回完整的 Agent 配置。

接口

GET /agents/{agent_id} 成功返回 200 和完整 Agent 对象。

路径参数

agent_id string (必选)Agent ID,按不透明字符串使用本接口没有 Query 参数。agent_id 格式错误、不存在、已删除或属于其他工作空间时返回 404。

请求示例

curl -sS "$BASE_URL/agents/agent_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

响应字段

未设置的可选字段可能返回 null。id stringAgent ID,按不透明字符串使用object stringAgent 对象类型,固定为 agentcreated_at integer创建时间的 Unix 秒时间戳updated_at integer最近修改时间的 Unix 秒时间戳,不是版本号name string / null展示名称metadata object / null元数据,保存的字符串键值对model string保存的模型 IDreasoning object / null推理配置。两项均可为 null。
effort string / null推理强度:none、minimal、low、medium、high、xhigh、maxsummary string / null推理摘要:concise、detailed、auto
text object / null文本输出配置。
format object输出格式。
type string / null输出格式类型,固定为 text
verbosity string / null输出详细程度,low、medium、high
instructions string / null保存的自定义指令tools array / null保存的工具配置;每个分支只返回本分支字段
function objectFunction 工具配置,返回 name、description、parametersmcp objectMCP 工具配置,返回 server_label、transport、allowed_tools、required、connection_origin;transport 为 http 或 stdioweb_search objectWeb Search 工具配置,返回 type 和已保存的配置
multi_agent object / null子 Agent 配置。
enabled boolean是否启用子 Agent 工具max_concurrent_subagents integer / null最大并发子 Agent 数;不补默认值

响应示例

{
  "id": "agent_xxx",
  "object": "agent",
  "created_at": 1794117521,
  "updated_at": 1794117521,
  "name": "quickstart-agent",
  "metadata": null,
  "model": "qwen3.8-max",
  "reasoning": null,
  "text": null,
  "instructions": "回答简洁,只输出必要信息。",
  "tools": null,
  "multi_agent": null
}

错误码

业务错误返回 error 对象,包含 type、code、message 和 param。常见错误如下:
HTTP 状态码错误类型 / 错误码解决方案
401authentication_error / invalid_api_key在请求头携带有效的 Authorization: Bearer $DASHSCOPE_API_KEY
404not_found_error / not_found_error使用当前工作空间中存在且未删除的 Agent ID
500server_error / server_error稍后重试;持续失败时提交工单并提供 x-request-id