12-Factor Agents: भरोसेमंद LLM एप्लिकेशन पैटर्न

• 12-Factor Agents एक सार्वजनिक गाइड है जो प्रोडक्शन ग्राहकों को देने लायक भरोसेमंद LLM-आधारित सॉफ़्टवेयर बनाने के लिए 12 सिद्धांतों को व्यवस्थित करता है
• इसका मानना है कि अच्छा एजेंट “prompt और tools का bundle देकर goal तक iterate करना” वाले रूप से अधिक, ज़्यादातर deterministic software में जहाँ ज़रूरत हो वहाँ LLM steps जोड़ने वाली संरचना के करीब होता है
• सामान्य agent loop में LLM अगला चरण structured JSON tool call के रूप में तय करता है, deterministic code उसे चलाता है, फिर परिणाम context window में जोड़ा जाता है, और यह प्रक्रिया पूरा होने तक दोहराई जाती है
• कई SaaS builders framework के साथ तेज़ी से शुरू करके 70~80% quality तक पहुँचते हैं, लेकिन customer-facing features के लिए यह काफ़ी नहीं होता; इसलिए उन्हें framework, prompt, और flow को reverse engineer करना पड़ता है या फिर शुरुआत से दोबारा बनाना पड़ता है
• ग्राहकों तक तेज़ी से high-quality AI software पहुँचाने का सबसे अच्छा तरीका पूरे agent framework को अपनाना नहीं, बल्कि छोटे और modular agent-building concepts को मौजूदा product में integrate करना है

---

प्रोजेक्ट की समस्या-चेतना

• 12-Factor Agents एक सार्वजनिक प्रोजेक्ट है जो 12 Factor Apps की भावना को LLM applications बनाने के सिद्धांतों पर लागू करना चाहता है
• इसका मुख्य सवाल है: “ऐसे कौन से सिद्धांत हैं जिनसे इतना अच्छा LLM-आधारित software बनाया जा सके कि उसे production customers के भरोसे छोड़ा जा सके?”
• यह अलग-अलग agent frameworks आज़माने और YC के भीतर-बाहर के tech founders से बातचीत के अनुभव से शुरू हुआ
  • कई founders production customer-facing agents में frameworks का भारी उपयोग करने के बजाय अपना stack खुद बना रहे हैं
  • “AI Agent” कहलाने वाले कई products पूरी तरह agentic नहीं, बल्कि ज़्यादातर deterministic code में सही जगह LLM steps मिलाने वाले रूप में देखे जाते हैं

एजेंट पर बुनियादी नज़रिया

• अच्छा agent सिर्फ़ “prompt, tools का सेट, और goal पूरा होने तक repetition” पैटर्न से नहीं बनता
• software को directed graph (DG) की तरह देखा जा सकता है, और पहले programs को flowchart में दिखाने की वजह भी यही थी
• लगभग 20 साल पहले से DAG orchestrators का व्यापक उपयोग शुरू हुआ
  • उदाहरण के तौर पर Airflow, Prefect, dagster, inggest, windmill दिए गए हैं
  • ये observability, modularity, retries, और management features जोड़ने वाले graph pattern का पालन करते हैं
• agents का वादा यह है कि engineer हर step और exception को खुद code करने के बजाय सिर्फ़ goal और transitions दे, और LLM real time में path तय करे
  • इस तरीके से कम code लिखने, errors से recover करने, और LLM के नए solutions खोजने की उम्मीद की जाती है
  • लेकिन इसका मानना है कि व्यवहार में यह तरीका उम्मीद जितना अच्छा काम नहीं करता

एजेंट लूप का execution model

• बुनियादी agent loop LLM decision → tool execution → result को context में जोड़ना → repetition से बनता है
• flow इस प्रकार है
  • शुरुआती context कोई starting event होता है, जैसे user message, cron execution, या webhook
  • LLM तय करता है कि अगला step क्या होगा या काम पूरा हुआ या नहीं
  • अगला step structured JSON के रूप में tool call बनकर निकलता है
  • deterministic code उस tool call को execute करता है
  • execution result को context window में जोड़ दिया जाता है
  • अगर अगला step done है, तो final response लौटाया जाता है
• README का उदाहरण llm.determine_next_step(context) से अगला step तय करता है, execute_step(next_step) से उसे चलाता है, और फिर result को context में जोड़ने वाला loop दिखाता है

12 सिद्धांतों की ज़रूरत क्यों है

