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
  behaves
    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
  expresses
    a2a
      methods: ["tasks/send", "tasks/get"]
  ensures
    permissions
      allowed to
        model
        network.http
  verifies
    test "researches a topic"
      assuming research {findings: ["Finding 1"], summary: "Brief research summary", sources: ["source1.com"]}
      given {topic: "quantum computing", depth: "deep"}
      expect {summary: "Brief research summary"}

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

  responds with
    summary as text
    sources as list

  behaves
    ask research_results, from: "a2a://research_agent"
      topic: "quantum computing"
      depth: "deep"
      returns
        summary as text
        sources as list

  verifies
    test "delegates research over a2a"
      assuming research_results {summary: "Research complete", sources: []}
      given {}
      expect {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 computer 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

  accepts
    query as text, is required

  responds with
    summary as text

  behaves
    ask agents, from: "@mashin/actions/http/get"
      url: "https://partner.mashin.live/.well-known/agent-card.json"
      returns
        agents as list

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

  verifies
    test "discovers agents and delegates"
      assuming agents {agents: [{name: "research_agent"}]}
      assuming result {summary: "Done."}
      given {query: "quantum"}
      expect {summary: "Done."}

Parallel delegation

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

machine parallel_research

  accepts
    topics as list, is required

  responds with
    combined as text

  behaves
    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")}

  verifies
    test "aggregates summaries across topics"
      assuming result {summary: "S"}
      given {topics: ["a", "b"]}
      expect {combined: "S\n\nS"}

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:

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

Governance

A2A interactions are fully governed:

1. The Agent Card declares the agent’s capabilities and security requirements
2. Incoming tasks are authenticated per the card’s securitySchemes
3. Inputs are validated against the machine’s accepts contract
4. Governance permissions are checked
5. A SurfaceAccess event is recorded with :a2a surface
6. 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 computer’s key, and the key ID is the computer’s fingerprint.

Next steps

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