Production playbook — patterns, anti-patterns, and deployment guidance.
This guide covers the engineering patterns for building production-quality AI features with AFK. It’s organized around three phases: starting narrow, adding capabilities, and scaling safely.
The most common mistake is building for complexity you don’t have yet. Start with the simplest version that solves the problem, then add capabilities based on real evidence.
[!TIP]
Test at every step. Don’t add tools before the base prompt works. Don’t add subagents before single-agent tools work. Each layer should be proven before adding the next.
Categorize input into predefined labels. No tools needed.
agent = Agent( name="classifier", model="gpt-5.5", instructions=""" Classify the support ticket into exactly one category: billing, technical, account, feature-request, other. Output only the category name, nothing else. """,)
Tips:
Constrain output format explicitly in the prompt
Test with a diverse set of inputs
Add evals for each category
Retrieve context, then generate an answer.
@tool(args_model=SearchArgs, name="search_docs", description="Search the knowledge base.")def search_docs(args: SearchArgs) -> dict: results = vector_db.search(args.query, top_k=5) return {"results": [r.text for r in results]}agent = Agent( name="rag-agent", model="gpt-5.5", instructions=""" Always search the knowledge base before answering. Cite sources. If no relevant docs found, say so. """, tools=[search_docs],)
Tips:
Always search before answering
Instruct the model to cite sources
Set tool_output_max_chars to prevent context overflow
Generate, review, and test code.
@tool(args_model=TestArgs, name="run_tests", description="Run the test suite.")def run_tests(args: TestArgs) -> dict: result = subprocess.run(["pytest", args.test_path], capture_output=True) return {"exit_code": result.returncode, "output": result.stdout[:4000]}agent = Agent( name="coder", model="gpt-5.5", instructions=""" Write code, then run the tests to verify. Fix any failures before presenting the final version. """, tools=[read_file, write_file, run_tests], fail_safe=FailSafeConfig( max_steps=20, max_tool_calls=15, max_total_cost_usd=1.00, ),)
