[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-3747":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":37,"readmeContent":38,"aiSummary":39,"trendingCount":16,"starSnapshotCount":16,"syncStatus":40,"lastSyncTime":41,"discoverSource":42},3747,"12-factor-agents","humanlayer\u002F12-factor-agents","humanlayer","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?","",null,"TypeScript",23189,1775,201,12,0,11,193,3433,121,119.75,"Other",false,"main",true,[27,5,28,29,30,31,32,33,34,35,36],"12-factor","agents","ai","context-window","framework","llms","memory","orchestration","prompt-engineering","rag","2026-06-12 04:00:19","# 12-Factor Agents - Principles for building reliable LLM applications\n\n\u003Cdiv align=\"center\">\n\u003Ca href=\"https:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCode-Apache%202.0-blue.svg\" alt=\"Code License: Apache 2.0\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fcreativecommons.org\u002Flicenses\u002Fby-sa\u002F4.0\u002F\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FContent-CC%20BY--SA%204.0-lightgrey.svg\" alt=\"Content License: CC BY-SA 4.0\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fhumanlayer.dev\u002Fdiscord\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fchat-discord-5865F2\" alt=\"Discord Server\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=8kMaTybvDUw\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Faidotengineer-conf_talk_(17m)-white\" alt=\"YouTube\nDeep Dive\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=yxJDyQ8v6P0\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fyoutube-deep_dive-crimson\" alt=\"YouTube\nDeep Dive\">\u003C\u002Fa>\n    \n\u003C\u002Fdiv>\n\n\u003Cp>\u003C\u002Fp>\n\n*In the spirit of [12 Factor Apps](https:\u002F\u002F12factor.net\u002F)*.  *The source for this project is public at https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents, and I welcome your feedback and contributions. Let's figure this out together!*\n\n> [!TIP]\n> Missed the AI Engineer World's Fair? [Catch the talk here](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=8kMaTybvDUw)\n>\n> Looking for Context Engineering? [Jump straight to factor 3](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-03-own-your-context-window.md)\n>\n> Want to contribute to `npx\u002Fuvx create-12-factor-agent` - check out [the discussion thread](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fdiscussions\u002F61)\n\n\n\u003Cimg referrerpolicy=\"no-referrer-when-downgrade\" src=\"https:\u002F\u002Fstatic.scarf.sh\u002Fa.png?x-pxid=2acad99a-c2d9-48df-86f5-9ca8061b7bf9\" \u002F>\n\n\u003Ca href=\"#visual-nav\">\u003Cimg width=\"907\" alt=\"Screenshot 2025-04-03 at 2 49 07 PM\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F23286ad8-7bef-4902-b371-88ff6a22e998\" \u002F>\u003C\u002Fa>\n\n\nHi, I'm Dex. I've been [hacking](https:\u002F\u002Fyoutu.be\u002F8bIHcttkOTE) on [AI agents](https:\u002F\u002Ftheouterloop.substack.com) for [a while](https:\u002F\u002Fhumanlayer.dev). \n\n\n**I've tried every agent framework out there**, from the plug-and-play crew\u002Flangchains to the \"minimalist\" smolagents of the world to the \"production grade\" langraph, griptape, etc. \n\n**I've talked to a lot of really strong founders**, in and out of YC, who are all building really impressive things with AI. Most of them are rolling the stack themselves. I don't see a lot of frameworks in production customer-facing agents.\n\n**I've been surprised to find** that most of the products out there billing themselves as \"AI Agents\" are not all that agentic. A lot of them are mostly deterministic code, with LLM steps sprinkled in at just the right points to make the experience truly magical.\n\nAgents, at least the good ones, don't follow the [\"here's your prompt, here's a bag of tools, loop until you hit the goal\"](https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fbuilding-effective-agents#agents) pattern. Rather, they are comprised of mostly just software. \n\nSo, I set out to answer:\n\n> ### **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?**\n\nWelcome to 12-factor agents. As every Chicago mayor since Daley has consistently plastered all over the city's major airports, we're glad you're here.\n\n*Special thanks to [@iantbutler01](https:\u002F\u002Fgithub.com\u002Fiantbutler01), [@tnm](https:\u002F\u002Fgithub.com\u002Ftnm), [@hellovai](https:\u002F\u002Fwww.github.com\u002Fhellovai), [@stantonk](https:\u002F\u002Fwww.github.com\u002Fstantonk), [@balanceiskey](https:\u002F\u002Fwww.github.com\u002Fbalanceiskey), [@AdjectiveAllison](https:\u002F\u002Fwww.github.com\u002FAdjectiveAllison), [@pfbyjy](https:\u002F\u002Fwww.github.com\u002Fpfbyjy), [@a-churchill](https:\u002F\u002Fwww.github.com\u002Fa-churchill), and the SF MLOps community for early feedback on this guide.*\n\n## The Short Version: The 12 Factors\n\nEven if LLMs [continue to get exponentially more powerful](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-10-small-focused-agents.md#what-if-llms-get-smarter), there will be core engineering techniques that make LLM-powered software more reliable, more scalable, and easier to maintain.\n\n- [How We Got Here: A Brief History of Software](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Fbrief-history-of-software.md)\n- [Factor 1: Natural Language to Tool Calls](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-01-natural-language-to-tool-calls.md)\n- [Factor 2: Own your prompts](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-02-own-your-prompts.md)\n- [Factor 3: Own your context window](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-03-own-your-context-window.md)\n- [Factor 4: Tools are just structured outputs](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-04-tools-are-structured-outputs.md)\n- [Factor 5: Unify execution state and business state](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-05-unify-execution-state.md)\n- [Factor 6: Launch\u002FPause\u002FResume with simple APIs](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-06-launch-pause-resume.md)\n- [Factor 7: Contact humans with tool calls](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-07-contact-humans-with-tools.md)\n- [Factor 8: Own your control flow](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-08-own-your-control-flow.md)\n- [Factor 9: Compact Errors into Context Window](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-09-compact-errors.md)\n- [Factor 10: Small, Focused Agents](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-10-small-focused-agents.md)\n- [Factor 11: Trigger from anywhere, meet users where they are](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-11-trigger-from-anywhere.md)\n- [Factor 12: Make your agent a stateless reducer](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-12-stateless-reducer.md)\n\n### Visual Nav\n\n|    |    |    |\n|----|----|-----|\n|[![factor 1](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F110-natural-language-tool-calls.png)](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-01-natural-language-to-tool-calls.md) | [![factor 2](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F120-own-your-prompts.png)](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-02-own-your-prompts.md) | [![factor 3](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F130-own-your-context-building.png)](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-03-own-your-context-window.md) |\n|[![factor 4](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F140-tools-are-just-structured-outputs.png)](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-04-tools-are-structured-outputs.md) | [![factor 5](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F150-unify-state.png)](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-05-unify-execution-state.md) | [![factor 6](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F160-pause-resume-with-simple-apis.png)](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-06-launch-pause-resume.md) |\n| [![factor 7](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F170-contact-humans-with-tools.png)](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-07-contact-humans-with-tools.md) | [![factor 8](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F180-control-flow.png)](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-08-own-your-control-flow.md) | [![factor 9](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F190-factor-9-errors-static.png)](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-09-compact-errors.md) |\n| [![factor 10](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F1a0-small-focused-agents.png)](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-10-small-focused-agents.md) | [![factor 11](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F1b0-trigger-from-anywhere.png)](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-11-trigger-from-anywhere.md) | [![factor 12](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F1c0-stateless-reducer.png)](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-12-stateless-reducer.md) |\n\n## How we got here\n\nFor a deeper dive on my agent journey and what led us here, check out [A Brief History of Software](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Fbrief-history-of-software.md) - a quick summary here:\n\n### The promise of agents\n\nWe're gonna talk a lot about Directed Graphs (DGs) and their Acyclic friends, DAGs. I'll start by pointing out that...well...software is a directed graph. There's a reason we used to represent programs as flow charts.\n\n![010-software-dag](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F010-software-dag.png)\n\n### From code to DAGs\n\nAround 20 years ago, we started to see DAG orchestrators become popular. We're talking classics like [Airflow](https:\u002F\u002Fairflow.apache.org\u002F), [Prefect](https:\u002F\u002Fwww.prefect.io\u002F), some predecessors, and some newer ones like ([dagster](https:\u002F\u002Fdagster.io\u002F), [inggest](https:\u002F\u002Fwww.inngest.com\u002F), [windmill](https:\u002F\u002Fwww.windmill.dev\u002F)). These followed the same graph pattern, with the added benefit of observability, modularity, retries, administration, etc.\n\n![015-dag-orchestrators](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F015-dag-orchestrators.png)\n\n### The promise of agents\n\nI'm not the first [person to say this](https:\u002F\u002Fyoutu.be\u002FDc99-zTMyMg?si=bcT0hIwWij2mR-40&t=73), but my biggest takeaway when I started learning about agents, was that you get to throw the DAG away. Instead of software engineers coding each step and edge case, you can give the agent a goal and a set of transitions:\n\n![025-agent-dag](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F025-agent-dag.png)\n\nAnd let the LLM make decisions in real time to figure out the path\n\n![026-agent-dag-lines](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F026-agent-dag-lines.png)\n\nThe promise here is that you write less software, you just give the LLM the \"edges\" of the graph and let it figure out the nodes. You can recover from errors, you can write less code, and you may find that LLMs find novel solutions to problems.\n\n\n### Agents as loops\n\nAs we'll see later, it turns out this doesn't quite work.\n\nLet's dive one step deeper - with agents you've got this loop consisting of 3 steps:\n\n1. LLM determines the next step in the workflow, outputting structured json (\"tool calling\")\n2. Deterministic code executes the tool call\n3. The result is appended to the context window \n4. Repeat until the next step is determined to be \"done\"\n\n```python\ninitial_event = {\"message\": \"...\"}\ncontext = [initial_event]\nwhile True:\n  next_step = await llm.determine_next_step(context)\n  context.append(next_step)\n\n  if (next_step.intent === \"done\"):\n    return next_step.final_answer\n\n  result = await execute_step(next_step)\n  context.append(result)\n```\n\nOur initial context is just the starting event (maybe a user message, maybe a cron fired, maybe a webhook, etc), and we ask the llm to choose the next step (tool) or to determine that we're done.\n\nHere's a multi-step example:\n\n[![027-agent-loop-animation](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F027-agent-loop-animation.gif)](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F3beb0966-fdb1-4c12-a47f-ed4e8240f8fd)\n\n\u003Cdetails>\n\u003Csummary>\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F027-agent-loop-animation.gif\">GIF Version\u003C\u002Fa>\u003C\u002Fsummary>\n\n![027-agent-loop-animation](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fimg\u002F027-agent-loop-animation.gif)\n\n\u003C\u002Fdetails>\n\n## Why 12-factor agents?\n\nAt the end of the day, this approach just doesn't work as well as we want it to.\n\nIn building HumanLayer, I've talked to at least 100 SaaS builders (mostly technical founders) looking to make their existing product more agentic. The journey usually goes something like:\n\n1. Decide you want to build an agent\n2. Product design, UX mapping, what problems to solve\n3. Want to move fast, so grab $FRAMEWORK and *get to building*\n4. Get to 70-80% quality bar \n5. Realize that 80% isn't good enough for most customer-facing features\n6. Realize that getting past 80% requires reverse-engineering the framework, prompts, flow, etc.\n7. Start over from scratch\n\n\u003Cdetails>\n\u003Csummary>Random Disclaimers\u003C\u002Fsummary>\n\n**DISCLAIMER**: I'm not sure the exact right place to say this, but here seems as good as any: **this in BY NO MEANS meant to be a dig on either the many frameworks out there, or the pretty dang smart people who work on them**. They enable incredible things and have accelerated the AI ecosystem. \n\nI hope that one outcome of this post is that agent framework builders can learn from the journeys of myself and others, and make frameworks even better. \n\nEspecially for builders who want to move fast but need deep control.\n\n**DISCLAIMER 2**: I'm not going to talk about MCP. I'm sure you can see where it fits in.\n\n**DISCLAIMER 3**: I'm using mostly typescript, for [reasons](https:\u002F\u002Fwww.linkedin.com\u002Fposts\u002Fdexterihorthy_llms-typescript-aiagents-activity-7290858296679313408-Lh9e?utm_source=share&utm_medium=member_desktop&rcm=ACoAAA4oHTkByAiD-wZjnGsMBUL_JT6nyyhOh30) but all this stuff works in python or any other language you prefer. \n\n\nAnyways back to the thing...\n\n\u003C\u002Fdetails>\n\n### Design Patterns for great LLM applications\n\nAfter digging through hundreds of AI libriaries and working with dozens of founders, my instinct is this:\n\n1. There are some core things that make agents great\n2. Going all in on a framework and building what is essentially a greenfield rewrite may be counter-productive\n3. There are some core principles that make agents great, and you will get most\u002Fall of them if you pull in a framework\n4. BUT, the fastest way I've seen for builders to get high-quality AI software in the hands of customers is to take small, modular concepts from agent building, and incorporate them into their existing product\n5. These modular concepts from agents can be defined and applied by most skilled software engineers, even if they don't have an AI background\n\n> #### The fastest way I've seen for builders to get good AI software in the hands of customers is to take small, modular concepts from agent building, and incorporate them into their existing product\n\n\n## The 12 Factors (again)\n\n\n- [How We Got Here: A Brief History of Software](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Fbrief-history-of-software.md)\n- [Factor 1: Natural Language to Tool Calls](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-01-natural-language-to-tool-calls.md)\n- [Factor 2: Own your prompts](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-02-own-your-prompts.md)\n- [Factor 3: Own your context window](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-03-own-your-context-window.md)\n- [Factor 4: Tools are just structured outputs](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-04-tools-are-structured-outputs.md)\n- [Factor 5: Unify execution state and business state](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-05-unify-execution-state.md)\n- [Factor 6: Launch\u002FPause\u002FResume with simple APIs](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-06-launch-pause-resume.md)\n- [Factor 7: Contact humans with tool calls](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-07-contact-humans-with-tools.md)\n- [Factor 8: Own your control flow](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-08-own-your-control-flow.md)\n- [Factor 9: Compact Errors into Context Window](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-09-compact-errors.md)\n- [Factor 10: Small, Focused Agents](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-10-small-focused-agents.md)\n- [Factor 11: Trigger from anywhere, meet users where they are](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-11-trigger-from-anywhere.md)\n- [Factor 12: Make your agent a stateless reducer](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Ffactor-12-stateless-reducer.md)\n\n## Honorable Mentions \u002F other advice\n\n- [Factor 13: Pre-fetch all the context you might need](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents\u002Fblob\u002Fmain\u002Fcontent\u002Fappendix-13-pre-fetch.md)\n\n## Related Resources\n\n- Contribute to this guide [here](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002F12-factor-agents)\n- [I talked about a lot of this on an episode of the Tool Use podcast](https:\u002F\u002Fyoutu.be\u002F8bIHcttkOTE) in March 2025\n- I write about some of this stuff at [The Outer Loop](https:\u002F\u002Ftheouterloop.substack.com)\n- I do [webinars about Maximizing LLM Performance](https:\u002F\u002Fgithub.com\u002Fhellovai\u002Fai-that-works\u002Ftree\u002Fmain) with [@hellovai](https:\u002F\u002Fgithub.com\u002Fhellovai)\n- We build OSS agents with this methodology under [got-agents\u002Fagents](https:\u002F\u002Fgithub.com\u002Fgot-agents\u002Fagents)\n- We ignored all our own advice and built a [framework for running distributed agents in kubernetes](https:\u002F\u002Fgithub.com\u002Fhumanlayer\u002Fkubechain)\n- Other links from this guide:\n  - [12 Factor Apps](https:\u002F\u002F12factor.net)\n  - [Building Effective Agents (Anthropic)](https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fbuilding-effective-agents#agents)\n  - [Prompts are Functions](https:\u002F\u002Fthedataexchange.media\u002Fbaml-revolution-in-ai-engineering\u002F )\n  - [Library patterns: Why frameworks are evil](https:\u002F\u002Ftomasp.net\u002Fblog\u002F2015\u002Flibrary-frameworks\u002F)\n  - [The Wrong Abstraction](https:\u002F\u002Fsandimetz.com\u002Fblog\u002F2016\u002F1\u002F20\u002Fthe-wrong-abstraction)\n  - [Mailcrew Agent](https:\u002F\u002Fgithub.com\u002Fdexhorthy\u002Fmailcrew)\n  - [Mailcrew Demo Video](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=f_cKnoPC_Oo)\n  - [Chainlit Demo](https:\u002F\u002Fx.com\u002Fchainlit_io\u002Fstatus\u002F1858613325921480922)\n  - [TypeScript for LLMs](https:\u002F\u002Fwww.linkedin.com\u002Fposts\u002Fdexterihorthy_llms-typescript-aiagents-activity-7290858296679313408-Lh9e)\n  - [Schema Aligned Parsing](https:\u002F\u002Fwww.boundaryml.com\u002Fblog\u002Fschema-aligned-parsing)\n  - [Function Calling vs Structured Outputs vs JSON Mode](https:\u002F\u002Fwww.vellum.ai\u002Fblog\u002Fwhen-should-i-use-function-calling-structured-outputs-or-json-mode)\n  - [BAML on GitHub](https:\u002F\u002Fgithub.com\u002Fboundaryml\u002Fbaml)\n  - [OpenAI JSON vs Function Calling](https:\u002F\u002Fdocs.llamaindex.ai\u002Fen\u002Fstable\u002Fexamples\u002Fllm\u002Fopenai_json_vs_function_calling\u002F)\n  - [Outer Loop Agents](https:\u002F\u002Ftheouterloop.substack.com\u002Fp\u002Fopenais-realtime-api-is-a-step-towards)\n  - [Airflow](https:\u002F\u002Fairflow.apache.org\u002F)\n  - [Prefect](https:\u002F\u002Fwww.prefect.io\u002F)\n  - [Dagster](https:\u002F\u002Fdagster.io\u002F)\n  - [Inngest](https:\u002F\u002Fwww.inngest.com\u002F)\n  - [Windmill](https:\u002F\u002Fwww.windmill.dev\u002F)\n  - [The AI Agent Index (MIT)](https:\u002F\u002Faiagentindex.mit.edu\u002F)\n  - [NotebookLM on Finding Model Capability Boundaries](https:\u002F\u002Fopen.substack.com\u002Fpub\u002Fswyx\u002Fp\u002Fnotebooklm?selection=08e1187c-cfee-4c63-93c9-71216640a5f8)\n\n## Contributors\n\nThanks to everyone who has contributed to 12-factor agents!\n\n[\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F3730605?v=4&s=80\" width=\"80px\" alt=\"dexhorthy\" \u002F>](https:\u002F\u002Fgithub.com\u002Fdexhorthy) [\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F50557586?v=4&s=80\" width=\"80px\" alt=\"Sypherd\" \u002F>](https:\u002F\u002Fgithub.com\u002FSypherd) [\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F66259401?v=4&s=80\" width=\"80px\" alt=\"tofaramususa\" \u002F>](https:\u002F\u002Fgithub.com\u002Ftofaramususa) [\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F18105223?v=4&s=80\" width=\"80px\" alt=\"a-churchill\" \u002F>](https:\u002F\u002Fgithub.com\u002Fa-churchill) [\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F4084885?v=4&s=80\" width=\"80px\" alt=\"Elijas\" \u002F>](https:\u002F\u002Fgithub.com\u002FElijas) [\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F39267118?v=4&s=80\" width=\"80px\" alt=\"hugolmn\" \u002F>](https:\u002F\u002Fgithub.com\u002Fhugolmn) [\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1882972?v=4&s=80\" width=\"80px\" alt=\"jeremypeters\" \u002F>](https:\u002F\u002Fgithub.com\u002Fjeremypeters)\n\n[\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F380402?v=4&s=80\" width=\"80px\" alt=\"kndl\" \u002F>](https:\u002F\u002Fgithub.com\u002Fkndl) [\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F16674643?v=4&s=80\" width=\"80px\" alt=\"maciejkos\" \u002F>](https:\u002F\u002Fgithub.com\u002Fmaciejkos) [\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F85041180?v=4&s=80\" width=\"80px\" alt=\"pfbyjy\" \u002F>](https:\u002F\u002Fgithub.com\u002Fpfbyjy) [\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F36044389?v=4&s=80\" width=\"80px\" alt=\"0xRaduan\" \u002F>](https:\u002F\u002Fgithub.com\u002F0xRaduan) [\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F7169731?v=4&s=80\" width=\"80px\" alt=\"zyuanlim\" \u002F>](https:\u002F\u002Fgithub.com\u002Fzyuanlim) [\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F15862501?v=4&s=80\" width=\"80px\" alt=\"lombardo-chcg\" \u002F>](https:\u002F\u002Fgithub.com\u002Flombardo-chcg) [\u003Cimg src=\"https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F160066852?v=4&s=80\" width=\"80px\" alt=\"sahanatvessel\" \u002F>](https:\u002F\u002Fgithub.com\u002Fsahanatvessel)\n \n## License\n\nAll content and images are licensed under a \u003Ca href=\"https:\u002F\u002Fcreativecommons.org\u002Flicenses\u002Fby-sa\u002F4.0\u002F\">CC BY-SA 4.0 License\u003C\u002Fa>\n\nCode is licensed under the \u003Ca href=\"https:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0\">Apache 2.0 License\u003C\u002Fa>\n\n\n","12-Factor Agents 是一个旨在构建可靠且适用于生产环境的大型语言模型（LLM）应用的原则框架。该项目基于12要素应用的理念，提供了一套全面的设计原则和最佳实践，以确保所开发的AI应用能够满足实际部署需求。它特别关注于如何有效管理上下文窗口、记忆机制以及提示工程等关键技术点，支持复杂的多步骤推理过程。适合那些希望将高质量AI代理应用于真实业务场景中的开发者或团队使用，尤其是在需要高度自定义和灵活性的情况下。",2,"2026-06-11 02:56:00","top_language"]