Skip to main content

​
Overview

The Bindu Gateway sits between an external system (your app, a custom frontend, another service) and one or more Bindu A2A agents. It takes a user question plus an agent catalog and returns a streaming plan: the gateway’s planner LLM decomposes the request, invokes A2A agents via the polling protocol, and emits Server-Sent Events in real time.
This is distinct from the per-agent Bindu Agent API, which describes what a single bindufy()-built agent exposes. This spec documents the gateway — the orchestrator sitting one layer up.
New to the gateway? Read the narrative walkthrough first — it takes you from “no idea what this is” to signing production requests in about 45 minutes.

​
Base URL

​
Mental model: one endpoint, many turns

Every orchestration goes through POST /plan. Inside, the planner LLM runs an agentic loop — it calls A2A agents as tools, the results feed back into the LLM, and the loop continues up to max_steps or until the plan resolves. Two auxiliary endpoints support health probing and DID-based peer authentication:

​
Request shape

A /plan request carries three things:

question

The user’s natural-language input.

agents[]

The catalog of A2A peers the planner may call — each with endpoint, auth, and skills. The gateway does not host agents.

preferences + session_id

Caps and continuation handles. Both optional.
The shape is stable and additive. Unknown top-level keys are accepted (forward-compatible .passthrough()), but preferences keys are strict snake_case. Clients sending camelCase preferences will have them silently dropped.

​
Response shape — Server-Sent Events

The happy path returns 200 OK with Content-Type: text/event-stream. Errors surface in three ways depending on when they occur:
Auth failure, invalid JSON, malformed request, session creation failure:401 / 400 / 500 with a JSON { error, detail? } body.
Planner or tool failure: a single event: error SSE frame, followed by event: done.
Every successful plan closes with event: done (empty payload). Consumers should treat the absence of done as an incomplete stream.

​
SSE events

Events emitted during a plan, in typical order:

​
Recipes (internal)

The gateway supports progressive-disclosure recipes — markdown playbooks the planner lazy-loads when a task matches (e.g., multi-agent-research, payment-required-flow). Recipes are operator-authored and not part of this HTTP API surface: they live in gateway/recipes/ and are injected automatically into the planner’s system prompt as metadata, with the body fetched on demand via an internal load_recipe tool.
You cannot upload, list, or invoke recipes via the HTTP API; they influence the planner’s behavior transparently. See the Recipes chapter for authoring details.

​
A2A protocol pass-through

The gateway speaks A2A (JSON-RPC 2.0 over HTTP) to every peer in agents[] — message/send + tasks/get polling, with DID signature verification when configured. A2A task states (submitted, working, input-required, auth-required, payment-required, completed, failed, canceled) flow through to the planner:
  • Terminal states become task.finished events.
  • Non-terminal states can surface as planner text or trigger recipe-based handling (e.g., surfacing a payment-required URL to the user).
See the Bindu Agent API spec for the full A2A protocol surface.

​
Next steps

Gateway walkthrough

The 45-minute end-to-end story.

Endpoint reference

Full schemas for /plan, /health, /.well-known/did.json are in the left sidebar under this tab.

DIDs explained

Under the hood of did_signed peer auth.

Recipes

Teach the planner reusable patterns.