ai-agents

What this skill does

# AI Agents Development — Production Skill Hub

**Modern Best Practices (March 2026)**: deterministic control flow, bounded tools, auditable state, MCP-based tool integration, handoff-first orchestration, multi-layer guardrails, OpenTelemetry tracing, and human-in-the-loop controls (OWASP LLM Top 10: https://owasp.org/www-project-top-10-for-large-language-model-applications/).

This skill provides **production-ready operational patterns** for designing, building, evaluating, and deploying AI agents.
It centralizes **procedures**, **checklists**, **decision rules**, and **templates** used across RAG agents, tool-using agents, OS agents, and multi-agent systems.

No theory. No narrative. Only operational steps and templates.

---

## When to Use This Skill

Codex should activate this skill whenever the user asks for:

- Designing an agent (LLM-based, tool-based, OS-based, or multi-agent).
- Scoping capability maturity and rollout risk for new agent behaviors.
- Creating action loops, plans, workflows, or delegation logic.
- Writing tool definitions, MCP tools, schemas, or validation logic.
- Generating RAG pipelines, retrieval modules, or context injection.
- Building memory systems (session, long-term, episodic, task).
- Creating evaluation harnesses, observability plans, or safety gates.
- Preparing CI/CD, rollout, deployment, or production operational specs.
- Producing any template in `/references/` or `/assets/`.
- Implementing MCP servers or integrating Model Context Protocol.
- Setting up agent handoffs and orchestration patterns.
- Configuring multi-layer guardrails and safety controls.
- **Evaluating whether to build an agent** (build vs not decision).
- **Calculating agent ROI**, token costs, or cost/benefit analysis.
- **Assessing hallucination risk** and mitigation strategies.
- **Deciding when to kill** an agent project (kill triggers).
- For prompt scaffolds, retrieval tuning, or security depth, see Scope Boundaries below.

## Scope Boundaries (Use These Skills for Depth)

- **Prompt scaffolds & structured outputs** → [ai-prompt-engineering](../ai-prompt-engineering/SKILL.md)
- **RAG retrieval & chunking** → [ai-rag](../ai-rag/SKILL.md)
- **Search tuning (BM25/HNSW/hybrid)** → [ai-rag](../ai-rag/SKILL.md)
- **Security/guardrails** → [ai-mlops](../ai-mlops/SKILL.md)
- **Inference optimization** → [ai-llm-inference](../ai-llm-inference/SKILL.md)

## Default Workflow (Production)

- Pick an architecture with the Decision Tree (below); default to **workflow/FSM/DAG** for production.
- Draft an agent spec with [`assets/core/agent-template-standard.md`](assets/core/agent-template-standard.md) (or [`assets/core/agent-template-quick.md`](assets/core/agent-template-quick.md)).
- Specify tools and handoffs with JSON Schema using [`assets/tools/tool-definition.md`](assets/tools/tool-definition.md) and [`references/api-contracts-for-agents.md`](references/api-contracts-for-agents.md).
- Add retrieval only when needed; start with [`assets/rag/rag-basic.md`](assets/rag/rag-basic.md) and scale via [`assets/rag/rag-advanced.md`](assets/rag/rag-advanced.md) + [`references/rag-patterns.md`](references/rag-patterns.md).
- Add eval + telemetry early via [`references/evaluation-and-observability.md`](references/evaluation-and-observability.md).
- Run the go/no-go gate with [`assets/checklists/agent-safety-checklist.md`](assets/checklists/agent-safety-checklist.md).
- Plan deploy/rollback and safety controls via [`references/deployment-ci-cd-and-safety.md`](references/deployment-ci-cd-and-safety.md).

---

## Quick Reference

| Agent Type | Core Control Flow | Interfaces | MCP/A2A | When to Use |
|------------|-----------|------------|---------|-------------|
| **Workflow Agent (FSM/DAG)** | Explicit state transitions | State store, tool allowlist | MCP | Deterministic, auditable flows |
| **Tool-Using Agent** | Route → call tool → observe | Tool schemas, retries/timeouts | MCP | External actions (APIs, DB, files) |
| **RAG Agent** | Retrieve → answer → cite | Retriever, citations, ACLs | MCP | Knowledge-grounded responses |
| **Planner/Executor** | Plan → execute steps with caps | Planner prompts, step budget | MCP (+A2A) | Multi-step problems with bounded autonomy |
| **Multi-Agent (Orchestrated)** | Delegate → merge → validate | Handoff contracts, eval gates | A2A | Specialization with explicit handoffs |
| **OS Agent** | Observe UI → act → verify | Sandbox, UI grounding | MCP | Desktop/browser control under strict guardrails |
| **Code/SWE Agent** | Branch → edit → test → PR | Repo access, CI gates | MCP | Coding tasks with review/merge controls |

### Framework Selection (March 2026)

**Tier 1 — Production-Grade**

| Framework | Architecture | Best For | Languages | Ease |
|-----------|--------------|----------|-----------|------|
| **LangGraph** | Graph-based, stateful | Enterprise, compliance, auditability | Python, JS | Medium |
| **Claude Agent SDK** | Event-driven, tool-centric | Anthropic ecosystem, Computer Use, MCP-native | Python, TS | Easy |
| **OpenAI Agents SDK** | Tool-centric, lightweight | Fast prototyping, OpenAI ecosystem | Python | Easy |
| **Google ADK** | Code-first, multi-language | Gemini/Vertex AI, polyglot teams | Python, TS, Go, Java | Medium |
| **Pydantic AI** | Type-safe, graph FSM | Production Python, type safety, MCP+A2A native | Python | Medium |
| **MS Agent Framework** | Kernel + multi-agent | Enterprise Azure, .NET/Java teams | Python, .NET, Java | Medium |

**Tier 2 — Specialized**

| Framework | Architecture | Best For | Languages | Ease |
|-----------|--------------|----------|-----------|------|
| **LlamaIndex** | Event-driven workflows | RAG-native agents, retrieval-heavy | Python, TS | Medium |
| **CrewAI** | Role-based crews | Team workflows, content generation | Python | Easiest |
| **Mastra** | Vercel AI SDK-based | TypeScript/Next.js teams | TypeScript | Easy |
| **SmolAgents** | Code-first, minimalist | Lightweight, fewer LLM calls | Python | Easy |
| **Agno** | FastAPI-native runtime | Production Python, 100+ integrations | Python | Easy |
| **AWS Bedrock Agents** | Managed infrastructure | Enterprise AWS, knowledge bases | Python | Easy |

**Tier 3 — Niche**

| Framework | Niche |
|-----------|-------|
| **Haystack** | Enterprise RAG+agents pipeline (Airbus, NVIDIA) |
| **DSPy** | Declarative optimization — compiles programs into prompts/weights |

See [`references/modern-best-practices.md`](references/modern-best-practices.md) for detailed comparison and selection guide.

### Framework Deep Dives

- **Claude Agent SDK** - [`references/claude-agent-sdk-patterns.md`](references/claude-agent-sdk-patterns.md)
  Agent definition, built-in tools (Bash, TextEditor, Computer), MCP servers, guardrails, multi-agent, streaming events
- **Pydantic AI** - [`references/pydantic-ai-patterns.md`](references/pydantic-ai-patterns.md)
  Type-safe agents, MCP toolsets, native A2A, pydantic-graph FSM, durable execution, HITL, TestModel testing

---

## Decision Tree: Choosing Agent Architecture

```text
What does the agent need to do?
    ├─ Answer questions from knowledge base?
    │   ├─ Simple lookup? → RAG Agent (LangChain/LlamaIndex + vector DB)
    │   └─ Complex multi-step? → Agentic RAG (iterative retrieval + reasoning)
    │
    ├─ Perform external actions (APIs, tools, functions)?
    │   ├─ 1-3 tools, linear flow? → Tool-Using Agent (LangGraph + MCP)
    │   └─ Complex workflows, branching? → Planning Agent (ReAct/Plan-Execute)
    │
    ├─ Write/modify code autonomously?
    │   ├─ Single file edits? → Tool-Using Agent with code tools
    │   └─ Multi-file, issue resolution? → Code/SWE Agent (HyperAgent pattern)
    │
    ├─ Delegate tasks to specialists?
    │   ├─ Fixed workflow? → Multi-Agent Sequential (A → B → C)
    │   ├─ Manager-Worker? → Multi-Agent Hierarchical (Manager + Workers)
    │   └─ Dynamic routing? → Multi-Agent Group Chat (collaborative)
    │
    ├─ Control desktop/browser?
    │   └─ OS Agen