Tools & sandbox

The tool step

- id: fetch
  type: tool
  tool_name: http_request
  tool_args:
    url: "https://api.example.com/orders/{state.order_id}"
    method: GET
  output: order

The step also takes the fields every step has: depends_on, timeout and retry.

output receives the tool’s return value as it is: a dictionary stays a dictionary, and templates read its fields, as {state.order.status_code}. steps.<id>.output holds the same value. A tool that returns nothing writes None to output and leaves no steps.<id> entry.

agentloom validate doesn’t look tools up: a tool_name that isn’t registered passes it and fails when the run reaches the step.

When a tool step fails

An error status from http_request, such as 404 or 500, and a non-zero exit code from shell_command aren’t failures: they come back in the result, for a later step or a router to check.

Every error a tool raises is retried, a sandbox refusal included, though the next attempt is refused the same way. On a step that may be refused, set retry: {max_retries: 0}. Reliability covers retries and what a failed step does to the steps after it.

A step or the model

Built-in tools

agentloom run, and every other command that runs a workflow, registers four tools, which check every call against the workflow’s sandbox.

http_request

It returns {status_code, headers, body}, with the body as text.

• Any status is a result, not an error.
• Redirects aren’t followed: a 3xx response comes back with its location header.
• Response headers whose names contain authorization, cookie, token, secret or key are left out of the result.
• The response isn’t limited in size.

shell_command

It returns {returncode, stdout, stderr}.

• A non-zero exit code is a result, not an error.
• Past timeout, the command and every process it started are killed, and the step still succeeds, with returncode: -1 and stderr: "Command timed out".
• The output isn’t limited in size.

file_read and file_write

• Relative paths start from the directory you run from.
• file_write creates missing parent directories and replaces an existing file. content must be a string.
• file_read reads text only: a binary file fails, and so does a missing one.

Declaring them to a model

An LLM call sends the model the tools it declares, with their description and parameters as written in the step. A tool declared without parameters is sent with the registered tool’s own. An agent names its tools and sends their own description and parameters.

tools:
  - name: file_read
    description: "Read a text file."
    parameters:
      type: object
      properties:
        path: { type: string }
      required: [path]

Tools of your own

Tools of your own are written in Python and registered on a ToolRegistry. agentloom run registers only the built-in tools, so a workflow that uses yours runs, and resumes, from Python.

Defining a tool

@tool turns a function into a tool:

from agentloom.tools import tool

@tool(name="word_count", description="Count the words in a text.")
def word_count(text: str) -> dict:
    return {"words": len(text.split())}

• The name defaults to the function’s, and the description to its docstring.
• The parameters come from the type hints: str, int, float and bool, lists such as list[str], dictionaries such as dict[str, float], and Optional[...] for a value that may be null. A parameter without a hint is a string, and one without a default is required.
• A function that isn’t async runs in a worker thread, so it doesn’t block other steps.

For more control, subclass BaseTool from agentloom.tools: set name, description and parameters_schema, a JSON Schema, and implement async def execute(self, **kwargs).

A tool receives its arguments and nothing else: not the state, the run or the sandbox. Its arguments aren’t checked against its parameters, so a tool should check them itself. Return values that serialise to JSON, such as strings, numbers, lists and dictionaries: the value goes to the state, to checkpoints and to --json, and a model receives anything but a string as JSON.

Running a workflow with them

import anyio

from agentloom.core.engine import WorkflowEngine
from agentloom.core.parser import WorkflowParser
from agentloom.providers.gateway import ProviderGateway
from agentloom.providers.openai import OpenAIProvider
from agentloom.tools import ToolRegistry
from agentloom.tools.builtins import register_builtins
from agentloom.tools.sandbox import ToolSandbox

async def main() -> None:
    workflow = WorkflowParser.from_yaml("word_tools.yaml")

    registry = ToolRegistry()
    register_builtins(registry, sandbox=ToolSandbox(**workflow.config.sandbox.model_dump()))
    registry.register(word_count)

    gateway = ProviderGateway()
    gateway.register(OpenAIProvider(), priority=0)

    engine = WorkflowEngine(workflow=workflow, provider_gateway=gateway, tool_registry=registry)
    result = await engine.run()
    print(result.status, result.final_state["counted"])

anyio.run(main)

• register_builtins gives the built-in tools the sandbox you pass. Without sandbox=, they run with no limits, whatever the file’s config.sandbox says.
• Registering a name that is already taken replaces that tool, with a warning; register(tool, replace=True) replaces it quietly.
• An engine without a tool_registry fails every tool step.
• examples/14_custom_tools_decorator.py and examples/15_custom_tools_subclass.py run complete workflows with tools of their own. Python DSL covers the engine and the gateway.

The sandbox

