# 12-factor-agents | HumanLayer | Knowledge Base | Instagit

What are the principles we can use to build LLM-powered software that is actually good enough to put in the hands of production customers?

GitHub Stars: 20.9k

Repository: https://github.com/humanlayer/12-factor-agents

---

## Articles

### [How to Migrate from Framework-Based Agents to Custom Implementations: A 12-Factor Guide](/humanlayer/12-factor-agents/how-to-migrate-from-framework-based-agents-to-custom-implementations)

Migrate from framework-based agents to custom implementations with this 12-factor guide. Extract agent loops, externalize prompts to BAML, and replace tool executors for full control.

- Tags: migration-guide
- Published: 2026-05-19

### [How to Debug Agent Loops and Prevent Infinite Spinning in 12-Factor Agents](/humanlayer/12-factor-agents/how-to-debug-agent-loops-and-infinite-spinning)

Debug agent loops and prevent infinite spinning in 12-Factor Agents. Implement step counters, validate LLM responses, and add structured logging to your agent code.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Handle Rate Limiting in LLM Agent Frameworks: A 12-Factor Approach](/humanlayer/12-factor-agents/how-to-handle-rate-limiting-in-agent-frameworks)

Handle rate limiting in LLM agent frameworks with token buckets and exponential back-off. This 12-factor approach prevents API quota exhaustion and ensures predictable agent behavior.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Implement DAG-Style Orchestration in Agent Systems](/humanlayer/12-factor-agents/how-to-implement-dag-style-orchestration-in-agent-systems)

Master DAG-style orchestration in agent systems. Learn how to combine static task dependencies with LLM control for dynamic execution and resumable state management. Explore the humanlayer/12-factor-agents repository.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Test and Evaluate LLM Agent Behavior Reliably: A 12-Factor Agents Guide](/humanlayer/12-factor-agents/how-to-test-and-evaluate-agent-behavior-reliably)

Learn to reliably test and evaluate LLM agent behavior using the 12-Factor Agents framework. This guide details a reproducible notebook workflow for isolated prompt execution and tool calls in sandboxed environments.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Add Approval Gates in Agent Tool Execution: A 12-Factor Agents Guide](/humanlayer/12-factor-agents/how-to-add-approval-gates-in-agent-tool-execution)

Learn how to add approval gates in agent tool execution using a Thread state checker. Pause agent loops, await human confirmation, and resume processing securely. Improve agent control and reliability.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Manage LLM Context Window Size for Long-Running Agents: A 12-Factor Approach](/humanlayer/12-factor-agents/how-to-manage-context-window-size-for-long-running-agents)

Master LLM context window size for long-running agents. Learn to serialize events, implement token budget guards, and optimize context for enhanced performance.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Implement RAG in Agent Context Windows: A 12-Factor Agents Guide](/humanlayer/12-factor-agents/how-to-implement-rag-in-agent-context-windows)

Learn to implement RAG in agent context windows by encoding documents as structured events for efficient LLM reasoning over current information. Explore the 12-Factor Agents guide.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Build Multi-Step Agent Workflows with Deterministic Control](/humanlayer/12-factor-agents/how-to-build-multi-step-agent-workflows-with-deterministic-control)

Learn to build multi step agent workflows with deterministic control by separating LLM reasoning from execution. Output JSON intents for a dispatch layer to route to functions. Enable interruptible loops with persistent state.

- Tags: tutorial
- Published: 2026-05-19

### [How to Design Agent Memory and Context Persistence in 12-Factor Agents](/humanlayer/12-factor-agents/how-to-design-agent-memory-and-context-persistence)

Learn to design agent memory and context persistence by treating threads as the source of truth and persisting events to a ThreadStore. Ensure seamless state retention for your stateless LLMs.

- Tags: how-to-guide
- Published: 2026-05-19

### [Agent Error Recovery and Retry Logic in 12-Factor Agents: A Complete Guide](/humanlayer/12-factor-agents/how-to-handle-agent-error-recovery-and-retry-logic)

Master agent error recovery and retry logic in 12-factor agents. Learn to treat tool failures as events for LLM self-correction and implement robust retry counters. Ensure agent resilience.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Implement Schema-Aligned Parsing for Reliable LLM Outputs](/humanlayer/12-factor-agents/how-to-implement-schema-aligned-parsing-for-reliable-llm-outputs)

