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

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