A2A Adapter

Each skill on a partner's A2A Agent Card becomes a Chio tool your agents call under grants you control. The kernel checks the caller's grant for that skill before a single A2A message leaves your host.

The adapter, chio-a2a-adapter, is the outbound side: Chio calls a remote A2A 1.x agent and governs the call. To serve your own tools as an A2A agent, use the A2A edge, chio-a2a-edge, described in Bridges.

1. Register the partner's agent with your kernel

The adapter is a Rust library that runs in your host process beside the kernel; it has no CLI of its own. Add the crate to the host.

cargo add chio-a2a-adapter

A2aAdapterConfig is a builder: set the target Agent Card URL and the manifest public key, add transport credentials and partner policy, then register the discovered adapter. The excerpt assumes an initialized kernel and a host-selected manifest key.

use chio_a2a_adapter::{A2aAdapter, A2aAdapterConfig, A2aPartnerPolicy};

let adapter = A2aAdapter::discover(
    A2aAdapterConfig::new(
        "https://agent.halden.example",
        manifest_public_key_hex,
    )
    .with_tls_root_ca_pem(tls_root_ca_pem)
    .with_mtls_client_auth_pem(
        client_cert_chain_pem,
        client_private_key_pem,
    )
    .with_request_header("X-Partner", "larkfield")
    .with_oauth_client_credentials(client_id, client_secret)
    .with_oauth_scope("a2a.invoke")
    .with_partner_policy(
        A2aPartnerPolicy::new("halden")
            .with_required_tenant("larkfield")
            .require_skill("review")
            .require_security_scheme("oauthAuth")
            .allow_interface_origin("https://agent.halden.example"),
    )
    .with_task_registry_file(".chio/a2a-task-registry.json")
)?;

kernel.register_tool_server(Box::new(adapter));

Discovery reads /.well-known/agent-card.json from a base URL, or uses a full Agent Card URL directly. Every advertised skill becomes a Chio tool, invocable through the kernel like any other tool server. Supply the partner's TLS material and OAuth credentials through your deployment configuration before discovery, and keep the task-registry directory private.

2. Admit only the agent you expect

A2aPartnerPolicy turns the partner's expected contract into discovery checks. An Agent Card that differs fails discovery, and the error names the failing tenant, interface, or scheme.

• with_required_tenant refuses a selected interface that advertises a different tenant id.
• require_skill refuses a card that does not expose the required skill id.
• require_security_scheme refuses a card whose schemes or security requirements lack the named scheme.
• allow_interface_origin refuses a card with no supported interface on an allowed origin.

The adapter sends only credentials that satisfy a security requirement the card declares. When a card demands a scheme the adapter does not implement, the invocation is refused locally, before any request goes upstream; terminate a custom scheme in front of the adapter and present one it supports.

3. Call the skill from your agent

The calling agent uses no A2A client library. It opens a Chio session with ChioClient, the lower-level session client in @chio-protocol/sdk and chio-sdk, and calls the tool the adapter published. Set CHIO_BASE_URL to the host's MCP endpoint and CHIO_AUTH_TOKEN to an authorized caller credential.

import { ChioClient } from "@chio-protocol/sdk";

const client = ChioClient.withStaticBearer(
  process.env.CHIO_BASE_URL!,
  process.env.CHIO_AUTH_TOKEN!,
);
const session = await client.initialize({
  clientInfo: { name: "larkfield-console", version: "0.1.0" },
});

try {
  const result = await session.callTool("review", {
    message: "Review PR #421 against the tests-are-evidence policy.",
    metadata: { source: "larkfield-console" },
  });
  console.log(JSON.stringify(result, null, 2));
} finally {
  await session.close();
}

import json
import os

from chio import ChioClient

client = ChioClient.with_static_bearer(
    os.environ["CHIO_BASE_URL"],
    os.environ["CHIO_AUTH_TOKEN"],
)
session = client.initialize(
    client_info={"name": "larkfield-console", "version": "0.1.0"}
)

try:
    result = session.call_tool(
        "review",
        {
            "message": "Review PR #421 against the tests-are-evidence policy.",
            "metadata": {"source": "larkfield-console"},
        },
    ).get("result", {})
    print(json.dumps(result, indent=2))
finally:
    session.close()

You should see the partner's reply as the tool result: a message for a blocking call, or an A2A task when the agent defers. The host must expose the registered review tool and grant it to this caller; without that grant, the kernel refuses the call and the partner receives nothing.

4. Follow a deferred task through the same tool

return_immediately makes the adapter return the A2A task instead of waiting for it. get_task then issues A2A GetTask on the same tool, and because follow-up modes exclude every SendMessage field, the poll carries only get_task. Run these inside the session's try block.

// The adapter answers with the A2A task rather than a terminal message.
const deferred = await session.callTool("review", {
  message: "Review the open pull requests on issues #412 to #419",
  return_immediately: true,
});

// Validate deferred and retain its returned task id as taskId before polling.
// Only `get_task` may be present in this follow-up.
const followUp = await session.callTool("review", {
  get_task: { id: taskId, history_length: 2 },
});

# The adapter answers with the A2A task rather than a terminal message.
deferred = session.call_tool(
    "review",
    {
        "message": "Review the open pull requests on issues #412 to #419",
        "return_immediately": True,
    },
).get("result", {})

# Validate deferred and retain its returned task id as task_id before polling.
# Only get_task may be present in this follow-up.
follow_up = session.call_tool(
    "review",
    {"get_task": {"id": task_id, "history_length": 2}},
).get("result", {})

You should see the deferred call return a task in TASK_STATE_WORKING and the poll return TASK_STATE_COMPLETED, the pair the adapter's own test asserts. Take the poll's taskId or task_id from the validated deferred result.

With with_task_registry_file, the adapter persists one binding per observed task id and refuses a follow-up whose task_id was not recorded for the same tool, server, binding, interface, and tenant. The binding survives adapter recreation and process restarts. It binds the route and partner context; per-caller task access remains a host or upstream check. Without a configured registry, the adapter skips this correlation check.

5. Read the receipt each hop signs

When your agent calls a partner's agent, which calls a tool at a third organization, Chio on each side signs one receipt per hop:

fixer at Larkfield
  -> a2a adapter (chio, Larkfield)   signed receipt R1
     -> a2a server (Halden's fixer-2)
        -> chio kernel (Halden)       signed receipt R2
           -> tool at a third org     signed receipt R3

The receipts link through GovernedTransactionIntent.call_chain, which your host supplies on its governed intent; the adapter passes requests through and leaves that field to the host. When the host relays a request to another organization, it carries the upstream chain_id and points the new link at the upstream request. A chain restarted at the boundary hides the upstream hops from downstream auditors.

Each link is one GovernedCallChainContext: a stable chain_id, the parent_request_id, an optional parent_receipt_id, the origin_subject at the root, and the delegator_subject that handed control to the current subject. The kernel refuses an empty chain_id, a parent_request_id equal to the current request, and an origin or delegator subject that disagrees with the validated capability lineage. Follow the parent pointers to rebuild the full path.

You should see that provenance on each signed receipt. /v1/reports/authorization-context and chio trust authorization-context list project it, alongside derived authorization-detail scope for commerce and metered-billing context.

{
  "chio": {
    "targetSkillId": "review",
    "targetSkillName": "Research"
  }
}

{
  "statusUpdate": {
    "taskId": "task-1",
    "status": {
      "state": "TASK_STATE_COMPLETED"
    }
  }
}