Agents and workflows

Tools

Nested agent/LLM tools resolve model settings from env when model_provider="env". LITELLM_API_KEY is marked optional* because it is only required for the LiteLLM provider.

`graph`

Build and run multi-agent graphs with defined nodes, edges, and handoff topology

Environment variables

Variable	Required	Default	Description
`LITELLM_API_KEY`	optional*	—	LiteLLM API key — required only when `ELSAI_PROVIDER=litellm`
`ELSAI_PROVIDER`	optional	`bedrock`	Provider name (`bedrock`, `anthropic`, `openai`, `ollama`, `litellm`, …)
`ELSAI_MODEL_ID`	optional	provider-specific	Model or deployment ID
`ELSAI_MAX_TOKENS`	optional	provider-specific	Max tokens for nested calls
`ELSAI_TEMPERATURE`	optional	provider-specific	Sampling temperature
`LITELLM_BASE_URL`	optional	—	Optional LiteLLM proxy base URL

`agent_graph`

Create, update, and execute persistent agent graphs with shared state across nodes

Environment variables

No dedicated environment variables.

`journal`

Maintain daily markdown journal files and execution logs on disk that agents can read and append to over time

Environment variables

No dedicated environment variables.

`write_todos`

Track structured in-session todos on agent state for complex multi-step tasks (distinct from disk-based journal)

Environment variables

No dedicated environment variables.

In-session task tracking

For in-session task tracking (not multi-agent orchestration), use write_todos to store structured todos on agent.state["todos"]. The model calls the tool during the agent loop on multi-step prompts. For persistent daily notes on disk, use journal.

Requires OPENAI_API_KEY and:

bash

pip install --extra-index-url https://elsai-agents.elsai.ai/root/ elsai-agents==0.3.1
pip install --extra-index-url https://core-packages.elsai.ai/root/ "elsai-model[openai]==2.1.0"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ elsai-agents-tools==0.3.0

python

import json
import os

from elsai import Agent
from elsai.agent import AgentConfig
from elsai_model.openai import OpenAIModel
from elsai_tools.write_todos import write_todos

agent = Agent(
    model=OpenAIModel(
        model_id="gpt-4o-mini",
        client_args={"api_key": os.environ["OPENAI_API_KEY"]},
    ),
    tools=[write_todos],
    system_prompt=(
        "Use write_todos to track progress on multi-step tasks. "
        "After using tools, answer the user clearly in plain text."
    ),
    config=AgentConfig(name="todo_assistant"),
)

result = agent(
    "Break this down into steps: gather requirements, draft a plan, then list test cases."
)
print(result)
print(json.dumps(agent.state.get("todos"), indent=2))

Parameter reference: write_todos API.

`swarm`

Coordinate a team of specialist agents that hand off to each other until the task is complete

Environment variables

Variable	Required	Default	Description
`LITELLM_API_KEY`	optional*	—	LiteLLM API key — required only when `ELSAI_PROVIDER=litellm`
`ELSAI_PROVIDER`	optional	`bedrock`	Provider name (`bedrock`, `anthropic`, `openai`, `ollama`, `litellm`, …)
`ELSAI_MODEL_ID`	optional	provider-specific	Model or deployment ID
`ELSAI_MAX_TOKENS`	optional	provider-specific	Max tokens for nested calls
`ELSAI_TEMPERATURE`	optional	provider-specific	Sampling temperature
`LITELLM_BASE_URL`	optional	—	Optional LiteLLM proxy base URL

`handoff_to_user`

Pause the agent loop and wait for human input, or fully hand control back to the user

Environment variables

No dedicated environment variables.

`use_agent`

Spawn a nested agent with its own tools and system prompt inside the current event loop

Environment variables

Variable	Required	Default	Description
`LITELLM_API_KEY`	optional*	—	LiteLLM API key — required only when `ELSAI_PROVIDER=litellm`
`ELSAI_PROVIDER`	optional	`bedrock`	Provider name (`bedrock`, `anthropic`, `openai`, `ollama`, `litellm`, …)
`ELSAI_MODEL_ID`	optional	provider-specific	Model or deployment ID
`ELSAI_MAX_TOKENS`	optional	provider-specific	Max tokens for nested calls
`ELSAI_TEMPERATURE`	optional	provider-specific	Sampling temperature
`LITELLM_BASE_URL`	optional	—	Optional LiteLLM proxy base URL

`think`

Run parallel reasoning branches and merge results — useful for exploring multiple approaches

Environment variables

Variable	Required	Default	Description
`LITELLM_API_KEY`	optional*	—	LiteLLM API key — required only when `ELSAI_PROVIDER=litellm`
`ELSAI_PROVIDER`	optional	`bedrock`	Provider name (`bedrock`, `anthropic`, `openai`, `ollama`, `litellm`, …)
`ELSAI_MODEL_ID`	optional	provider-specific	Model or deployment ID
`ELSAI_MAX_TOKENS`	optional	provider-specific	Max tokens for nested calls
`ELSAI_TEMPERATURE`	optional	provider-specific	Sampling temperature
`LITELLM_BASE_URL`	optional	—	Optional LiteLLM proxy base URL

`use_llm`

Call a nested LLM with a custom prompt, separate from the main agent conversation

Environment variables

