Agent Card¶

An Agent Card is the discovery document read before invoking an Agent. It describes the Agent’s name, protocol version, accepted modes, and advertised capabilities. Use it for connectivity checks, capability negotiation, and client feature flags—not as a source of runtime status.

Retrieve a Card¶

Select one Agent with agent_code or agent_id:

GET /newmoi/agents/card?agent_code=explore HTTP/1.1
Host: <moi-host>
moi-key: <api-key>
Accept: application/json

Add the agent_workspace_id query parameter when the service assigns an Agent workspace to that Agent. The caller must still provide the normal MOI authentication and workspace context.

The following example deliberately uses requests instead of moi.RawClient.get_json. The official Python SDK’s JSON helper unwraps the Catalog envelope, whereas this endpoint returns the Agent Card directly.

import os
import requests

base_url = os.environ["MOI_BASE_URL"].rstrip("/")
response = requests.get(
    f"{base_url}/newmoi/agents/card",
    params={"agent_code": "explore"},
    headers={
        "moi-key": os.environ["MOI_API_KEY"],
        "Accept": "application/json",
    },
    timeout=30,
)
response.raise_for_status()
card = response.json()

print(card["name"])
print(card.get("capabilities", {}).get("streaming", False))

MOI_BASE_URL is the MOI service root. If the URL supplied for your deployment already ends in /newmoi, remove the duplicate path segment from the example.

Interpret the fields¶

The exact fields depend on the Agent implementation and protocol version. A current Card can include:

Field	Purpose
`name`	Human-readable Agent name; not a stable selector
`version`	Version of the Agent implementation
`protocolVersion`	A2A protocol version declared by the Card
`capabilities.streaming`	Whether the Agent advertises streaming messages
`capabilities.stateTransitionHistory`	Whether state-transition history is advertised
`defaultInputModes`	Media types accepted by default
`defaultOutputModes`	Media types produced by default

A minimal example response is:

{
  "name": "Matrixflow Explore Agent",
  "version": "v2",
  "protocolVersion": "0.3.0",
  "capabilities": {
    "streaming": true,
    "stateTransitionHistory": true
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/json"]
}

Do not hard-code these example values as universal Agent capabilities. Clients should preserve unknown extension fields and behave conservatively when an optional field is absent. For example, if streaming is not advertised, use message/send or tell the caller that streaming support could not be confirmed.

Validation and caching¶

Verify that the response is a JSON object and contains the fields your client requires to display or select the Agent.
Negotiate only media types advertised by the Card; the message examples in this section use text/plain.
A Card may be cached briefly, but retrieve it again after an Agent release or target change.
Do not invoke A2A blindly after Card retrieval fails. Check the selector, API key, current workspace, and Agent visibility first.

After reading the Card, continue with messages and streaming.