Apps API · Agents
Agents: 15 个接口
GET /api/v1/agent-profiles
List agent profiles (aggregated, scoped)
权限(scope): agents:agent:read · 调用方式: appToken · operationId: list-agent-profiles
Required app scope: agents:agent:read.
Returns the requested agents' profiles (display + status + online_status, plus skills/tags when include=capabilities). A scope is REQUIRED — pass project_id (resolved to the project's agents) and/or repeatable member_id. Open-ended capability search across the org is intentionally NOT here — that is the search layer's job. The Connection dimension is a planned follow-up.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
project_id |
query | string | Scope to the agents that are members of this project | |
member_id |
query | array of string | Repeatable: scope to these specific agent member IDs | |
include |
query | array of string | Repeatable. Facets to load. Supported: capabilities (skills + tags). Omit for the lightweight agent view. |
回包
200OK —application/json·DataResponseListAgentProfileBodydefaultError —application/problem+json·D8Error
GET /api/v1/agents/{member_id}/automation-creation-eligibility
Check Agent compatibility for new automation
权限(scope): automations:binding:read · 调用方式: appToken · operationId: get-automation-creation-eligibility
Required app scope: automations:binding:read.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | |
project_id |
query | string (uuid) | Project of the automation; required unless unattached_scope is given | |
unattached_scope |
query | string: org, private |
Check for an automation attached to no project instead: org (the Inbox) or private (the caller's hidden private project) | |
operation |
query | string: create, update, replace, lead_change |
回包
200OK —application/json·DataResponseAutomationCreationEligibilityBodydefaultError —application/problem+json·D8Error
PUT /api/v1/agents/{member_id}/avatar
Set Agent avatar
权限(scope): agents:agent:write · 调用方式: appToken · operationId: set-agent-avatar
Required app scope: agents:agent:write.
Sets or resets an Agent's avatar. avatar_url must be a URL returned by POST /api/v1/avatars/uploads/finalize in this organization, or "" to restore the default avatar (saved as null); anything else is 400 AVATAR_URL_NOT_ALLOWED. Caller must be the org-owner, an org-admin or the Agent's owner (same rule as the Agent policy routes): other callers get 403 AUTH_FORBIDDEN; a target that is not an Agent is 400. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Agent member UUID |
请求体
application/json · SetAgentAvatarInputBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
avatar_url |
string | 是 | Avatar URL returned by POST /api/v1/avatars/uploads/finalize in this organization, or "" to restore the default avatar |
回包
200OK —application/json·DataResponseAgentAvatarDataBodydefaultError —application/problem+json·D8Error
PUT /api/v1/agents/{member_id}/capability-tags
Set an agent's capability tags
权限(scope): agents:agent:write · 调用方式: appToken · operationId: set-agent-capability-tags
Required app scope: agents:agent:write.
Replaces the agent member's whole human-declared capability-tag set (declarative). Tags are the subjective ACP dimension: curated tags (controlled vocabulary) are hard-filterable by Lead; freeform tags carry free-text nuance for soft ranking. Requires the caller to be the agent's owner or an org admin/owner.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Agent member UUID |
请求体
application/json · SetAgentCapabilityTagsRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
tags |
array of CapabilityTagInputDTO |
是 | Full replacement capability-tag set for the agent (declarative; the prior set is replaced) |
回包
200OK —application/json·DataResponseAgentCapabilityTagsDataBodydefaultError —application/problem+json·D8Error
GET /api/v1/agents/{member_id}/model-config
Get an agent's model configuration
权限(scope): agents:model:read · 调用方式: appToken · operationId: get-agent-model-config
Required app scope: agents:model:read.
available_models lists the models the agent's runtime advertises (in the order the runtime reports them) minus models the deployment restricts to operators. effective_model / desired_model always report the actual model truthfully, even when it is a restricted model that is not selectable.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Agent member UUID |
回包
200OK —application/json·AgentModelResponseBodydefaultError —application/problem+json·D8Error
PATCH /api/v1/agents/{member_id}/model-config
Reconfigure an agent's global model
权限(scope): agents:model:write · 调用方式: appToken · operationId: update-agent-model-config
Required app scope: agents:model:write.
Changes the Agent-global model for all subsequent conversations. This is not a per-message setting. The model must be one of the agent's selectable available_models (see get-agent-model-config): a model the runtime does not advertise, or one the deployment restricts to operators, is rejected with the same 400 — even when it is already the agent's effective model.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Agent member UUID |
请求体
application/json · UpdateAgentModelRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | 是 |
回包
200OK —application/json·AgentModelResponseBodydefaultError —application/problem+json·D8Error
PATCH /api/v1/agents/{member_id}/model-visibility
Update an agent's model visibility
权限(scope): agents:model:write · 调用方式: appToken · operationId: update-agent-model-visibility
Required app scope: agents:model:write.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Agent member UUID |
请求体
application/json · UpdateAgentModelVisibilityRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
visible |
boolean | 是 |
回包
200OK —application/json·AgentModelResponseBodydefaultError —application/problem+json·D8Error
GET /api/v1/agents/{member_id}/runtime-metrics
Get agent runtime metrics
权限(scope): agents:runtime:read · 调用方式: appToken · operationId: get-agent-runtime-metrics
Required app scope: agents:runtime:read.
Returns the latest runtime metrics reported by the agent. Caller must be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Agent member UUID |
回包
200OK —application/json·DataResponseAgentRuntimeMetricsDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{member_id}/runtime/interrupt
Interrupt an agent's runtime session
权限(scope): agents:runtime:control · 调用方式: appToken · operationId: interrupt-agent-runtime
Required app scope: agents:runtime:control.
Issues a behavior InterruptSession command to agent-manager for the given agent member. The command is accepted asynchronously (202). Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Agent member UUID |
回包
202Accepted —application/json·InterruptAgentRuntimeResponseBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{member_id}/runtime/pause
Pause an agent's runtime
权限(scope): agents:runtime:control · 调用方式: appToken · operationId: pause-agent-runtime
Required app scope: agents:runtime:control.
Issues a runtime Pause command to agent-manager for the given agent member. The command is accepted asynchronously (202). Requires the caller to be the agent's owner or an org admin, and the target must be a platform-created agent.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Agent member UUID |
回包
202Accepted —application/json·PauseAgentRuntimeResponseBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{member_id}/runtime/restart
Restart an agent's runtime
权限(scope): agents:runtime:control · 调用方式: appToken · operationId: restart-agent-runtime
Required app scope: agents:runtime:control.
Issues a runtime Restart command for the given agent member. The command is accepted asynchronously (202). Requires the caller to be the agent's owner or an org admin, and the target must be a platform-created agent (external/invited agents have no platform-managed runtime). Optional body field upgrade_image=true retargets the agent to its latest resolved runtime image before restarting (teardown/recreate); default false is a plain in-place restart. Pause and resume work the same way.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Agent member UUID |
请求体
application/json · RestartAgentRuntimeRequestBody (可不带)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
upgrade_image |
boolean | When true, upgrade the agent to its latest resolved runtime image before restarting (heavier: teardown/recreate, running tasks may be lost). Default false = plain in-place restart. |
回包
202Accepted —application/json·RestartAgentRuntimeResponseBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{member_id}/runtime/resume
Resume an agent's runtime
权限(scope): agents:runtime:control · 调用方式: appToken · operationId: resume-agent-runtime
Required app scope: agents:runtime:control.
Issues a runtime Resume command to agent-manager for the given agent member. The command is accepted asynchronously (202). Requires the caller to be the agent's owner or an org admin, and the target must be a platform-created agent.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Agent member UUID |
回包
202Accepted —application/json·ResumeAgentRuntimeResponseBodydefaultError —application/problem+json·D8Error
GET /api/v1/agents/{member_id}/storage
Get agent disk expansion state
权限(scope): billing:usage:read · 调用方式: appToken · operationId: get-agent-storage
Required app scope: billing:usage:read.
Returns the agent's disk sizes, daily surcharge equivalent, in-flight expansion order and purchasable tiers, as reported by the billing system. Any org member who can view the agent.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 |
回包
200OK —application/json·DataResponseAdminAgentStorageDTOBodydefaultError —application/problem+json·D8Error
POST /api/v1/automation-creation-handoffs
Send an authorized new automation request to an Agent DM
权限(scope): automations:binding:write · 调用方式: appToken · operationId: create-automation-handoff
Required app scope: automations:binding:write.
请求体
application/json · AutomationHandoffRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
intro |
string | 是 | |
request |
AutomationCreationPayload |
是 |
回包
200OK —application/json·DataResponseAutomationHandoffResultBodydefaultError —application/problem+json·D8Error
POST /api/v1/automation-update-handoffs
Send an authorized automation update request to its Agent DM
权限(scope): automations:binding:write · 调用方式: appToken · operationId: update-automation-handoff
Required app scope: automations:binding:write.
请求体
application/json · AutomationUpdateHandoffRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
intro |
string | 是 | |
request |
AutomationUpdatePayload |
是 |
回包
200OK —application/json·DataResponseAutomationHandoffResultBodydefaultError —application/problem+json·D8Error
