Multi-Agent API

---

GraphBuilder

from elsai.multiagent import GraphBuilder

Builder for constructing a Graph. Add nodes and edges, configure limits and hooks, then call .build().

GraphBuilder.add_node

builder.add_node(executor, node_id=None)

Add an Agent (or other MultiAgentBase instance) as a node. Returns the GraphNode instance. Auto-generates node_id from the executor's id or name when omitted.

GraphBuilder.add_edge

builder.add_edge(source, target, condition=None)

Create a directed edge so target runs after source and receives its output. Pass node ID strings or GraphNode objects returned from add_node() — not raw Agent instances.

GraphBuilder.set_max_node_executions

builder.set_max_node_executions(3)

Cap total node executions. Required for cyclic graphs.

GraphBuilder.set_session_manager

builder.set_session_manager(session_manager)

Attach a SessionManager for persistence across invocations.

GraphBuilder.set_hook_providers

builder.set_hook_providers([hook_provider])

Register HookProvider instances for multi-agent lifecycle events.

GraphBuilder.build

graph = builder.build()

Returns a runnable Graph instance.

---

Graph

from elsai.multiagent.graph import Graph

Deterministic, dependency-driven agent orchestration. Construct via GraphBuilder.build().

Graph.__call__

result = graph(prompt)

Execute the graph synchronously.

Graph.invoke_async

result = await graph.invoke_async(prompt)

Execute the graph asynchronously.

GraphResult

result.status              # "completed" | "failed" | "interrupted"
result.results             # dict[str, NodeResult]: per-node results
result.accumulated_usage   # Usage dict with inputTokens, outputTokens, totalTokens
result.accumulated_metrics # Metrics dict with latencyMs
result.execution_time      # int: total time in ms
result.total_nodes         # GraphResult only
result.execution_order     # GraphResult only: list of GraphNode

Each NodeResult exposes result (an AgentResult, nested MultiAgentResult, or Exception), status, execution_time, and accumulated_usage.

---

Swarm

from elsai.multiagent import Swarm

Autonomous, collaborative agent orchestration.

Swarm.__init__

Swarm(
    nodes,
    *,
    entry_point=None,
    max_handoffs=20,
    max_iterations=20,
    execution_timeout=900.0,
    node_timeout=300.0,
    id="default_swarm",
    hooks=None,
    plugins=None,
    session_manager=None,
    trace_attributes=None,
)

Parameter	Type	Description
nodes	list[Agent]	Agents in the swarm
entry_point	Agent | None	Agent to start with; defaults to the first node
max_handoffs	int	Maximum handoffs between agents (default 20)
max_iterations	int	Maximum node executions within the swarm (default 20)
execution_timeout	float	Total swarm timeout in seconds (default 900.0)
node_timeout	float	Per-node execution timeout in seconds (default 300.0)
id	str	Swarm identifier for session management
hooks	list | None	Lifecycle hooks
plugins	list | None	Plugins attached to the swarm
session_manager	SessionManager | None	Session backend for persistence
trace_attributes	dict | None	OpenTelemetry attributes for tracing

Swarm.__call__

result = swarm(prompt)

Swarm.invoke_async

result = await swarm.invoke_async(prompt)

SwarmResult

Extends GraphResult with:

result.node_history   # list[SwarmNode]: handoff sequence

---

Agent.as_tool

tool = agent.as_tool(
    *,
    name=None,
    description=None,
    preserve_context=False,
    mode="reject",
)

Wraps the agent as an AgentTool that can be passed to another agent's tools parameter.

Parameter	Default	Description
name	agent.name	Tool name shown to the model
description	agent.description	Tool description
preserve_context	False	Preserve conversation history between calls
mode	"reject"	Concurrency when the same tool is invoked in parallel: reject, queue, or spawn

Passing tools=[sub_agent] auto-wraps with mode="reject". For parallel calls to the same specialist, use sub_agent.as_tool(mode="spawn") or mode="queue".

See Agent as Tool — Concurrent invocation.

---

Multi-agent hooks

from elsai.hooks import (
    BeforeNodeCallEvent,
    AfterNodeCallEvent,
    MultiAgentInitializedEvent,
    BeforeMultiAgentInvocationEvent,
    AfterMultiAgentInvocationEvent,
)

BeforeNodeCallEvent

Fires before each node starts executing.

Attribute	Type	Description
source	MultiAgentBase	The graph or swarm orchestrator
node_id	str	ID of the node about to execute
invocation_state	dict | None	Invocation context
cancel_node	bool | str	Writable — cancel this node when set

AfterNodeCallEvent

Fires after each node finishes.

Attribute	Type	Description
source	MultiAgentBase	The graph or swarm orchestrator
node_id	str	ID of the node that just completed
invocation_state	dict | None	Invocation context

---

A2A

Agent-to-Agent protocol support (A2A Protocol v1.0, a2a-sdk>=1.0.0). Requires elsai-agents[a2a]>=0.3.0.

• Agent-to-Agent (A2A) — usage, session isolation, migration from v0.3
• A2A API — A2AServer, A2AAgent, A2ASessionStore, stream normalizer, and handler options