• HumanLayer बनाते समय कम से कम 100 SaaS builders से बातचीत हुई, और ये आम तौर पर ऐसे tech founders थे जो अपने मौजूदा products को अधिक agentic बनाना चाहते थे
• सामान्य यात्रा कुछ ऐसी होती है
  • agent बनाने का फ़ैसला किया जाता है
  • product design, UX mapping, और हल की जाने वाली समस्या तय की जाती है
  • तेज़ी से आगे बढ़ने के लिए कोई खास framework चुना जाता है
  • 70~80% quality तक पहुँचा जाता है
  • फिर समझ आता है कि 80% quality ज़्यादातर customer-facing features के लिए काफ़ी नहीं है
  • 80% से आगे बढ़ने के लिए framework, prompt, flow वगैरह को reverse engineer करना पड़ता है
  • अंत में शुरुआत से दोबारा बनाना पड़ता है
• यह आलोचना framework या framework बनाने वालों पर हमला नहीं है; इसमें कहा गया है कि frameworks ने AI ecosystem को तेज़ किया है
• इसमें MCP को शामिल नहीं किया गया है, और उदाहरण मुख्य रूप से TypeScript में हैं, लेकिन सिद्धांत Python या दूसरी भाषाओं में भी लागू किए जा सकते हैं

12 factors

• इसका मानना है कि LLMs चाहे लगातार अधिक शक्तिशाली होते जाएँ, फिर भी LLM-आधारित software को अधिक reliable, scalable, और maintainable बनाने वाली मूल engineering techniques बनी रहेंगी
• 12 factors इस प्रकार हैं
  • Factor 1: Natural Language to Tool Calls: natural language को tool calls में बदलना
  • Factor 2: Own your prompts: अपने prompts पर खुद नियंत्रण रखना
  • Factor 3: Own your context window: अपनी context window पर खुद नियंत्रण रखना
  • Factor 4: Tools are just structured outputs: tools सिर्फ़ structured outputs हैं
  • Factor 5: Unify execution state and business state: execution state और business state को एक करना
  • Factor 6: Launch/Pause/Resume with simple APIs: simple APIs से launch, pause, और resume करना
  • Factor 7: Contact humans with tool calls: tool calls के ज़रिए इंसानों से संपर्क करना
  • Factor 8: Own your control flow: अपने control flow पर खुद नियंत्रण रखना
  • Factor 9: Compact Errors into Context Window: errors को context window में संक्षिप्त रूप में समेटना
  • Factor 10: Small, Focused Agents: छोटे और केंद्रित agents
  • Factor 11: Trigger from anywhere, meet users where they are: कहीं से भी trigger करना और users तक वहीं पहुँचना जहाँ वे हैं
  • Factor 12: Make your agent a stateless reducer: अपने agent को stateless reducer बनाना
• अतिरिक्त सलाह के रूप में Factor 13: Pre-fetch all the context you might need शामिल है

लागू करने का तरीका और संबंधित सामग्री

• इसका मानना है कि पूरा framework अपनाकर लगभग greenfield rewrite की ओर जाना उल्टा असर डाल सकता है
• agent को बेहतर बनाने वाले मुख्य सिद्धांत framework अपनाने से अक्सर मिल सकते हैं, लेकिन ग्राहकों तक तेज़ी से high-quality AI software पहुँचाने का रास्ता छोटे और modular concepts को मौजूदा product में integrate करना है
• कहा गया है कि इन modular concepts को AI background न रखने वाले skilled software engineers भी define और apply कर सकते हैं
• संबंधित सामग्री के रूप में Anthropic का Building Effective Agents, Prompts are Functions, Library patterns: Why frameworks are evil, The Wrong Abstraction जुड़े हुए हैं
• content और images CC BY-SA 4.0 के तहत, और code Apache 2.0 लाइसेंस के तहत उपलब्ध हैं

[GN⁺]

Hacker News की राय

• इस लेख के पॉइंट्स शानदार हैं। मैंने कुछ सालों तक खुद करके जो सीखा, उसकी एक सूची भी है: https://mg.dev/lessons-learned-building-ai-agents/
  अगर आज जोड़ना हो, तो सबसे बड़ी बात यह होगी कि सबसे निचले स्तर के planning loop को खुद own करें। Dynamic planning ठीक है, लेकिन observe-orient-decide-act (OODA) loop आपके अपने नियंत्रण में होना चाहिए, और यह तय करने के लिए heuristics (जैसे scoring) या exit conditions (जैसे अधिकतम iteration count) होने चाहिए कि समाधान की ओर converge हो रहे हैं या नहीं
  साथ ही workflow engine जोड़ने पर भी विचार किया जा सकता है। Model से कई turns में implicit workflow बनाए रखने और आगे बढ़ाने के बजाय, बेहतर है कि model से उस engine में चलने वाली workflow specification बनवाई जाए, और हर step पर ज़रूरत पड़ने पर model को फिर call किया जाए

  • यह guide अच्छी है, और खासकर “chat interface बेवकूफी भरा है” वाले नजरिए से सहमत हूं। AI-based UI को अभी बहुत लंबा रास्ता तय करना है

