humanlayer / 12-factor-agents

2025-03-30 · Source: Github Trending: All languages · Field: Technology & Digital — Artificial Intelligence & Machine Learning, Software Development & Engineering, Robotics & Autonomous Systems · Depth: Intermediate, medium

Summary

The "12-Factor Agents" guide, inspired by the "12-Factor Apps" methodology, outlines principles for building reliable, production-grade LLM-powered software. Authored by Dex, a seasoned AI agent developer, the guide addresses the challenges of deploying agentic applications beyond an 80% quality bar, noting that many existing frameworks fall short for customer-facing use cases. It proposes 12 core factors, such as "Natural Language to Tool Calls," "Own your prompts," "Unify execution state and business state," and "Small, Focused Agents," to help developers integrate modular AI concepts into existing products. The guide emphasizes that effective agents are primarily deterministic software with strategically placed LLM steps, rather than purely LLM-driven loops, and provides a public GitHub repository for community contributions.

Key takeaway

For AI Engineers building customer-facing LLM applications, prioritize integrating modular agent principles into your existing software stack rather than relying solely on comprehensive frameworks. Focus on deterministic control flow, explicit prompt management, and unifying application states to achieve the reliability and quality needed for production environments. This approach allows for faster iteration and higher quality outcomes than greenfield rewrites.

Key insights

Reliable LLM agents require robust software engineering principles, not just advanced AI frameworks.

Principles

• Own your prompts and context window.
• Tools are structured outputs.
• Unify execution and business state.

Method

LLM agents operate in a loop: LLM determines the next tool call, deterministic code executes it, and the result is appended to the context window until a "done" state is reached.

In practice

• Integrate modular AI concepts into existing products.
• Focus on small, specialized agents.
• Design agents for pause/resume capabilities.

Topics

• 12-Factor Agents
• LLM Application Development
• AI Agent Design Patterns
• Tool Calling
• Context Window Management

Code references

• humanlayer/12-factor-agents
• hellovai/ai-that-works
• got-agents/agents
• humanlayer/kubechain
• dexhorthy/mailcrew

Best for: AI Engineer, Software Engineer, MLOps Engineer

Related on AIssential

• Ralph Wiggum (and why Claude Code's implementation isn't it) with Geoffrey Huntley and Dexter Horthy — Effective LLM agent design requires deterministic context management and human oversight, not autonomous "in-loop" operation.
• You Probably Don’t Need an Agent Framework — Explicit LLM workflows offer more reliability and control than autonomous agents for many applications.
• Anatomy of Agent SKILLS — Agent "skills" prevent context bloat by progressively disclosing information, improving efficiency and modularity.
• 10 LLM Engineering Concepts Explained in 10 Minutes — Modern LLM applications are complex systems built on engineering principles beyond basic prompt design.
• Enterprise AI Engineering — Effective enterprise AI agents require robust evaluation and human-in-the-loop design from inception.
• 4 Things Everyone Must Know About LLMs and Agentic AI — Effective LLM and agentic AI development prioritizes model selection, task simplification, context management, and structural prompting over complex prompts.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by Github Trending: All languages.