Tools: Agent2Agent (A2A)

The a2a tool lets your Lectic interlocutor call a remote agent that implements the Agent2Agent (A2A) protocol.

This is useful for:

  • Testing the built-in lectic a2a server
  • Delegating work to an external agent process

Configuring interlocutors as A2A agents

When using lectic a2a, each interlocutor is exposed as an A2A agent. You can customize the agent ID and description with the a2a field on the interlocutor:

interlocutor:
  name: Research Assistant
  prompt: You are a research assistant.
  a2a:
    id: researcher
    description: Finds and summarizes academic papers.

If a2a.id is not set, the interlocutor’s name is used as the agent ID. The description is exposed in the agent card returned by the A2A server.

Configuration

You configure an A2A tool by providing the base URL for the agent.

If your agent card is served at:

  • http://HOST:PORT/agents/<id>/.well-known/agent-card.json

then set the tool URL to:

  • http://HOST:PORT/agents/<id>

Example:

tools:
  - name: remote_agent
    a2a: http://127.0.0.1:41240/agents/assistant

Optional settings:

  • stream: Prefer streaming (message/sendStream). Defaults to true.
  • maxWaitSeconds: When streaming, max seconds to wait for the call to reach a final event before returning early with taskId so you can poll using getTask. Defaults to 5.
  • headers: Extra HTTP headers to attach to every A2A request.
    • Header values support file: and exec: sources (same as MCP).
    • Avoid hardcoding secrets directly in YAML.

Example (bearer token loaded from an external command):

tools:
  - name: prod_agent
    a2a: https://example.com/agents/assistant
    headers:
      Authorization: exec:bash -lc 'echo "Bearer $(pass a2a/token)"'

Tool call parameters

The tool exposes these parameters:

  • op (required): operation mode.
    • sendMsg: send user text via message/send (or message/sendStream).
    • getTask: poll a long-running task via tasks/get.
  • text (required for op=sendMsg): user text to send to the agent.
  • contextId (optional): A2A context id to continue a conversation.
  • taskId:
    • required for op=getTask
    • optional for op=sendMsg (some agents may attach messages to a task)
  • stream (optional): override streaming for op=sendMsg.
  • maxWaitSeconds (optional): override the streaming max-wait for this call. When exceeded, the tool returns early with a taskId.

Example conversation

Configuration:

interlocutors:
  - name: Assistant
    prompt: >
      You coordinate with a remote research agent.
    tools:
      - name: researcher
        a2a: http://127.0.0.1:41240/agents/research

Conversation:

Find recent papers on retrieval-augmented generation.

:::Assistant

<tool-call with="researcher">
<arguments>
<op>
┆sendMsg
</op>
<text>
┆Find recent papers on retrieval-augmented generation.
</text>
</arguments>
<results>
<result type="text">
┆Here are three recent papers on RAG:
┆1. "Adaptive RAG" (Chen et al., 2025) ...
┆2. ...
</result>
<result type="application/json">
┆{
┆  "contextId": "ctx-abc123",
┆  "taskId": "task-xyz789",
┆  "agent": "research",
┆  "baseUrl": "http://127.0.0.1:41240/agents/research",
┆  "streaming": true
┆}
</result>
</results>
</tool-call>

The remote agent found three recent papers on RAG. Here's a
summary...

:::

To continue the same conversation with the remote agent, the assistant passes the contextId from the metadata in subsequent calls.

Output format

The tool returns:

  1. text/plain: the agent response text.
  2. Zero or more additional results extracted from A2A message parts and artifact updates:
    • application/pdf, image/*, etc. are returned as data: URLs when provided as bytes, or as a normal URL when provided as a URI.
    • application/json results are emitted for data parts.
  3. application/json: call metadata.

The metadata includes:

  • contextId, taskId: identifiers you can reuse
  • agent: the agent name from its agent card
  • baseUrl, streaming: call metadata