• उत्सुकता है कि DSPY जैसी library factor-2 में कैसे fit होती है: https://dspy.ai/, https://github.com/humanlayer/12-factor-agents/blob/main/con...
  पढ़ते समय देखा कि BAML से prompts generate करने की बात थी। व्यक्तिगत रूप से unstructured data से structured जानकारी निकालने के लिए prompts हाथ से लिखना आसान नहीं लगा, और DSPY के साथ अब तक अनुभव काफी अच्छा रहा है
  अगर BAML के raw prompt का इस्तेमाल किया जाए, तो DSPY के raw prompt इस्तेमाल करने के तरीके को आप कैसे देखते हैं, यह जानना चाहूंगा: https://dspy.ai/tutorials/observability/#using-inspect_histo...

  • दिलचस्प है, लेकिन इस हिस्से में मैं Boundary (YC W23) की तरफ की राय से ज्यादा सहमत हूं। अगर cutting-edge performance चाहिए, तो box खोलकर अंदर की चीजें खुद ठीक कर पाने की क्षमता होनी चाहिए
    https://www.chrismdp.com/beyond-prompting/ इस लेख से पूरी तरह सहमत नहीं हूं, लेकिन punch card → assembly → C → high-level languages वाली तुलना यहां काफी उपयोगी है
    अभी नहीं पता कि सही abstraction कब आएगा, और मुझे नहीं लगता कि LangChain या DSPY अभी AI की “C programming language” हैं। हो सकता है कभी बन जाएं
    फिलहाल मैं ऐसा low-level workbench इस्तेमाल करूंगा जहां tokens inspect कर सकूं, system/user/JSON जैसे special tokens का क्रम बदल सकूं, library support का इंतज़ार करते हुए बंधा न रहूं, और नए models की quirks के हिसाब से तेजी से adjust कर सकूं

• framework patterns पर एक पुराना, कम चर्चित लेख मेरे पूरे career में relevant लगा है, और मुझे लगता है कि यह यहां भी लागू होता है: https://tomasp.net/blog/2015/library-frameworks/
  लेख में बताए कारणों और उससे भी ज्यादा वजहों से, खासकर अभी जब सब कुछ बहुत तेजी से बदल रहा है, LLM को framework से ज्यादा library की तरह इस्तेमाल करना बेहतर है। हालांकि frameworks ज्यादा sexy और बेचने में आसान होते हैं, और lock-in व add-on services तक ले जाते हैं, इसलिए उनका प्रचार ज्यादा होता है

  • यह analogy सच में अच्छी है। Package tour framework खरीदने जैसा है, जहां travel, hotel, meals और activities framework के दिए हुए ढांचे में fit होते हैं। वहीं independent travel कई libraries को combine करने जैसा है, जहां flights, accommodation और itinerary खुद बनानी पड़ती है और यह ज्यादा झंझट वाला है, लेकिन आप अपनी मर्जी से control कर सकते हैं
  • अच्छा है। links section में जोड़ने वाला हूं

• मैंने अपना “AI agent framework” SecAI actor model, state machine और aspect-oriented programming के आधार पर बनाया है और अभी publish किया है: https://github.com/pancsta/secai
  खासकर नंबर 5 “execution state और business state को unify करें” और नंबर 8 “control flow को खुद own करें” पसंद आए। SecAI का core एक graph control flow library है; यह DAG नहीं, बल्कि multigraph इस्तेमाल करता है और LLM calls graph nodes में embedded होते हैं
  Flow को negotiation, cancellation और stateful relationships से मजबूत किया गया है, जिससे यह ज्यादा organic तरीके से काम करता है। इसमें dedicated dev tools (dbg, repl, svg), failure-first programming, हर step को विस्तार से inspect करने की क्षमता, automatic data export (metrics, traces, logs, SQL), और simple integration (bash) भी शामिल हैं, जो दूसरे frameworks में अक्सर नहीं मिलते
  पहला tech demo भी जारी किया है, जिसमें AtomicAgents से port किए गए deepresearch reference implementation के जरिए dev tools दिखाए गए हैं: https://youtu.be/0VJzO1S-gV0
  Send/Stop buttons असल में “Factor 6. simple API से start/pause/resume” हैं, और network transparency भी है, इसलिए यह scalable है

  • इस बात से सहमत हूं कि dedicated dev tools दूसरे frameworks में अक्सर गायब होते हैं। खुद इस्तेमाल करके देखा है कि PydanticAI ने Logfire के साथ agent debugging को सच में बहुत अच्छे से हल किया है, और जिन दूसरे frameworks और libraries को test किया उनसे यह कहीं ज्यादा आसान और प्रभावी था: https://ai.pydantic.dev/logfire/#pydantic-logfire
  • terminal UI और OTel integration पसंद आए। जिज्ञासा है कि अभी इसे किस तरह के कामों में इस्तेमाल कर रहे हैं

