12-factor-agents

Translates unstructured natural language agent reasoning into deterministic, schema-validated tool calls by implementing a strict separation between LLM reasoning and tool invocation. The system uses structured output formats (likely JSON schema validation) to ensure every tool call conforms to a predefined interface before execution, preventing hallucinated or malformed function calls from reaching production code. This implements Factor 1 of the 12-Factor methodology, treating tool calls as the primary interface between LLM decisions and deterministic system behavior.

Provides a framework for treating prompts as first-class, versioned artifacts rather than embedded strings, enabling teams to own, test, and iterate on prompts independently from application code. Implements Factor 2 by establishing a clear separation between prompt templates, system instructions, and dynamic context injection, with support for prompt versioning, A/B testing, and rollback capabilities. Prompts are stored and managed as configuration rather than hardcoded, allowing non-engineers to modify agent behavior without code changes.

Enables agents to be triggered from any event source (webhooks, message queues, scheduled jobs, user actions) through a unified invocation interface, rather than being tightly coupled to specific trigger mechanisms. Implements Factor 11 by decoupling agent invocation from trigger sources, allowing the same agent to be triggered by multiple sources without modification. Uses an event adapter pattern to normalize different trigger types into a common agent invocation format.

Implements agents as pure, stateless reducers that take a state snapshot and an action, produce a new state snapshot, and have no side effects outside of state mutation. Implements Factor 12 by treating agent execution as a functional transformation where each step is deterministic and reproducible, enabling perfect replay, time-travel debugging, and easy testing. Uses an immutable state model where every action produces a new state snapshot rather than mutating state in place.

Proactively fetches and preloads context data before agent execution begins, reducing latency and ensuring critical information is available without requiring the agent to fetch it during execution. Implements Factor 13 (appendix) by identifying context dependencies upfront and loading them in parallel before the agent starts reasoning, rather than having the agent fetch context on-demand. Uses dependency analysis to determine what context is needed and prefetch strategies to optimize loading.

Provides code generation and scaffolding tools that generate boilerplate agent implementations from high-level specifications, reducing the effort required to implement agents that follow 12-Factor principles. Includes tools like 'walkthroughgen' that analyze existing agent implementations and generate documentation, tests, or new agent variants. Uses code analysis and template-based generation to create consistent, production-ready agent code.

Provides testing infrastructure for agents including unit tests, integration tests, and validation of agent behavior against expected outcomes, with support for deterministic replay and scenario-based testing. Enables testing of agent decision-making, tool call validation, and state transitions in isolation without requiring live LLM calls. Uses snapshot testing and scenario-based approaches to validate agent behavior.

Integrates with BAML (Boundary Augmented Markup Language) for defining and validating structured outputs from LLMs, providing a domain-specific language for specifying tool schemas, output formats, and validation rules. BAML integration enables type-safe tool definitions and structured output validation without requiring manual JSON Schema definition. Uses BAML's parsing and validation capabilities to ensure LLM outputs conform to expected schemas.

Manages agent execution threads and events, tracking the sequence of agent actions, tool calls, and state transitions in a structured event log. Provides mechanisms to query execution history, replay events, and correlate events across multiple agents or execution threads. Uses an event sourcing pattern where every significant action is recorded as an immutable event.

Implements intelligent context window budgeting and management to prevent token overflow and ensure critical information remains available to the LLM throughout agent execution. Implements Factor 3 by providing explicit control over what gets included in the context window, with strategies for prioritizing recent events, important facts, and error information while dropping less critical context when space is constrained. Uses a sliding window or priority-based eviction strategy rather than naive context truncation.

Defines tools as structured output schemas rather than arbitrary functions, ensuring every tool has a well-defined input/output contract that both the LLM and deterministic code can understand. Implements Factor 4 by treating tool definitions as data structures with explicit type information, validation rules, and documentation, enabling the system to generate tool descriptions for the LLM and validate tool responses before execution. Tools are defined declaratively (likely via JSON Schema or similar) rather than as imperative function signatures.

Unifies the agent's execution state (what step it's on, what tools it's called, what errors occurred) with the application's business state (user data, domain objects, transaction state) into a single, consistent state representation. Implements Factor 5 by ensuring the agent's internal reasoning state and the application's persistent state are always synchronized, preventing divergence where the agent thinks it succeeded but the business operation failed. Uses a single state reducer pattern where each agent action produces a new state snapshot.

Provides simple APIs to launch, pause, resume, and cancel agent execution without losing state or context, enabling long-running agents to be interrupted for human review or system maintenance. Implements Factor 6 by treating agent execution as a pausable process with explicit state checkpoints, allowing the agent to be suspended mid-execution, inspected, and resumed from the exact point of interruption. Uses a state-machine approach where pause/resume transitions are explicit and validated.

Enables agents to contact humans (request approval, ask clarifying questions, escalate decisions) by treating human contact as a tool call rather than a special case, maintaining consistency with the tool-call abstraction. Implements Factor 7 by allowing the LLM to decide when human input is needed and what information to request, with the human response being treated as a tool result that feeds back into the agent's reasoning loop. Human contact is asynchronous and non-blocking, allowing the agent to be paused while awaiting human response.

Provides explicit, deterministic control flow logic that the agent cannot override, ensuring critical business logic and safety constraints are enforced regardless of LLM reasoning. Implements Factor 8 by separating the agent's decision-making (what tool to call) from the application's control flow (whether that tool call is allowed, what happens next), with the control flow implemented in deterministic code rather than left to the LLM. Uses a state machine or workflow engine to define valid state transitions and enforce business rules.

Compacts error information into a concise, context-window-efficient format that provides the agent with actionable debugging information without consuming excessive tokens. Implements Factor 9 by extracting the most relevant error details (error type, root cause, suggested remediation) and presenting them in a structured format that the LLM can efficiently process, rather than including full stack traces or verbose error messages. Uses error categorization and templating to ensure consistency.

Decomposes complex agent tasks into small, focused agents with single responsibilities that can be composed together, rather than building monolithic agents that handle multiple concerns. Implements Factor 10 by establishing clear boundaries between agent responsibilities, with each agent handling a specific domain or task type, and providing composition mechanisms to orchestrate multiple agents. Uses a DAG (directed acyclic graph) or similar pattern to define agent dependencies and execution order.