Skip to main content

概览

Managed Agents API 的服务地址、协议约定与接口清单，由平台托管会话、沙箱、工具执行与事件流。

调用前请先配置认证；错误处理见错误码。

前提条件

  1. 已开通阿里云百炼，并创建 API Key。
  2. 获取工作空间 ID：阿里云百炼控制台右上角下拉菜单查看，形如 {workspace_id}。

Endpoint

API 基地址按工作空间与地域拼装： 
https://{workspace_id}.{region}.maas.aliyuncs.com/api/v1/agentstudio
  • workspace_id：工作空间 ID
  • region：地域 ID，当前仅支持 cn-beijing

SDK

除直接调用 REST 接口外，还可通过 Python 或 Java SDK 接入。Managed Agents 模块要求 Python SDK v1.26.2 及以上、Java SDK v2.22.24 及以上。若已安装旧版本，请重新执行安装命令以升级。 会话级 Agent 配置覆盖（agent 对象与 patch）和会话级 MCP 请求头（mcp_configs）需要 Python SDK v1.27.7 及以上、Java SDK v2.23.2 及以上；直接调用 REST 接口不受此限制。 
pip install dashscope

请求与响应

  • 请求体为 JSON，Content-Type: application/json
  • 每次响应携带 x-request-id 头，可用于定位具体请求
  • 列表端点支持分页：limit（默认 20，最大 100）、page（首次不传，后续传上一次响应的 next_page）。响应不含 next_page 表示已是末页

可用 API

资源端点用途
AgentPOST /agents创建 Agent
GET /agents/{agent_id}获取 Agent
GET /agents列出 Agent
POST /agents/{agent_id}更新 Agent（自动生成新版本号）
POST /agents/{agent_id}/archive归档 Agent
EnvironmentPOST /environments创建 Environment
GET /environments/{environment_id}获取 Environment
GET /environments列出 Environment
POST /environments/{environment_id}更新 Environment
DELETE /environments/{environment_id}删除 Environment
POST /environments/{environment_id}/archive归档 Environment
Session & EventPOST /sessions创建 Session
GET /sessions/{session_id}获取 Session
GET /sessions列出 Session
POST /sessions/{session_id}更新 Session（如重命名）
DELETE /sessions/{session_id}删除 Session
POST /sessions/{session_id}/archive归档 Session
POST /sessions/{session_id}/events发送 Event（向 Agent 投递用户消息或工具回执）
GET /sessions/{session_id}/events列出 Event 历史；订阅 SSE 事件流（流式输出）
FilePOST /files上传 File（multipart/form-data）
GET /files/{file_id}查询 File 元数据
GET /files列出 File
DELETE /files/{file_id}删除 File
Memory StorePOST /memory_stores创建 Memory Store
GET /memory_stores列出 Memory Store
GET /memory_stores/{memory_store_id}获取 Memory Store
POST /memory_stores/{memory_store_id}更新 Memory Store
POST /memory_stores/{memory_store_id}/archive归档 Memory Store
POST /memory_stores/{memory_store_id}/memories创建 Memory（记忆文件）
GET /memory_stores/{memory_store_id}/memories列出 Memory
GET /memory_stores/{memory_store_id}/memories/{memory_id}获取 Memory
POST /memory_stores/{memory_store_id}/memories/{memory_id}更新 Memory
DELETE /memory_stores/{memory_store_id}/memories/{memory_id}删除 Memory
GET /memory_stores/{memory_store_id}/memory_versions列出 Memory Version（历史版本）
GET /memory_stores/{memory_store_id}/memory_versions/{memory_version_id}获取 Memory Version
POST /memory_stores/{memory_store_id}/memory_versions/{memory_version_id}/redact擦除 Memory Version 正文
SkillPOST /skills创建 Skill
GET /skills/{skill_id}查询 Skill
GET /skills列出 Skill
DELETE /skills/{skill_id}删除 Skill
POST /skills/{skill_id}/versions上传 Skill 新版本
GET /skills/{skill_id}/versions/{version}查询 Skill 版本
GET /skills/{skill_id}/versions列出 Skill 版本
GET /skills/{skill_id}/versions/{version}/content下载 Skill 包
VaultPOST /vaults创建 Vault
GET /vaults/{vault_id}获取 Vault
GET /vaults列出 Vault
POST /vaults/{vault_id}更新 Vault
DELETE /vaults/{vault_id}删除 Vault
POST /vaults/{vault_id}/archive归档 Vault
CredentialPOST /vaults/{vault_id}/credentials创建 Credential
GET /vaults/{vault_id}/credentials/{credential_id}获取 Credential
GET /vaults/{vault_id}/credentials列出 Credential
POST /vaults/{vault_id}/credentials/{credential_id}更新 Credential
DELETE /vaults/{vault_id}/credentials/{credential_id}删除 Credential
POST /vaults/{vault_id}/credentials/{credential_id}/archive归档 Credential
WebhookPOST /webhook_endpoints创建 Webhook
GET /webhook_endpoints/{id}查询 Webhook 详情
GET /webhook_endpoints查询 Webhook 列表
PUT /webhook_endpoints/{id}更新 Webhook
DELETE /webhook_endpoints/{id}删除 Webhook
POST /webhook_endpoints/{id}/enable启用 Webhook
POST /webhook_endpoints/{id}/disable禁用 Webhook
POST /webhook_endpoints/{id}/test测试 Webhook
POST /webhook_endpoints/{id}/reset_secret重置 Signing Secret
GET /webhook_endpoints/{id}/events查询 Webhook 事件