Agents

Defining an agent

name: support_desk
description: Answers billing questions for ACME customers.
system_prompt: |
  You answer billing questions for ACME customers. Before answering, read the
  billing policy at examples/data/billing_policy.txt with file_read. When the
  customer asks for money back, ask the refunds agent whether the charge is
  eligible. Keep the answer to one or two sentences.
tools:
  - file_read                        # a registered tool
  - name: ask_refunds                # another agent, offered as a tool
    agent: examples/agents/refunds.yaml
memory:
  token_budget: 4000
  trim_policy: drop_pairs
loop_policy:
  max_iterations: 6
  on_max_iterations: error
output_schema:
  type: pydantic
  model: examples.structured_output_schemas.SupportReply
constraints:
  max_cost_usd: 0.05
  max_latency_ms: 60000
  forbidden_patterns: ["as an AI language model"]

The file is checked when the workflow loads: unknown keys, duplicate tool names and agent files that refer to each other in a cycle are errors. An agent takes no thinking, tool_choice or stream.

The agent step

steps:
  - id: answer
    type: agent
    agent: examples/agents/support.yaml
    prompt: "{state.question}"
    conversation: state.chat
    output: reply

  - id: follow_up
    type: agent
    depends_on: [answer]
    agent: examples/agents/support.yaml
    prompt: "How long until the money is back on my card?"
    conversation: state.chat
    output: follow_up

The step also takes depends_on, retry and timeout. The fields the agent defines can’t be set on the step: model, system_prompt, temperature, max_tokens, thinking, tools, tool_choice, max_tool_iterations, response_schema and speaker are refused with an error that names them.

Paths are relative to the directory you run from, not to the workflow file, and so are the paths of agents named inside an agent file. examples/41_agent.yaml loads examples/agents/support.yaml, which loads examples/agents/refunds.yaml, and runs from the repository’s root.

A turn

A turn is an LLM call with the agent’s settings: its model, system prompt, tools and max_iterations as the tool loop’s cap, with the agent’s name as the speaker.

1. The agent’s tools are looked up. A tool that isn’t registered, the agent’s own or one of an agent it calls, fails the step before the first model call.
2. The model is called with the prompt, the conversation and only the agent’s tools. A call to any other tool, even one the workflow registers, goes back to the model as not registered.
3. Tool calls run as in an LLM call’s loop, until the model replies without calling a tool.
4. The reply is checked against output_schema and constraints. If it passes, it is written to output and to the conversation.

The agent’s system prompt applies to its own turns and isn’t stored in the conversation, so several agents can share one. Nothing is written when the turn fails.

The cap

Reaching max_iterations without a reply:

• under on_max_iterations: error, fails the step without a retry;
• under warn_and_return, returns the last reply’s text with a warning. With tools, that is the text that came with the calls still pending, such as “I’ll check the policy”, stored as it is. A last reply with no text fails the step either way.

A typed reply

With an output_schema, the reply is validated before it is accepted.

• Without tools, the provider’s structured output holds the reply to the schema, as on an LLM call. An invalid reply is asked for again, within the same max_iterations; if none validates, the step fails without a retry.
• With tools, the agent replies by calling a final_result tool whose arguments follow the schema, and the model must call a tool on every call of the turn. Invalid arguments go back to the model as the tool’s error, and a plain-text reply is sent back asking for the tool. The loop ends on the first valid final_result. No valid one within max_iterations fails the step, under either on_max_iterations. The conversation keeps the validated reply as JSON.

final_result is a reserved tool name in an agent with an output_schema, and the schema must describe an object.

Constraints

Models without a price in AgentLoom’s pricing table cost 0, so max_cost_usd never stops them. See Providers.

Memory

memory sets the conversation’s budget and trimming policy for this agent’s turns, without changing the settings the conversation stores; a field left out keeps the conversation’s own. The conversation is stored as trimmed, so agents that share it share the trim, and the smallest memory wins. To give them all one budget, set it on the conversation instead.

Retries and results

• The step’s retry repeats the whole turn after a transient failure: a provider error such as a 429, or max_latency_ms. Tools run again. A broken constraint, the cap, a missing final_result, a missing tool and a broken template fail the step for good.
• An agent turn doesn’t stream: with stream: true, the reply reaches the stream in one piece, once it has passed the checks.
• The step’s tokens and cost include the calls of agents used as tools and conversation summaries.

Agents as tools

A {name, agent} entry in tools offers another agent to the model as a tool, with one message parameter:

tools:
  - name: ask_refunds
    agent: examples/agents/refunds.yaml
    description: "Ask whether a charge can be refunded."   # the agent's own description without it

Each call runs one turn of that agent:

• on a new, empty conversation, with the call’s message as the prompt;
• with its prompts rendered against the calling workflow’s state, plus message;
• with its own model, or else the workflow’s config.model, not the calling agent’s model.

Its reply goes back to the caller as the tool’s result, as JSON with an output_schema.

• Its cost and tokens count toward the calling step’s, and toward the caller’s max_cost_usd.
• Its model calls are recorded under <step id>::<tool name>#<n>, such as answer::ask_refunds#1 for the first call of the turn, so a recording replays them in order.
• There is no depth limit: agents can call agents that call agents. Only cycles are refused.

From Python

Agent runs a turn without a workflow:

from agentloom import Agent
from agentloom.exceptions import AgentError

agent = Agent.from_yaml(
    "examples/agents/support.yaml",
    gateway=gateway,
    tool_registry=registry,
    model="claude-haiku-4-5",   # for a file that names no model
)

try:
    result = await agent.invoke("My bill seems wrong", conversation=previous)
except AgentError as err:
    print(err)

result.reply          # a SupportReply, typed per output_schema; the text without one
result.conversation   # the conversation, with the new turns
result.cost_usd       # what the turn spent, agents used as tools included
result.iterations     # the agent's own model calls

• Agent(definition, *, gateway, tool_registry=None, model=None) takes a definition already loaded; Agent.from_yaml loads one from a file. The definition’s model wins over model=, and an agent with neither is refused.
• invoke raises AgentError when the prompt is empty, when the turn can’t start, or when it fails. The conversation passed in is copied, not changed.
• There is no engine around the turn: no retries, budget or observer.

Inspecting an agent

agentloom agent inspect prints a definition as it loads, without running it:

agentloom agent inspect examples/agents/support.yaml
agentloom agent inspect examples/agents/support.yaml --json

It shows the model and its prices, the system prompt, each tool with its parameters, the agents it calls, described in turn, and the resolved JSON Schema of the output_schema. See CLI.

examples/41_agent.yaml runs the support desk above offline, two turns on one conversation.

What’s next

• LLM calls

  Tool loops, structured output and conversations, which agent turns are built on.

• Tools & sandbox

  The built-in tools, tools of your own, and what the sandbox allows.

• Testing & replay

  Recordings, replay and the inter-agent event log.