config.sandbox limits what the built-in tools may run, read, write and reach. It is disabled by default, and the built-in tools then have the access of the process that runs AgentLoom: any command, any file and any host, internal addresses included.

config:
  sandbox:
    enabled: true
    allowed_commands: [ls, wc, grep]
    readable_paths: [data]
    writable_paths: [out]
    allowed_domains: [api.example.com]
    max_write_bytes: 1000000

Paths are relative to the directory you run from, resolved when the run starts.

allow_network: false without enabled: true limits attachment downloads and nothing else: http_request still reaches any URL.

What it covers

Commands

With the sandbox enabled, a shell_command call is checked in this order:

1. The directory. cwd must sit under allowed_paths or readable_paths. Otherwise every command is refused: with cwd left at ., the directory you run from must be covered, or each call must pass a cwd that is.
2. Shell operators. |, ;, &, a backtick, <, >, $(, <(, >( and line breaks are refused anywhere in the command, even inside quotes. One call runs one program.
3. Shell expansion. $, *, ?, [, brace lists such as {a,b} or {1..3}, and a ~ that starts a word or follows = or : are refused anywhere in the command, even inside quotes, so '$5' or "*.log" can’t be passed to a program. A command that needs them can’t run in the sandbox.
4. The program. The file name of the first word must be in allowed_commands, matching case. A path, such as /usr/bin/grep or ./grep, must be the file that name resolves to on PATH; any other file of that name is refused.
5. Interpreters and launchers. sh, bash, zsh, fish, ksh, dash, env, xargs, find, exec, eval, source, ., python, python3, node, perl, ruby, php, lua, awk, nc, ncat, socat and ssh can run anything else, so they are refused even when allowed, unless danger_opt_in lists them too, one by one.
6. Path arguments. When any path list is set, each argument that looks like a path, such as ., .., anything with a /, or the value of --opt=dir/file, must resolve, from cwd, under one of the three lists. A bare name that is a symbolic link is checked too. A path attached to a short flag is checked from its first /, so -finclude/list reads as /list and is refused: pass it as a separate argument, -f include/list.

Files

• file_read may read under allowed_paths and readable_paths; file_write may write under allowed_paths and writable_paths. A directory listed only in writable_paths can’t be read.
• Paths are resolved before the check, .. and symbolic links included: a link inside an allowed directory that points outside it is refused.
• With the sandbox enabled and no path lists, nothing can be read or written.
• max_write_bytes limits the encoded size of what file_write writes.

Network

With the sandbox enabled, an http_request call is checked against:

• allow_network: false, which refuses every request;
• allowed_schemes: the URL’s scheme must be listed. Only http and https ever work;
• allowed_domains, when set: the host must be listed exactly, without regard to case. api.example.com doesn’t admit eu.api.example.com. A listed host is reached even when it is internal, which is how to allow a service on your own network, unless deny_internal_hosts is on.

Without allowed_domains, internal addresses are refused: loopback, private and link-local ranges, the cloud metadata address 169.254.169.254, shared address space and localhost, in any spelling, such as 127.1, 0x7f000001 or [::ffff:127.0.0.1]. A host name is resolved and every address it returns is checked, and a host that doesn’t resolve is refused.

The request then connects to the addresses the check resolved, so a DNS answer that changes in between can’t reach an internal host. The host name stays in the Host header and the TLS server name, and the certificate is checked against it. A proxy from the environment, such as HTTPS_PROXY, resolves the name itself: nothing is pinned then, so restrict which hosts the proxy lets through. Webhooks and attachment downloads connect the same way.

When the sandbox refuses

Subworkflows

A subworkflow runs its built-in tools, attachments and webhooks under one sandbox:

With both enabled, a child can narrow the parent’s sandbox and can’t widen it:

• A command or a danger_opt_in entry must be on both lists.
• A directory must be readable, or writable, under both. Of two nested directories, the deeper one applies.
• allowed_domains and allowed_schemes must share an entry when both are set; one left empty sets no limit. Two lists with nothing in common refuse every request. A parent with no allowed_domains refuses internal addresses, so a child that lists hosts runs with deny_internal_hosts on: its list can’t open them.
• allow_network and allow_internal_webhook_targets must be true in both, and the smaller max_write_bytes applies.

The child’s built-in tools are rebuilt from these config.sandbox blocks and from nothing else: from Python, a different ToolSandbox passed to register_builtins doesn’t carry over to a child that has its own sandbox. Tools of your own stay unchecked.

Running tools in parallel

• tool steps in the same layer run at the same time, up to config.max_concurrent_steps.
• The tool calls of one model reply run at the same time; see the loop.
• Tools read a copy of the state and change it only through output.

What’s next

• Reliability

  Retries, timeouts, failure policies, budgets and checkpoints.

• LLM calls

  Letting a model call tools, and how the loop ends.

• Testing & replay

  Recording model tool calls and replaying them offline.