Learn schema-aligned parsing to ensure LLM outputs are reliable JSON, validating against Zod schemas and preventing errors before they impact your business logic.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Build Small Focused Agents vs Monolithic Agent Systems](/humanlayer/12-factor-agents/how-to-build-small-focused-agents-vs-monolithic-agent-systems)

Learn to build small focused agents versus monolithic agent systems. Discover how composable agents improve manageability and context with the 12-factor approach.

- Tags: architecture
- Published: 2026-05-19

### [How to Optimize Token Usage in LLM Context Windows: 7 Strategies from 12-Factor Agents](/humanlayer/12-factor-agents/how-to-optimize-token-usage-in-llm-context-windows)

Optimize LLM context window token usage with 7 strategies from 12-Factor Agents. Learn to pack data, serialize events, filter history, and use token-budget-aware trimming for efficient LLM performance.

- Tags: best-practices
- Published: 2026-05-19

### [How to Implement Human-in-the-Loop with LLM Tool Calls in 12-Factor Agents](/humanlayer/12-factor-agents/how-to-implement-human-in-the-loop-with-tool-calls)

Learn how to implement human-in-the-loop with LLM tool calls. Expose request_human_input tool, handle intent with clarification handler, and persist history for seamless agent loops. Build smarter AI applications.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Trigger Agents from Anywhere Using Webhooks and Events](/humanlayer/12-factor-agents/how-to-trigger-agents-from-anywhere-using-webhooks-and-events)

Learn to trigger agents from anywhere using webhooks and events with the 12-Factor Agents framework. Easily integrate external systems for seamless agent execution.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Unify Execution State and Business State in Agent Architectures: A 12-Factor Approach](/humanlayer/12-factor-agents/how-to-unify-execution-state-and-business-state-in-agent-architectures)

Unify execution and business state in agent architectures by merging them into a single Thread object. Learn this 12-factor approach to simplify your agent development and improve clarity.

- Tags: architecture
- Published: 2026-05-19

### [How to Implement Pause and Resume Functionality in Agent Systems](/humanlayer/12-factor-agents/how-to-implement-pause-resume-functionality-in-agent-systems)

Learn to implement pause and resume for agent systems. Externalize state to a ThreadStore and use thread_id in webhooks for stateless orchestration resilient to restarts and scaling.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Compact Errors into Context Window for Agent Self-Healing](/humanlayer/12-factor-agents/how-to-compact-errors-into-context-window-for-agent-self-healing)

Learn how to compact errors into the agent's context window for self-healing. Wrap tool executions and append compact error representations for LLM error detection and resolution.

- Tags: how-to-guide
- Published: 2026-05-19

### [When to Use Function Calling vs Structured Outputs vs JSON Mode for LLMs](/humanlayer/12-factor-agents/when-to-use-function-calling-vs-structured-outputs-vs-json-mode)

Choose the right LLM output: Function calling for schema validation, structured outputs for custom validation, or JSON mode for rapid prototyping. Optimize your API calls today.

- Tags: best-practices
- Published: 2026-05-19

### [How to Build Stateless Reducer Agents Using the Redux Pattern](/humanlayer/12-factor-agents/how-to-build-stateless-reducer-agents-similar-to-redux-pattern)

Build stateless reducer agents using the Redux pattern. Treat agent loops as pure functions for easy restarting without losing state or context. Learn how for your projects.

- Tags: best-practices
- Published: 2026-05-19

### [Why Agents Should Manage Their Own Control Flow Instead of Framework Loops](/humanlayer/12-factor-agents/why-agents-should-own-their-control-flow-instead-of-using-framework-loops)

Agents get interrupt-resume capabilities, explicit state persistence, and dynamic decision-making when they manage control flow instead of using framework loops. Elevate your agent's performance

- Tags: tutorial
- Published: 2026-05-19

### [Context Engineering for LLM Applications: A Complete Implementation Guide](/humanlayer/12-factor-agents/how-to-implement-context-engineering-for-llm-applications)

Implement context engineering for LLM applications. Learn to control LLM input by serializing prompts, tool results, and memory into a custom format. Read our complete guide.

- Tags: how-to-guide
- Published: 2026-05-19

### [How to Convert Natural Language to Structured Tool Calls in LLM Agents](/humanlayer/12-factor-agents/how-to-convert-natural-language-to-structured-tool-calls-in-llm-agents)

Learn to convert natural language to structured tool calls in LLM agents. Prompt LLMs for JSON, parse output, and dispatch to tools for efficient agent development. Get started now!

- Tags: how-to-guide
- Published: 2026-05-19