Surfaces: A2A

此内容尚不支持你的语言。

The a2a surface exposes a machine via the Agent-to-Agent (A2A) protocol. A2A is an open protocol for agents to discover each other, exchange tasks, and collaborate, regardless of what framework or platform they were built with. A mashin machine with an A2A surface becomes a first-class citizen in any multi-agent system.

Declaring an A2A surface

machine research_agent

  accepts
    topic as text, is required
    depth as text

  responds with
    findings as list
    summary as text
    sources as list

  ensures
    permissions
      allowed to
        reason, http

  implements
    ask research, using: "anthropic:claude-sonnet-4-6"
      with task "Research the topic '${input.topic}' at ${input.depth || 'medium'} depth"
      returns
        findings as list
        summary as text
        sources as list
      assuming
        findings: ["Finding 1", "Finding 2"]
        summary: "Brief research summary"
        sources: ["source1.com", "source2.com"]

  expresses
    a2a
      methods: ["tasks/send", "tasks/get"]

Configuration options

Config	Required	Default	Description
`methods`	No	All standard methods	Which A2A methods this agent supports

Supported methods

Method	Purpose
`tasks/send`	Submit a task to this agent
`tasks/get`	Check the status of a submitted task
`tasks/sendSubscribe`	Submit a task and receive streaming updates
`tasks/cancel`	Cancel a running task

The Agent Card

Every machine with an A2A surface automatically generates an Agent Card, the A2A discovery document. Other agents use the card to understand what this agent can do and how to interact with it.

The card is served at:

Per-machine: GET /a2a/card/{machine_slug}
Org listing: GET /.well-known/agent-card.json (lists all A2A agents)

Example card:

{
  "id": "mach_abc123",
  "name": "research_agent",
  "description": "Researches topics and returns structured findings",
  "version": "1.0.0",
  "protocolVersion": "0.3.0",
  "url": "https://myorg.mashin.live/a2a/research_agent",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true
  },
  "skills": [
    {
      "id": "research",
      "name": "Research",
      "description": "Research a topic at configurable depth",
      "inputModes": ["text/plain", "application/json"],
      "outputModes": ["text/plain", "application/json"]
    }
  ],
  "securitySchemes": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-Api-Key"
    }
  }
}

Skills are derived from the machine’s structure: its chains, MCP tools, and API endpoints. A single-chain machine has one skill. A multi-chain machine has one skill per chain.

Calling an A2A agent

Sending a task

curl -X POST https://myorg.mashin.live/a2a/rpc/research_agent \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tasks/send",
    "id": "req-1",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "Research quantum computing applications in drug discovery"}]
      }
    }
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "id": "task_xyz",
    "status": {
      "state": "completed"
    },
    "artifacts": [
      {
        "parts": [
          {"type": "text", "text": "Quantum computing is being applied to drug discovery in three key areas..."}
        ]
      }
    ]
  }
}

Getting task status

curl -X POST https://myorg.mashin.live/a2a/rpc/research_agent \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tasks/get",
    "id": "req-2",
    "params": {"id": "task_xyz"}
  }'

From mashin machines

Machines can call A2A agents using ask ... from:

machine coordinator

  implements
    ask research_results, from: "a2a://research_agent"
      topic: "quantum computing"
      depth: "deep"
      returns
        summary as text
        sources as list
      assuming
        summary: "Research complete"
        sources: []

The a2a:// prefix tells the runtime to use the A2A protocol for the call instead of direct machine invocation.

Local A2A

For development and testing, A2A routes work on your local cell without subdomains:

Discovery: GET http://localhost:9000/a2a/card/research_agent
RPC: POST http://localhost:9000/a2a/rpc/research_agent

Multi-agent patterns

Agent discovery

An orchestrator agent can discover available agents and delegate tasks:

machine orchestrator

  implements
    ask agents, from: "@mashin/actions/http/get"
      url: "https://partner.mashin.live/.well-known/agent-card.json"
      returns
        agents as list
      assuming
        agents: [{"name": "research_agent", "url": "..."}]

    ask result, from: "a2a://research_agent"
      topic: input.query
      returns
        summary as text

Parallel delegation

An orchestrator can send tasks to multiple agents and aggregate results:

machine parallel_research

  implements
    for_each topic in input.topics
      ask result, from: "a2a://research_agent"
        topic: topic
        returns
          summary as text

    compute aggregate
      let summaries = steps.result.map(r => r.summary)
      {combined: summaries.join("\n\n")}

Cross-organization

A2A enables cross-organization agent collaboration. Your agent can call an agent at another organization’s mashin instance, with governance on both sides:

Your machine’s ensures checks that it is allowed to make external calls
The remote agent’s governance checks that your request is authorized
Both sides record the interaction in their behavioral ledgers

Governance

A2A interactions are fully governed:

The Agent Card declares the agent’s capabilities and security requirements
Incoming tasks are authenticated per the card’s securitySchemes
Inputs are validated against the machine’s accepts contract
Governance permissions are checked
A SurfaceAccess event is recorded with :a2a surface
The result is returned per the A2A protocol specification

Ed25519 signatures on Agent Cards provide cryptographic proof of agent identity. The signing key is the cell’s key, and the key ID is the cell’s fingerprint.

Next steps

Pages - Web interfaces (Kanvas)
MCP - Model Context Protocol
Surfaces overview - All surface types