API reference

Generated from the source. The public surface is small on purpose.

Building and running

Graph

Assembles a graph of communicating agents.

Two styles, mixable:

• Linear Graph().node("a", A).node("b", B) chains each node after the previous one, so A hands its message to B.
• DAG pass after=[...] to wire explicit dependencies, and barrier / k to control fan-in (agent-to-agent) join semantics.

join

join(name: str, *, after: list[str], agent: Any = None, barrier: str | BarrierKind = 'all', k: int | None = None, **kwargs: Any) -> Graph

Explicit fan-in node. Defaults to a pass-through :class:IdentityAgent.

A join ALWAYS hands its agent a dict keyed by the (surviving) upstream node names, even for a single upstream, so the input shape is stable.

run async

run(payload: Any = None, **kwargs: Any) -> Result

Convenience: compile and run in one call.

CompiledGraph

A compiled, validated graph ready to exchange messages between agents.

spec

spec() -> dict[str, Any]

JSON-serializable topology (for babelagent inspect).

Messages and results

Message

Bases: BaseModel

The envelope passed from one agent to the next.

payload is the data itself (anything). meta carries provenance and annotations that accumulate as the message travels between agents. content_type is an optional, informational schema hint.

with_payload

with_payload(payload: Any, **meta: Any) -> Message

Return a copy carrying a new payload and merged metadata.

annotate

annotate(**meta: Any) -> Message

Return a copy with additional metadata merged in.

Result

Bases: BaseModel

What a run returns: the final output plus a full trace of the exchange.

Nodes, barriers, grading

Node dataclass

A node in the graph: an agent, its upstream dependencies, and its gate.

Wraps a single :class:Agent, an optional quality check whose grade can gate the exchange (per gate mode), an optional per-node timeout_s, the after list of upstream node names, and the fan-in barrier.

BarrierPolicy dataclass

Verdict

Bases: str, Enum

A node's quality judgement.

worst classmethod

worst(verdicts: list[Verdict]) -> Verdict

The most severe verdict in a set (PASS if empty).

Grade

Bases: BaseModel

The outcome of a node Check: a verdict plus a human reason.

GateMode

Bases: str, Enum

How a node's Check grade affects the exchange.

OFF class-attribute instance-attribute

OFF = 'off'

Run the check for its verdict, but never block (advisory only).

WARN class-attribute instance-attribute

WARN = 'warn'

Block only on FAIL; WARN passes through.

STRICT class-attribute instance-attribute

STRICT = 'strict'

Block on WARN or FAIL.

The agent interface

Agent

Bases: Protocol

A participant in the graph.

Anything a user brings, a callable, an HTTP/OpenAPI endpoint, an MCP tool, a framework agent, or an LLM, is adapted to this single async interface so it can exchange messages with every other agent.

Context dataclass

Run-scoped context threaded through every node in the graph.

state is a shared blackboard for the run. deadline (a time.monotonic() value) bounds the whole run; individual nodes may also carry their own timeout.

remaining

remaining() -> float | None

Seconds left before the run deadline, or None if unbounded.

Adapters

adapt

adapt(obj: Any, *, name: str | None = None, **hints: Any) -> Agent

Return an :class:Agent for obj, inferring the right adapter.

Resolution order: already-an-Agent → custom/entry-point registrations → MCP ref → A2A ref → framework agent → HTTP/OpenAPI → plain callable.

register_adapter

register_adapter(name: str, matches: Matcher, build: Builder) -> None

Register a custom adapter. Later registrations take precedence.

A2ARef dataclass

A reference to a remote A2A agent by base URL (recognized by adapt()).

McpRef dataclass

A reference to an MCP tool: a stdio server command + a tool name.

LLM

A prompt-in / text-out worker backed by an LLM provider.

The node's input payload is substituted into prompt via {input} (or sent as the whole user message when prompt is omitted).