Toolnexus.A2a (toolnexus v0.9.4)

Copy Markdown View Source

A2A (agent-to-agent) — OUTBOUND: call remote A2A agents (SPEC §7A).

A remote agent publishes an Agent Card at /.well-known/agent-card.json describing its skills. Each advertised skill becomes a uniform Toolnexus.Tool (source: "a2a") whose execute performs one JSON-RPC SendMessage (non-blocking) to get a Task id, then polls GetTask until the Task reaches a terminal state — mapping the Task's artifact/message text to a ToolResult.

This is a genuine subset of real A2A (JSON-RPC 2.0 over one HTTP POST endpoint), byte-identical with js/src/a2a.ts. ${ENV_VAR} header values expand from the environment at call time and are never logged.

Summary

Functions

agent(opts)

Build an Agent descriptor pointing at a remote Agent Card URL.

agent_tools(ag)

Resolve an Agent to its tools: fetch the card, read skills[], and produce one Tool per skill (name = sanitize(card.name) <> "_" <> sanitize(skill id)). Raises on a card fetch/parse failure — the toolkit isolates it.

parse_agents_config(block)

Parse an agents config block (%{id => %{"card" => ..., ...}}, mirroring mcpServers) into Agent descriptors, skipping disabled entries (MCP isEnabled precedence: disabled: true wins, then enabled: false). The config key is only an identifier — a tool's name prefix comes from the fetched card's name, not the key. Entries are resolved in sorted-key order.

Functions

agent(opts)

@spec agent(keyword() | map()) :: map()

Build an Agent descriptor pointing at a remote Agent Card URL.

Options (keyword list or map): :card (required — the card URL), :headers (${ENV_VAR} values expand at call time, never logged), :timeout (overall poll budget in ms, default 300000), :poll_every (interval between GetTask polls in ms, default 1000).

agent_tools(ag)

@spec agent_tools(map()) :: [Toolnexus.Tool.t()]

Resolve an Agent to its tools: fetch the card, read skills[], and produce one Tool per skill (name = sanitize(card.name) <> "_" <> sanitize(skill id)). Raises on a card fetch/parse failure — the toolkit isolates it.

parse_agents_config(block)

@spec parse_agents_config(map() | nil) :: [map()]

Parse an agents config block (%{id => %{"card" => ..., ...}}, mirroring mcpServers) into Agent descriptors, skipping disabled entries (MCP isEnabled precedence: disabled: true wins, then enabled: false). The config key is only an identifier — a tool's name prefix comes from the fetched card's name, not the key. Entries are resolved in sorted-key order.