You can ship a working AI agent in an afternoon with about 150 lines of code. The hard part isn't building — it's making it reliable, observable, and safe in production. Here's the practical guide.
For background on what an agent actually is, see our agent glossary and agentic loop entries.
The minimum viable agent in 2026
Every AI agent boils down to this pattern:
1. Read the goal
2. Plan the steps (optional but improves quality)
3. Loop:
- LLM decides next action
- Execute tool call
- Observe result
4. Stop when goal met or limit hit
5. Return result
That's it. Everything else is implementation detail.
Quickest path: vendor SDK + Python
Skip the framework decisions. Use the SDK from whichever model vendor you use most.
Anthropic Agent SDK (Claude):
from anthropic import Anthropic
client = Anthropic()
# Define tools
tools = [
{
"name": "get_weather",
"description": "Get the current weather for a city",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}
]
# Agent loop
def run_agent(goal, max_iterations=10):
messages = [{"role": "user", "content": goal}]
for _ in range(max_iterations):
response = client.messages.create(
model="claude-sonnet-4-6-20260101",
max_tokens=4096,
tools=tools,
messages=messages
)
if response.stop_reason == "end_turn":
return response.content
# Handle tool calls
for block in response.content:
if block.type == "tool_use":
result = execute_tool(block.name, block.input)
messages.append({"role": "assistant", "content": response.content})
messages.append({
"role": "user",
"content": [{
"type": "tool_result",
"tool_use_id": block.id,
"content": str(result)
}]
})
That's your basic agent. ~30 lines of real logic.
OpenAI Agents SDK — same pattern, slightly different API surface. Both are now mature.
When you actually need a framework
The vendor SDKs are enough for ~80% of agent use cases in 2026. Add a framework when:
You have branching control flow. Multiple paths depending on intermediate results. → Use LangGraph.
You have stateful long-running agents. Memory across sessions, persistent state. → Use LangGraph or roll your own state layer.
You have role-based multi-agent setups. Several specialized agents collaborating. → Use CrewAI.
You need standardized observability across agents. → Helicone, LangSmith, or Braintrust regardless of framework.
For most product work in 2026: vendor SDK + a tiny custom state layer beats picking a framework. See AI agent framework for the broader comparison.
The four design decisions that matter
When building an agent, these four decisions determine everything else:
1. Tool set design
Wrong: Give the agent 50 tools and hope it picks the right one. Right: 5-15 carefully designed tools with clear, non-overlapping descriptions.
Tool descriptions are prompts. Write them like you'd write a spec for a junior engineer: what does it do, when to use it, what it returns, what to avoid.
See our tool use glossary entry.
2. System prompt
The single highest-leverage knob in your agent. Production system prompts are real software — 1-4K tokens, tested, versioned, evaluated.
Three things every agent's system prompt needs:
- Identity and capabilities. Who is this agent, what can it do, what should it refuse.
- Tool guidance. When to use each tool, when not to.
- Output format. How to structure responses, when to ask clarifying questions.
See system prompt.
3. Stop conditions
When does the agent decide it's done?
Wrong: Run until the LLM stops emitting tool calls. Right: Explicit stop conditions — goal achieved, max iterations hit, error threshold exceeded, user intervention needed.
Most agents fail by either stopping too early (incomplete work) or running forever (infinite loops). Stop conditions are how you make this reliable.
4. Approval gates
For irreversible actions — sending emails, deploying code, charging cards, deleting data — gate explicitly.
def execute_tool(name, input):
if name in IRREVERSIBLE_TOOLS:
if not get_user_approval(name, input):
return "User declined to approve this action"
return ACTUAL_TOOL_HANDLERS[name](input)
See human-in-the-loop for the broader pattern.
Adding MCP to your agent
In 2026, MCP is the way to give your agent access to common tools without writing custom code for each one.
For your custom agent, MCP gives you:
- Pre-built integrations with GitHub, Linear, Slack, Notion, Sentry, Postgres, and 50+ more
- Standard protocol so any future tool you add works without custom wiring
- The same tools your team already uses in Cursor or Claude Code
Most vendor SDKs in 2026 ship with MCP client libraries. See Best MCP servers in 2026 for what to install.
Production-grade requires evals
The single biggest jump from "working agent" to "production agent" is evals.
Eval set: 50-200 input/expected-output pairs covering top intents and known failure modes. Run on every prompt change or model swap.
Tools: Braintrust, Promptfoo, or LangSmith. All let you run an eval suite as a one-command CI step.
Without evals, you have a demo. With evals, you have a product.
See AI evals.
The observability layer
Production agents need LLM observability. At minimum:
- Trace every LLM call. Prompt, response, tokens, latency, cost.
- Trace every tool call. Inputs, outputs, errors, latency.
- Aggregate cost per user / per request.
- Watch for failure patterns. Tool errors, hallucinations, jailbreaks.
Tools: Helicone (free tier excellent), LangSmith (LangGraph-native), Braintrust (combines evals + observability), Arize (broader APM).
Add observability before launch, not after the first incident.
Guardrails — the security layer
Three layers of guardrails:
1. Input filtering. Detect prompt injection, PII, off-topic queries before they hit the LLM.
2. Output classification. Re-classify model outputs before they reach the user. Catch policy violations, hallucinations on critical claims, leaked secrets.
3. Tool-call allowlists. The agent can only call tools the deployment has explicitly authorized. Don't trust the LLM to obey your system prompt's restrictions; enforce in code.
Tools: NeMo Guardrails, Llama Guard, Lakera, or custom.
Cost optimization — don't skip this
Three patterns that cut agent costs 50-90%:
1. Prompt caching. Anthropic and OpenAI both cache system prompts at 50-90% discount. Structure your prompts to put stable content at the top.
2. Model routing. Use a strong model for planning and verification; a cheaper model for routine tool calls. Most agents over-use frontier models.
3. Stop conditions. Aggressive max-iteration limits prevent runaway costs from infinite loops.
See TCO calculator for cost modeling at your scale.
A realistic timeline
What it actually takes to ship a production-grade agent:
| Phase | Time | Output |
|---|---|---|
| MVP — working agent | 1-3 days | Demo |
| Tool design + system prompt iteration | 1-2 weeks | Reliable on common cases |
| Evals + first benchmark | 1-2 weeks | Quantified quality baseline |
| Observability + monitoring | 3-5 days | Production debugging |
| Guardrails + security review | 1-2 weeks | Launchable |
| Cost optimization + scaling | 1 week | Sustainable economics |
| Total | 5-8 weeks | Production-grade |
The most common mistake: shipping the MVP and treating it as production. The follow-up work matters more than the build.
Three patterns that don't work
After watching dozens of agent projects, three failure modes recur:
1. "Just plug LangChain in." LangChain abstractions add accidental complexity. For most agents, vendor SDK is simpler and more debuggable.
2. "Add more tools." Beyond 15-20 tools, agent reliability drops sharply. The right move is fewer, better tools — or splitting into specialized sub-agents.
3. "Skip evals because we'll iterate." Without evals you can't tell if iteration is improving or regressing quality. Build the eval suite before you optimize the prompt.