Get the agent call instructions¶

Read the Agent Card and confirm the A2A protocol version, calling address, input and output type and capability supported by the target agent. Regular agents must use agent_id; the universal entry only handles agent_code for supported built-in agent code.

GET https://moi.matrixorigin.cn/newmoi/agents/card

Preparation before calling¶

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

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.
$AGENT_ID: Target agent ID, passed through the query parameter agent_id.

Request example¶

curl --get "https://moi.matrixorigin.cn/newmoi/agents/card" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Accept: application/json" \
  --data-urlencode "agent_id=$AGENT_ID"

Query parameters¶

Parameters	Type	Is it required	Description
`agent_id`	string	Required for regular queries	Target agent ID.
`agent_code`	string	No	Supported built-in agent code. Cannot be used as a replacement for a normal agent ID.
`agent_workspace_id`	string	No	ID of the workspace to which the target agent belongs. If not provided, the current workspace is used; only the current workspace or the system workspace can be specified.

Successful response¶

Returns 200 and Agent Card on success. The response does not use the generic code, message, data envelopes. Clients should only call Card’s explicitly declared capabilities and be compatible with unknown extension fields.

{
  "name": "销售分析助手",
  "description": "用于销售数据分析",
  "url": "https://moi.matrixorigin.cn/newmoi/agents/a2a",
  "version": "1.0.0",
  "protocolVersion": "0.3.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "defaultInputModes": ["text/plain", "application/octet-stream"],
  "defaultOutputModes": ["text/plain"],
  "skills": []
}

The response fields are as follows.

Field	Type	Description
`name`	string	Agent display name.
`description`	string	Agent description; may be empty if not set.
`url`	string	The A2A calling address of this agent.
`version`	string	Agent version.
`protocolVersion`	string	A2A protocol version.
`capabilities`	object	Capability statement.
`capabilities.streaming`	boolean	Whether to support streaming calls.
`capabilities.pushNotifications`	boolean	Whether to support push notifications.
`capabilities.stateTransitionHistory`	boolean	Whether to support status change history.
`defaultInputModes`	string[]	Default input media type.
`defaultOutputModes`	string[]	Default output media type.
`skills`	object[]	The skill declared by the agent. The fields for each item are defined by the A2A Agent Card.
`metadata`	object	Protocol extension metadata; may contain platform-declared data fragmentation capabilities.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Error response¶

When the Agent Card cannot be generated, the interface returns a generic error envelope.

{
  "code": "ErrParamInvalid",
  "msg": "agent_code or agent_id is required",
  "data": null
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	`agent_id` or supported `agent_code` is not provided, or the selector format is invalid.	Provide valid selector and workspace request headers.
`500`	`ErrServer`	The target agent does not exist or is unavailable, or the server cannot generate the Agent Card.	Check the agent ID and running status; confirm it is correct and try again later.

Follow-up operations¶

Called Called by other agents based on capabilities and url; only use streaming calls or other extended capabilities if Card declares support.

Last updated on Sep 3, 2026