# 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.

```text
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

```bash
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.

```json
{
  "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.

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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](call-agent-from-agent.md) based on `capabilities` and `url`; only use streaming calls or other extended capabilities if Card declares support.