Agents and Workflows

Multi-agent orchestration, nested agents, and A2A protocol tools.

← Prebuilt Tools overview

Tool	Extra	Description
graph	base	Multi-agent graphs with nodes and handoff edges.
agent_graph	base	Persistent agent graphs with shared state.
journal	base	Daily markdown journal files and execution logs on disk.
write_todos	base	Session task list on agent.state["todos"] for multi-step agent work.
swarm	base	Coordinate specialist agents with handoffs.
handoff_to_user	base	Pause for human input or full handoff.
use_agent	base	Spawn a nested agent event loop.
think	base	Parallel reasoning branches.
use_llm	base	Nested LLM call with custom prompt.
workflow	base	Sequenced task pipelines with dependencies.
batch	base	Invoke multiple tools in one model turn.
a2a_discover_agent	a2a-client	Discover remote A2A agents. Register via A2AClientToolProvider.
a2a_list_discovered_agents	a2a-client	List discovered A2A agents.
a2a_send_message	a2a-client	Send a message to a remote A2A agent.

---

graph

Multi-agent graphs with nodes and handoff edges.

from elsai_tools.graph import graph

Parameter	Type	Required	Description
action	str	Yes	create, execute, status, list, or delete
graph_id	str	No	Graph identifier
topology	Dict	No	Nodes and edges
task	str	No	Task for execute
model_provider	str	No	Model provider
tools	List[str]	No	Tool names

A2A isolation

On A2A servers, graph declares PER_CONTEXT scope. Each context_id gets its own GraphTool instance. Graph IDs are automatically prefixed with the context_id so in-memory graph definitions cannot collide across concurrent conversations.

Using on an A2A server

from elsai import Agent

# Register the tool on the template agent; PER_CONTEXT cloning is automatic.
agent = Agent(tools=[...])  # e.g. tools=[python_repl], tools=[graph], …

Full A2AServer + session-manager wiring lives in Concepts — see Stateful prebuilt tools — examples.

• Graph IDs from the model are auto-prefixed: graph_id="research" becomes "<context_id>:research".
• Two A2A clients cannot see each other's in-memory graphs even with the same logical ID.

See Stateful tools on A2A and Stateful prebuilt tools — examples.

agent_graph

Persistent agent graphs with shared state.

from elsai_tools.agent_graph import agent_graph

Parameter	Type	Required	Description
action	str	Yes	Graph action
graph_id	str	No	Graph identifier
topology	dict	No	Graph topology
task	str	No	Execution task
message	str	No	Message to send

journal

Daily markdown journal files and execution logs stored on disk under ./journal/.

from elsai_tools.journal import journal

Parameter	Type	Required	Description
action	str	Yes	Journal action
task	str	No	Task entry
log	str	No	Log entry
date	str	No	Date filter

write_todos

Session task tracking for complex multi-step agent work. Each call replaces the full todo list stored on agent.state["todos"]. Pass an empty list to clear todos.

from elsai_tools.write_todos import write_todos

Parameter	Type	Required	Description
todos	List[Todo]	Yes	Full todo list (replaces the previous list)

Todo item

Field	Type	Required	Description
content	str	Yes	Task description (non-empty; leading and trailing whitespace is stripped)
status	str	Yes	pending, in_progress, or completed

Distinct from journal

journal appends markdown notes and checkbox tasks to daily journal files on disk. write_todos stores structured todos in agent state for the current session.

Usage

Register write_todos on Agent(tools=[...]) and send a multi-step prompt — the model calls the tool during the agent loop. Todos are stored on agent.state["todos"]. For programmatic calls without the LLM, use agent.tool.write_todos(todos=[...]).

See Prebuilt Tools — Task tracking (write_todos) for an example.

When a session manager is configured, agent.state["todos"] is saved and restored across process restarts. See Persisting state across sessions.

swarm

Coordinate specialist agents with handoffs.

from elsai_tools.swarm import swarm

Parameter	Type	Required	Description
task	str	Yes	Task description
agents	List[Dict[str, Any]]	Yes	List of agent configs
max_handoffs	int	No	Max handoffs
max_iterations	int	No	Max iterations
execution_timeout	float	No	Total timeout in seconds

handoff_to_user

Pause for human input or full handoff.

from elsai_tools.handoff_to_user import handoff_to_user

Parameter	Type	Required	Description
message	str	Yes	Message to show the user
breakout_of_loop	bool	No	Exit agent loop entirely

use_agent

Spawn a nested agent event loop.

from elsai_tools.use_agent import use_agent

Parameter	Type	Required	Description
prompt	str	Yes	User prompt
system_prompt	str	Yes	System prompt
tools	List[str]	No	Tool names
model_provider	str	No	Model provider
model_settings	Dict[str, Any]	No	Model settings dict

think

Parallel reasoning branches.

from elsai_tools.think import think

Parameter	Type	Required	Description
thought	str	Yes	Reasoning prompt
cycle_count	int	Yes	Number of branches
system_prompt	str	Yes	System prompt
tools	List[str]	No	Tool names
model_provider	str	No	Model provider

use_llm

Nested LLM call with custom prompt.

from elsai_tools.use_llm import use_llm

Parameter	Type	Required	Description
prompt	str	Yes	LLM prompt
system_prompt	Any	No	System prompt
model_provider	Any	No	Model provider
model_settings	Any	No	Model settings dict

workflow

Sequenced task pipelines with dependencies.

from elsai_tools.workflow import workflow

Parameter	Type	Required	Description
action	str	Yes	Workflow action
workflow_id	str	No	Workflow identifier
tasks	List[Dict[str, Any]]	No	Task definitions with dependencies

A2A isolation

On A2A servers, workflow declares PER_CONTEXT scope. Each context_id gets its own WorkflowTool instance. Workflow definitions are stored under:

$ELSAI_A2A_SESSION_DIR/<context_id>/workflows/

Workflow IDs are prefixed with the context_id.

Using on an A2A server

from elsai import Agent

# Register the tool on the template agent; PER_CONTEXT cloning is automatic.
agent = Agent(tools=[...])  # e.g. tools=[python_repl], tools=[graph], …

Full A2AServer + session-manager wiring lives in Concepts — see Stateful prebuilt tools — examples.

• Workflow files: $ELSAI_A2A_SESSION_DIR/<context_id>/workflows/
• Workflow IDs are prefixed with context_id the same way as graph.

See Stateful tools on A2A and Stateful prebuilt tools — examples.

batch

Invoke multiple tools in one model turn.

from elsai_tools.batch import batch

Parameter	Type	Required	Description
tool_calls	list[dict]	Yes	List of tool invocations

a2a_discover_agent

Discover remote A2A agents. Register via A2AClientToolProvider. Uses A2A Protocol v1.0 internally (a2a-sdk>=1.0.0).

from elsai_tools.a2a_client import A2AClientToolProvider

provider = A2AClientToolProvider(known_agent_urls=["http://agent.example.com"])
agent = Agent(tools=provider.tools)

Extra: a2a-client

Parameter	Type	Required	Description
url	str	Yes	A2A agent endpoint URL

a2a_list_discovered_agents

List discovered A2A agents.

Extra: a2a-client

No parameters.

a2a_send_message

Send a message to a remote A2A agent.

Extra: a2a-client

Parameter	Type	Required	Description
message_text	str	Yes	Message content
target_agent_url	str	Yes	Agent endpoint URL
message_id	str	No	Optional message ID