• एक और बात जोड़नी हो, तो scale बढ़ने पर cost की planning करनी चाहिए
  ऐसे systems scale पर सस्ते नहीं होते, इसलिए अगर कोई task deterministic components से handle हो सकता है, तो पहले वही try करना बेहतर है। इससे hallucinations और latency कम होती है, और final profit पर भी बड़ा फर्क पड़ सकता है

  • बिल्कुल ऐसा ही लगता है। लोगों में सबसे आम pattern यह दिखता है: “शुरुआत ऐसे तरीके से करें जो धीमा और महंगा है लेकिन development effort कम मांगता है, और फिर speed, quality, cost bottlenecks में जहां निवेश worthwhile लगे, वहां gradually सुधार करें”

• हर principle को follow करना आसान बनाने के लिए, कई factors के आर-पार चलने वाली consistent narrative हो तो अच्छा होगा। अगर वास्तविकता के करीब किसी system example को लगातार इस्तेमाल किया जाए, तो समझना और आसान होगा

  • अच्छा feedback है। सोच रहा हूं किस तरह का use case सही रहेगा
    इसे community के साथ खुले तौर पर लगातार evolve करना चाहता हूं

• शानदार। 80% तो पहले ही मेहनत करके सीख लिया था, और बाकी 20% पढ़ने लायक लग रहा है
  निजी तौर पर मुझे LangGraph + pydantic schema के कॉम्बिनेशन से सफलता मिली है। यह भी जानने की उत्सुकता है कि दूसरों ने कौन-से tools उपयोगी पाए

  • “80% मेहनत करके सीख लिया” वाली बात मज़ेदार है, क्योंकि इस लेख का एक और working title https://github.com/kelseyhightower/kubernetes-the-hard-way की spirit पर Agents the Hard Way था

• यह लेख ठीक उसी समय आया है जब इसकी जरूरत थी
  मैं audiovisual sandbox के आइडिया पर प्रयोग कर रहा हूँ। vvvv जैसा कुछ, लेकिन कहीं ज्यादा सरल और केवल न्यूनतम features वाला: https://kfs.mkj.lt/#audiovisllm, https://vvvv.org/
  आइडिया यह है कि किसी खास काम के लिए और बहुत सीमित output वाले LM या सरल local neural network “nodes” को insert किया जाए। इसलिए “question -> answer: float” जैसे उदाहरण बहुत आकर्षक लगते हैं। मेरे मामले में कुछ सवाल काफी abstract हो सकते हैं, लेकिन multi-step pipeline भी रोचक है

  • LLM का typed output गेम बदल देने वाली चीज़ है

• विस्तार से नहीं पढ़ा, लेकिन मैं जितना संभव हो उतना deterministic code इस्तेमाल करना और LLM का उपयोग न्यूनतम रखना चाहूँगा
  मुझे लगता है कि इससे predictable results, कम operating cost, और यह संकेत मिलता है कि दूसरे लोग उसी app को जल्दी से copy नहीं कर पाएँगे। LLM को दूसरे systems से जोड़ने के लिए buzzword-जैसे glue को ज्यों का त्यों इस्तेमाल करने के बजाय मैं tools खुद बनाने की तरफ रहता हूँ
  अगर ये conditions पूरी न हों या उनकी जरूरत न हो, तो मुझे लगता है कि कोई भी वही solution पल भर में vibe coding से बना सकता है। नियंत्रण बनाए रखना होगा। control वाली hill पर मरने के लिए भी तैयार हूँ। इसका मतलब यह नहीं कि मैं LLM से प्रभावित नहीं हूँ; बल्कि बिल्कुल उलटा है

  • control भी अच्छा है और determinism भी। मूल लक्ष्य यह समझाना है कि “बहुत ज्यादा control मत छोड़ो”, लेकिन secondary goal यह दिखाना है कि “जहाँ थोड़ा control छोड़ा जा सकता है, वे जगहें यही हैं”