Variable	Required	Default	Description
`LITELLM_API_KEY`	optional*	—	LiteLLM API key — required only when `ELSAI_PROVIDER=litellm`
`ELSAI_PROVIDER`	optional	`bedrock`	Provider name (`bedrock`, `anthropic`, `openai`, `ollama`, `litellm`, …)
`ELSAI_MODEL_ID`	optional	provider-specific	Model or deployment ID
`ELSAI_MAX_TOKENS`	optional	provider-specific	Max tokens for nested calls
`ELSAI_TEMPERATURE`	optional	provider-specific	Sampling temperature
`LITELLM_BASE_URL`	optional	—	Optional LiteLLM proxy base URL

`workflow`

Define and execute sequenced task pipelines with dependencies and priority ordering

Environment variables

Variable	Required	Default	Description
`LITELLM_API_KEY`	optional*	—	LiteLLM API key — required only when `ELSAI_PROVIDER=litellm`
`ELSAI_PROVIDER`	optional	`bedrock`	Provider name (`bedrock`, `anthropic`, `openai`, `ollama`, `litellm`, …)
`ELSAI_MODEL_ID`	optional	provider-specific	Model or deployment ID
`ELSAI_MAX_TOKENS`	optional	provider-specific	Max tokens for nested calls
`ELSAI_TEMPERATURE`	optional	provider-specific	Sampling temperature
`LITELLM_BASE_URL`	optional	—	Optional LiteLLM proxy base URL
`ELSAI_WORKFLOW_DIR`	optional	`~/.elsai/workflows`	Where workflow definitions are stored
`ELSAI_WORKFLOW_MIN_THREADS`	optional	`2`	Minimum worker threads
`ELSAI_WORKFLOW_MAX_THREADS`	optional	`8`	Maximum worker threads
`ELSAI_WORKFLOW_CPU_THRESHOLD`	optional	`80`	CPU % above which workers scale down

`batch`

Invoke multiple tools in a single model turn, reducing round-trips for compound operations

Environment variables

No dedicated environment variables.

`a2a_discover_agent`

Discover remote agents that expose the Agent-to-Agent (A2A) protocol on a given endpoint

Extra: a2a-client

Environment variables

No dedicated environment variables.

`a2a_list_discovered_agents`

List agents previously discovered via A2A, with their capabilities and endpoints

Extra: a2a-client

Environment variables

No dedicated environment variables.

`a2a_send_message`

Send a task or message to a remote A2A agent and receive its response

Extra: a2a-client

Environment variables

No dedicated environment variables.

Examples

Graph / swarm / workflow tools

Requires OPENAI_API_KEY.

bash

pip install --extra-index-url https://elsai-agents.elsai.ai/root/ elsai-agents==0.3.1
pip install --extra-index-url https://core-packages.elsai.ai/root/ "elsai-model[openai]==2.1.0"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ elsai-agents-tools==0.3.0

python

import os

from elsai import Agent
from elsai.agent import AgentConfig
from elsai_model.openai import OpenAIModel
from elsai_tools.graph import graph

agent = Agent(
    model=OpenAIModel(
        model_id="gpt-4o-mini",
        client_args={"api_key": os.environ["OPENAI_API_KEY"]},
    ),
    tools=[graph],
    system_prompt=(
        "Use the graph tool to create a small pipeline when the user asks for "
        "multi-step research and writing. After using tools, answer clearly."
    ),
    config=AgentConfig(name="graph_assistant"),
)

result = agent(
    "Create a two-node graph (researcher → writer) and run it on: "
    "Summarize the top three AI agent trends for 2026."
)
print(result)

A2A client tools

Optional extra for A2A tools (uses A2A Protocol v1.0 via a2a-sdk>=1.0.0; requires elsai-agents[a2a]>=0.3.1):

bash

pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[a2a-client]==0.3.0"

Parameter reference: Agents and workflows API.

Prebuilt Tools

Agents and workflows

Tools

`graph`

Environment variables

`agent_graph`

Environment variables

`journal`

Environment variables

`write_todos`

Environment variables

In-session task tracking

`swarm`

Environment variables

`handoff_to_user`

Environment variables

`use_agent`

Environment variables

`think`

Environment variables

`use_llm`

Environment variables

`workflow`

Environment variables

`batch`

Environment variables

`a2a_discover_agent`

Environment variables

`a2a_list_discovered_agents`

Environment variables

`a2a_send_message`

Environment variables

Examples

Graph / swarm / workflow tools

A2A client tools

See also

elsai Docs Assistant

Agents and workflows ​

Tools ​

graph ​

Environment variables ​

agent_graph ​

Environment variables ​

journal ​

Environment variables ​

write_todos ​

Environment variables ​

In-session task tracking ​

swarm ​

Environment variables ​

handoff_to_user ​

Environment variables ​

use_agent ​

Environment variables ​

think ​

Environment variables ​

use_llm ​

Environment variables ​

workflow ​

Environment variables ​

batch ​

Environment variables ​

a2a_discover_agent ​

Environment variables ​

a2a_list_discovered_agents ​

Environment variables ​

a2a_send_message ​

Environment variables ​

Examples ​

Graph / swarm / workflow tools ​

A2A client tools ​

See also ​

Agents and workflows

Tools

`graph`

Environment variables

`agent_graph`

Environment variables

`journal`

Environment variables

`write_todos`

Environment variables

In-session task tracking

`swarm`

Environment variables

`handoff_to_user`

Environment variables

`use_agent`

Environment variables

`think`

Environment variables

`use_llm`

Environment variables

`workflow`

Environment variables

`batch`

Environment variables

`a2a_discover_agent`

Environment variables

`a2a_list_discovered_agents`

Environment variables

`a2a_send_message`

Environment variables

Examples

Graph / swarm / workflow tools

A2A client tools

See also