@techNmak ·
Someone documented the engineering principles behind AI agents that actually work in production. It's called 12-Factor Agents. Here's what each factor actually means and why it matters: Factor 1 - Natural Language to Tool Calls The LLM's only job is to decide what to do next, outputting structured JSON. Your deterministic code does the actual execution. This separation is what makes agents debuggable. Factor 2 - Own your prompts If a framework hides your prompts from you, you can't debug output quality. Visibility is non-negotiable. Factor 3 - Own your context window The context window is the agent's entire working memory. What you put in, in what order, with what compression, determines output quality more than model choice. This is context engineering, the most underrated skill in agent development. Factor 4 - Tools are just structured outputs Tool calling is not magic. It's JSON schema. The LLM outputs a structured object. Your code pattern-matches on it and executes. Demystify this and everything else gets simpler. Factor 5 - Unify execution state and business state Don't maintain two separate state systems. The agent's execution state and your application's business state should live in one place or you'll spend your life keeping them in sync. Factor 6 - Launch/Pause/Resume with simple APIs Production agents get interrupted. Users change their minds. Systems go down. Design for pause and resume from the start, not as an afterthought. Factor 7 - Contact humans with tool calls Human approval isn't a special interrupt mechanism. It's just another tool the agent can call. This reframe makes human-in-the-loop trivial to add and trivial to remove. Factor 8 - Own your control flow Let the LLM decide what action to take. Keep the if/else and switch statements in your code. The moment a framework owns your control flow, debugging becomes reverse-engineering. Factor 9 - Compact errors into context window A failed tool call is information, not an exception to throw. Put the error back into context so the agent can reason about what went wrong and try differently. Factor 10 - Small, focused agents One agent. One job. Reliability degrades with scope. The agents that work in production do one thing well and hand off cleanly to the next. Factor 11 - Trigger from anywhere Email, Slack, webhook, cron, mobile app. The same agent should be triggerable from any surface without rewriting the core logic. Factor 12 - Make your agent a stateless reducer Given the same context window, the agent always produces the same next action. Test it like a function. Debug it like a function. This is the architectural principle that makes everything else tractable. The fastest path to production AI is understanding these principles well enough to apply them inside what you're already building. 22k+ stars. GitHub Repo: https://t.co/nQjPc8w3V1
- 10Replies
- 63Reposts
- 309Likes
- 14.7KViews
