a2a

Ce contenu n’est pas encore disponible dans votre langue.

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 participant in any multi-agent system.

Overview

Declaring an A2A surface does two things: it generates an Agent Card (the discovery document that describes the agent’s capabilities) and it registers a JSON-RPC endpoint where other agents can submit tasks. The Agent Card is served automatically. Other agents discover it, read the capabilities, and send tasks using standard A2A methods.

Syntax

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

A complete machine with 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"]

  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

When methods is omitted, all standard methods are enabled.

The Agent Card

Every machine with an A2A surface automatically generates an Agent Card. The card is served at:

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

The card includes the agent’s name, description, protocol version, capabilities, skills (derived from the machine’s chains), and security schemes. Skills map to the machine’s structure: a single-chain machine has one skill; a multi-chain machine has one skill per chain.

Agent Cards are signed with Ed25519, using the cell’s key. The key ID is the cell’s fingerprint, providing cryptographic proof of agent identity.

Calling an A2A agent

From another mashin machine, use ask ... from with the a2a:// prefix:

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: []

From any HTTP client, send a JSON-RPC 2.0 request to POST /a2a/rpc/{machine_slug} with a standard tasks/send payload.

Governance

A2A interactions are fully governed:

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

Cross-organization calls are governed on both sides: your machine’s ensures checks outbound permissions, and the remote agent’s governance checks inbound authorization. Both sides record the interaction.

Example

Local A2A routes work without subdomains:

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

On cloud cells, use https://myorg.mashin.live/a2a/card/research_agent for discovery and https://myorg.mashin.live/a2a/rpc/research_agent for RPC.

a2a