Get agent invocation information¶

Read the Agent Card to check the target agent’s A2A protocol version, input and output types, and capabilities.

GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agents/{agent_id}/.well-known/agent-card.json

Preparation before calling¶

Query the agent list, select an active agent, and record its owning workspace.

Prepare a personal access token with access to the target workspace and the workspace ID.

Request example¶

$AGENT_ID and $AGENT_WORKSPACE_ID are the id and workspace_id from the same agent list item. $WORKSPACE_ID is the workspace for this call; $AI_STUDIO_API_KEY is the credential.

curl --get "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/.well-known/agent-card.json" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Accept: application/json" \
  --data-urlencode "agent_workspace_id=$AGENT_WORKSPACE_ID"

Path parameters¶

Parameter	Type	Required	Description
`workspace_id`	string	Yes	Workspace for this call. Must match the workspace header.
`agent_id`	string	Yes	Target agent ID from the agent list.

Query parameters¶

Parameter	Type	Required	Description
`agent_workspace_id`	string	No	Agent’s owning workspace: the current workspace or `system`. Defaults to the current workspace.

For a system assistant, pass system in the query parameter and keep the actual target workspace in the path.

The generic endpoint GET /v5/agents/card?agent_id=...&agent_workspace_id=... also reads Cards. If it returns an error, use the workspace-scoped path above to check the same agent.

Successful response¶

Returns an Agent Card without a common response envelope. This excerpt shows the workflow assistant’s capability declarations; the full response also includes its URL and extension metadata. Display text may be localized.

{
  "name": "Matrixflow 工作流助手",
  "description": "根据自然语言和已注册工作项创建 Matrixflow 工作流。",
  "version": "v1",
  "protocolVersion": "0.3.0",
  "capabilities": {
    "streaming": true,
    "stateTransitionHistory": true
  },
  "defaultInputModes": ["text/plain", "application/octet-stream"],
  "defaultOutputModes": ["text/plain"]
}

Field	Type	Description
`name`	string	Agent display name.
`description`	string	Agent description.
`url`	string	Declared A2A URL; may be an internal deployment address.
`version`	string	Agent version.
`protocolVersion`	string	A2A protocol version.
`capabilities`	object	Capability declarations.
`capabilities.streaming`	boolean	Whether streaming is supported.
`capabilities.pushNotifications`	boolean	Whether push notifications are supported; returned when available.
`capabilities.stateTransitionHistory`	boolean	Whether state transition history is supported.
`defaultInputModes`	string[]	Default input media types.
`defaultOutputModes`	string[]	Default output media types.
`skills`	object[]	Declared skills; returned when available.
`metadata`	object	Protocol extensions, possibly including data-part capabilities.

[] after a type denotes an array. Use only declared capabilities and tolerate unknown extension fields. If url is an internal address, external clients should use the public workspace-scoped path in Call an agent from another agent, preserving agent_workspace_id. Do not send credentials to the internal address.

Error response¶

The generic endpoint can return this error when it cannot retrieve or process the Card. This error alone does not identify the cause.

{
  "code": "ErrServer",
  "data": null,
  "msg": "服务器内部错误"
}

HTTP status	Error code	Action
500	`ErrServer`	Save the request time and trace ID and check the workspace-scoped path. If failures persist, inspect service logs; do not infer a permission or model issue from this error alone.

Follow-up operations¶

Call the agent through the public workspace-scoped path. Use streaming and other extensions only when the Card declares support.

Last updated on Oct 19, 2026