# beam_agent v0.1.0 - Table of Contents

> A general-purpose, OTP-based agent harness for Elixir: an LLM tool-use
loop with an injectable tool registry, configurable guardrails,
pluggable post-run verification, deterministic context compression,
a full execution trace, and supervised, concurrent agent runs.

## Pages

- [BeamAgent](readme.md)

## Modules

- [BeamAgent](BeamAgent.md): BeamAgent is a general-purpose Elixir agent harness: an LLM-driven
tool-use loop, deterministic context compression, guardrails, and
post-run verification, built as OTP processes so each run is isolated —
one crashing has no effect on any other — and supervised for automatic
cleanup.
- [BeamAgent.API](BeamAgent.API.md): Public API for executing agents.
- [BeamAgent.Context](BeamAgent.Context.md): Owns the information sent to the model.
- [BeamAgent.Guardrails](BeamAgent.Guardrails.md): Thin dispatcher over the individual guardrail checks, each its own module:
`BeamAgent.Guardrails.MaxIterations`, `MaxContextMessages`,
`MaxExecutionTime`, and `MaxToolCalls`. All read their options from the
same `guardrails` keyword list passed to `BeamAgent.Runner.start_link/1`
(via `BeamAgent.API.run/2`'s `:guardrails` opt) — there's no shared config
struct, each check just looks up its own key with its own default.

- [BeamAgent.Guardrails.MaxContextMessages](BeamAgent.Guardrails.MaxContextMessages.md): Ensures that the final model-facing context is within its configured
message limit.

- [BeamAgent.Guardrails.MaxExecutionTime](BeamAgent.Guardrails.MaxExecutionTime.md): Prevents an agent from executing for longer than the allowed time.

- [BeamAgent.Guardrails.MaxIterations](BeamAgent.Guardrails.MaxIterations.md): Guardrail for enforcing maximum iteration limits.

- [BeamAgent.Guardrails.MaxToolCalls](BeamAgent.Guardrails.MaxToolCalls.md): Prevents an agent executing more than the allowed tool calls.

- [BeamAgent.LLM.Client](BeamAgent.LLM.Client.md): Behaviour implemented by every LLM provider.

- [BeamAgent.LLM.Config](BeamAgent.LLM.Config.md): Configuration for the LLM client.

- [BeamAgent.LLM.Mock](BeamAgent.LLM.Mock.md): Deterministic LLM implementation used to exercise the agent harness.

- [BeamAgent.Run](BeamAgent.Run.md): Represents a completed outcome of a single agent execution.
- [BeamAgent.Run.Builder](BeamAgent.Run.Builder.md): Converts internal execution state into a structured `BeamAgent.Run`
representation, capturing the goal, answer, status, trace, and timestamps
of the agent's execution.

- [BeamAgent.RunSupervisor](BeamAgent.RunSupervisor.md): Dynamically supervises individual agent executions.
- [BeamAgent.Runner](BeamAgent.Runner.md): Executes one isolated agent run.
- [BeamAgent.State](BeamAgent.State.md): Holds the runtime state for a single agent execution.
- [BeamAgent.Tools.Behaviour](BeamAgent.Tools.Behaviour.md): Behaviour implemented by every tool the agent can execute.

- [BeamAgent.Tools.Crash](BeamAgent.Tools.Crash.md): A tool that always raises. Exists to exercise runner crash isolation —
that a tool blowing up takes down only its own run, not the caller or any
other concurrent run (see `BeamAgent.RunSupervisor`).

- [BeamAgent.Tools.Echo](BeamAgent.Tools.Echo.md): A simple module for echoing values.

- [BeamAgent.Tools.Registry](BeamAgent.Tools.Registry.md): Dispatches a tool call to the module registered for it.
- [BeamAgent.Tools.Sleep](BeamAgent.Tools.Sleep.md): A tool that sleeps for a specified duration.
Testing execution time guardrail

- [BeamAgent.Trace](BeamAgent.Trace.md): Provides tracing functionality for the agent.
- [BeamAgent.Trace.Step](BeamAgent.Trace.Step.md): Represents a single trace entry.

- [BeamAgent.Verifier](BeamAgent.Verifier.md): Verifies whether an agent execution satisfied the expected conditions.
- [BeamAgent.Verifier.Behaviour](BeamAgent.Verifier.Behaviour.md): Behaviour implemented by every verifier.
- [BeamAgent.Verifier.Default](BeamAgent.Verifier.Default.md): Default verifier: checks that the run finished, produced an answer, and
called every tool listed under `:required_tools`.

