# Get agent invocation information

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

```text
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](../agents/list-agents.md), select an active agent, and record its owning workspace.

Prepare a [personal access token](../../../../../guides/genesis/api-keys.md) with access to the target workspace and the [workspace ID](../../../../../guides/ai-studio/resource-center/workspace.md#copy-a-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.

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

```json
{
  "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](call-agent-from-agent.md), 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.

```json
{
  "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](call-agent-from-agent.md) through the public workspace-scoped path. Use streaming and other extensions only when the Card declares support.