Running the examples
Clone the repository, install it, and run the examples from its root: recordings, agent definitions and data files are found from there.
git clone https://github.com/cchinchilla-dev/agentloom.gitcd agentloompip install -e . # the package that matches these examplesagentloom run examples/41_agent.yaml --liteExamples 35 to 41 name the mock provider and replay a recording from recordings/: no key, no network, the same answers every time. --lite skips the observability exporter.
export OPENAI_API_KEY=sk-...agentloom run examples/02_chain_of_thought.yamlMost examples name OpenAI’s gpt-4o-mini in their config; the list below says which need another provider or files of their own.
export ANTHROPIC_API_KEY=sk-ant-...agentloom run examples/02_chain_of_thought.yaml --provider anthropic --model claude-haiku-4-5-20251001Pass the model too: the model name picks the provider.
ollama pull phi4agentloom run examples/02_chain_of_thought.yaml --provider ollama --model phi4Free and local; small models follow long prompts less closely than the ones the examples were written for.
Before a run, agentloom validate examples/<file> checks a file and agentloom visualize examples/<file> draws its DAG.
Basics
One idea each: the shape of a workflow, a chain, a branch, a tool.
One LLM call that answers a question from the state: config, state and an output, and nothing else. Runs on Ollama with
phi4.Three calls in sequence: break a question down, research each part, synthesize an answer. Each step reads what the previous one wrote. OpenAI.
Classifies a customer’s message and routes it to a billing, technical or general handler; only the chosen branch runs. OpenAI.
Fetches JSON with the built-in
http_requesttool, then has a model analyze it. OpenAI.
Pipelines
Realistic workflows: parallel checks that join, a router at the end, subworkflows for repeated tracks. They use placeholder APIs, so the HTTP steps show the shape rather than real data.
Toxicity, PII and policy checks run in parallel, then a router approves, escalates to a person or rejects. Eight steps in four layers, at most three at once. OpenAI.
Enriches a lead through an API, scores its buying intent and routes it to outreach, nurture or archive. OpenAI.
Correlates a deployment with an alert, classifies the severity as P1, P2 or P3 and drafts a page, a ticket or a backlog item. OpenAI.
A four-step chain over a SaaS agreement: extract the clauses, assess the risk, compare with industry standards, summarize. OpenAI.
Two parallel fetches, four parallel fraud checks and a risk score; high-risk orders go to a nested investigation subworkflow. Eleven steps in five layers. OpenAI.
Three localization subworkflows, Spanish, German and Japanese, run in parallel, four steps each, then a review and a deployment manifest. Eighteen steps in all. OpenAI.
Coverage and fraud checks run as subworkflows beside a medical review; the result routes to automatic approval, with its own payment subworkflow, an adjuster or a denial. Eighteen steps in six layers. OpenAI.
Tools
The built-in tools, and tools of your own.
Two
shell_commandsteps gather error logs and system metrics in parallel (cannedechooutput, so it runs anywhere), then a model correlates them and a router acts on the severity. OpenAI.Writes its own input files with
file_write, reads them back withfile_read, analyzes SLA compliance and writes a report, all under/tmp/agentloom-demo/. OpenAI.14 · Custom tools with a decorator
Tools defined as decorated Python functions, with their schema generated from the signature. Run the Python file next to it,
python examples/14_custom_tools_decorator.py, which registers the tools and loads the YAML. Ollama withphi4.The same idea with tools that subclass
BaseTool; runpython examples/15_custom_tools_subclass.py. Ollama withphi4.
Resilience and sandbox
How failures surface, and what the sandbox lets a tool do.
Calls a model that doesn’t exist, so every call fails. When Ollama isn’t running at all, the connection errors are retried until the provider’s circuit breaker opens and rejects the remaining attempts. With Ollama running, the 404 is not retried and the steps fail at once.
Enables the sandbox with only
echoandcatallowed and files limited to/tmp/agentloom, then runs tools that stay inside it. OpenAI.Five tools that break the policy: a command off the list, a pipe, a path outside it. The run fails by design, and each blocked step is retried before it does. Needs no key.
Attachments
Images, PDFs and audio sent with a prompt. Providers lists which provider takes which.
AgentLoom downloads the image and sends it inline. Any vision model; the file names OpenAI’s
gpt-4o.The image is base64 data in the state: no network needed. OpenAI
gpt-4o.The URL goes to the provider, which fetches it itself; for providers that accept image URLs, OpenAI and Anthropic. OpenAI
gpt-4o.22 · Attachments in the sandbox
Only URLs from
allowed_domainsmay be fetched. OpenAIgpt-4o.Analyzes a PDF that you place at
/tmp/agentloom/sample.pdf. Anthropic or Google.Transcribes and analyzes a clip that you place at
/tmp/agentloom/recording.wav. Google, or OpenAI withgpt-4o-audio-previewand a WAV or MP3 file.
Streaming
A question answered token by token with
--stream, with usage and cost tracked as usual. OpenAI.An image description streamed as it is written. OpenAI
gpt-4o.
State, checkpoints and approval
Templates that read list items from the state, such as
{state.items[0]}. Ollama withphi4.Run it with
--checkpoint; if it fails,agentloom resume <run_id>continues from the saved state. Ollama withphi4.Drafts an email and pauses for a person. Run it with
--checkpoint, thenagentloom resume <run_id> --approveor--reject. OpenAI.The same gate, which also posts to a URL when it pauses so a chat or CI system can act on it. The URL points at
localhost, which the sandbox blocks for webhooks unlessallow_internal_webhook_targetsis set. OpenAI.
Testing and replay
Run it once with
--recordagainst a real provider, then replay the recording offline withagentloom replayor--mock-responses. Anthropic.The same replay configured in the file, with no flags:
provider: mockand aresponses_file. Needs the recording that 31 makes, atrecordings/byzantine.json.The recording declares a 429 and a 503 before the answer: every run fails the same two calls and recovers on the third attempt, through the real retry path. Offline.
Model features
The model decides to call
http_request, reads the result and answers. Offline; with--provider openai --model gpt-4o-minithe model picks the tool itself.Classifies a message into one of four intents and returns a typed object with a confidence score, from a schema in
structured_output_schemas.py. Offline, or live on any provider.Embeds a small set of documents with the
embedstep. Offline, or live with OpenAI, Google or Ollama embedding models.
Conversations and agents
Three turns of one conversation kept in the state: each step adds a user turn and the reply. Offline.
A planner and a critic take turns in one conversation, each with its own system prompt and name. Offline.
A support agent defined once in
agents/support.yaml, with its tools, a refunds agent it calls as a tool, memory and a typed reply, run for two turns. Offline.