Toolnexus.Serve (toolnexus v0.9.4)

Copy Markdown View Source

A2A (agent-to-agent) — INBOUND: serve a toolkit as a remote A2A agent (SPEC §7B), with the MCP profile co-mounted at /mcp (SPEC §7C).

Toolnexus.Toolkit.serve(toolkit, addr, opts) stands up a Bandit HTTP server that, when the a2a profile is present, exposes:

  • GET /.well-known/agent-card.json → an Agent Card built from the toolkit's skills (SKILL.md name + description), never raw tools.
  • POST / → JSON-RPC 2.0: SendMessage (submit a Task, fulfil it asynchronously via the client loop) + GetTask (poll).

A §10 suspension in the fulfilment run surfaces as the protocol's input-required Task state carrying the request prompt — never a false completed. Task persistence is a pluggable TaskStore (in-memory default; "file:<dir>" / custom via a2a.store). When neither profile is present, every request answers 404.

Summary

Functions

build_agent_card(cfg, skills, url)

Build an Agent Card from the toolkit's skills (never raw tools), filtered to a2a.skills when given. url is the JSON-RPC endpoint peers POST to.

close(handle)

Alias for stop/1.

resolve_store(store)

Map a store selector to a concrete TaskStore: nil | "memory" ⇒ in-memory (default); "file:<dir>" ⇒ file store; a struct ⇒ used as-is.

start(addr, opts)

Start the HTTP server. Delegated to by Toolnexus.Toolkit.serve/3. Options

stop(handle)

Stop the server.

Functions

build_agent_card(cfg, skills, url)

Build an Agent Card from the toolkit's skills (never raw tools), filtered to a2a.skills when given. url is the JSON-RPC endpoint peers POST to.

close(handle)

@spec close(Toolnexus.Serve.Handle.t()) :: :ok

Alias for stop/1.

resolve_store(store)

Map a store selector to a concrete TaskStore: nil | "memory" ⇒ in-memory (default); "file:<dir>" ⇒ file store; a struct ⇒ used as-is.

start(addr, opts)

@spec start(
  String.t(),
  keyword()
) :: Toolnexus.Serve.Handle.t()

Start the HTTP server. Delegated to by Toolnexus.Toolkit.serve/3. Options:

  • :a2a — the A2A profile map (mounts the card + JSON-RPC routes)
  • :skills — the toolkit's Skill.Infos, for the card
  • :run_task — (text, context_id) -> RunResult fulfilment fun
  • :on_task — fires on each Task's terminal state
  • :mcp — the MCP serve profile map (mounts /mcp)
  • :mcp_tools — the toolkit's unified tools, exposed by the MCP profile
  • :on_call — fires on each inbound MCP tools/call

When no profile is present the server answers 404 to everything.

stop(handle)

@spec stop(Toolnexus.Serve.Handle.t()) :: :ok

Stop the server.