← Docs · 日本語

AgenTrux A2A Agent Card & Endpoint

AgenTrux publishes an Agent Card for the A2A (Agent-to-Agent) protocol and serves a stateless A2A JSON-RPC endpoint. By fetching the Agent Card, other agents can automatically discover what AgenTrux can do (skills), where to connect (url), and how to authenticate (security).

How to fetch the card

Item Value
Agent Card URL https://api.agentrux.com/.well-known/agent-card.json
Legacy alias https://api.agentrux.com/.well-known/agent.json → 301 redirect
A2A protocol version 1.0 (v1.0.1, released 2026-03)
Content-Type application/json (cache: public, max-age=3600) 
curl https://api.agentrux.com/.well-known/agent-card.json

/.well-known/agent.json is kept for backward compatibility and 301 redirects to /.well-known/agent-card.json. New integrations should point directly at agent-card.json.

Agent Card structure

The main fields returned are:

Field Contents
name "AgenTrux"
description Short description for agents (authenticated short-lived Pub/Sub)
supportedInterfaces [{ "url": "https://api.agentrux.com/a2a", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }]
version Agent Card version ("1.0.0")
provider { "organization": "AgenTrux", "url": "<console URL>" }
documentationUrl "https://docs.agentrux.com"
iconUrl https://agentrux.com/agentrux-mark.svg
capabilities See below
defaultInputModes / defaultOutputModes ["application/json"]
securitySchemes / security Auth scheme — see below
skills Offered skills — see below

capabilities

{
  "streaming": false,
  "pushNotifications": false,
  "extendedAgentCard": false
}

The declaration matches the implementation exactly: the A2A endpoint is a stateless binding. It never creates Tasks, does not stream (message/stream), and does not store push-notification configs. What you see in capabilities is what the endpoint actually does.

The A2A endpoint (POST /a2a)

https://api.agentrux.com/a2a accepts A2A JSON-RPC 1.0 requests with a Bearer JWT (see security below). Requests must carry an A2A-Version: 1.0 header (or ?A2A-Version=1.0); other versions get -32009 VersionNotSupportedError.

Method Behavior
SendMessage Publishes the event carried in the message and returns a direct reply Message (no Task is created)
GetTask, CancelTask Always -32001 TaskNotFoundError (this agent never creates tasks)
ListTasks Always an empty list (stateless: there are never any tasks)
SendStreamingMessage, SubscribeToTask, GetExtendedAgentCard -32004 UnsupportedOperationError (capabilities are declared false)
CreateTaskPushNotificationConfig and the other push-config methods -32003 PushNotificationNotSupportedError
Others (including old 0.3 names like message/send) -32601 MethodNotFoundError (with a hint to the 1.0 name)

Calling SendMessage

Send exactly one data part whose data carries the Topic, event type, and payload (in 1.0, parts are a flat oneof — no kind field):

curl -X POST https://api.agentrux.com/a2a \
  -H "Authorization: Bearer aat_..." \
  -H "A2A-Version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "c2f7…(any uuid)",
        "role": "ROLE_USER",
        "parts": [{
          "data": {
            "topic": "top_your-topic-id",
            "event_type": "ask",
            "payload": { "q": "hello" }
          }
        }]
      }
    }
  }'

The response is a direct Message (not a Task) containing the published event id:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "message": {
      "messageId": "…",
      "role": "ROLE_AGENT",
      "parts": [{ "data": { "event_id": "evt_…", "topic": "top_…", "event_type": "ask" },
                  "mediaType": "application/json" }]
    }
  }
}

Notes:

securitySchemes / security

"securitySchemes": {
  "bearer_jwt": { "httpAuthSecurityScheme": { "scheme": "bearer", "bearerFormat": "JWT" } }
},
"securityRequirements": [{ "schemes": { "bearer_jwt": { "list": ["topic.write"] } } }]

Authentication uses a Bearer JWT (access token) issued by OAuth 2.1. The token-acquisition steps are discoverable from the Authorization Server Metadata (https://api.agentrux.com/.well-known/oauth-authorization-server). Authentication and authorization failures are returned at the HTTP layer (401 / 403), not as JSON-RPC errors.

skills

id name Description Required scope Reachable via
publish_event Publish Event Publish an inline JSON event (≤256 KiB) to a Topic topic.write A2A SendMessage or MCP
read_events Read Events Read a Topic with cursor pagination + event_type filter topic.read MCP
get_event Get Event Fetch a single event by event_id topic.read MCP
list_topics List Topics List Topics accessible to the connected workspace — MCP
list_grants List Grants List Grants for the connected Script — MCP

skills[] in the card is descriptive metadata about what the agent can do. The A2A binding executes the publish skill; read-side skills are served over the MCP interface listed in x_agentrux_discovery.mcp.

From discovery to use

1. GET /.well-known/agent-card.json
   → read name / url / skills / securitySchemes

2. Confirm the auth scheme from security → obtain an OAuth 2.1 access token
   (discover endpoints via GET /.well-known/oauth-authorization-server)

3. POST /a2a with the Bearer JWT + `A2A-Version: 1.0`: SendMessage publishes an event
   (for reads, connect to the MCP interface from x_agentrux_discovery.mcp)

AgenTrux extension fields

The A2A spec allows extension fields. AgenTrux provides the following under the x_agentrux_* prefix.

Related links