How to build an AI agent, with evals from day one

To build an AI agent, start with the simplest design that can do the job: a model, a few tools it can call, and a loop that runs until the model gives a final answer or hits a stop condition. Write a small set of evals before you add complexity, and add structure (more agents, more steps) only when the evals show the simple version falls short.

The advice below comes from Anthropic’s and OpenAI’s own documentation, and the code is quoted from the official docs.

Decide whether you need an agent

Anthropic separates two designs in Building effective agents (published Dec 19, 2024):

• Workflows: “systems where LLMs and tools are orchestrated through predefined code paths.”
• Agents: systems where “LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks.”

Its advice is to find “the simplest solution possible, and only increasing complexity when needed”, and that “optimizing single LLM calls with retrieval and in-context examples is usually enough.” Workflows suit well-defined tasks. Agents are “the better option when flexibility and model-driven decision-making are needed at scale.”

Design	Who picks the next step	Use it when
Single LLM call	You	Retrieval and examples are enough
Workflow	Your code	The steps are known in advance
Agent	The model	The steps depend on what it finds

Pick a workflow pattern first

The same guide lists five workflow patterns. Each is a place to stop before you reach a full agent.

Pattern	What it does (Anthropic’s wording)
Prompt chaining	“decomposes a task into a sequence of steps, where each LLM call processes the output of the previous one.”
Routing	“classifies an input and directs it to a specialized followup task.”
Parallelization	“LLMs can sometimes work simultaneously on a task and have their outputs aggregated programmatically.”
Orchestrator-workers	“a central LLM dynamically breaks down tasks, delegates them to worker LLMs, and synthesizes their results.”
Evaluator-optimizer	“one LLM call generates a response while another provides evaluation and feedback in a loop.”

Source: Anthropic. The Anthropic post predates the current SDKs, and it notes that much of its tooling has changed since. The patterns still describe the shapes most agent frameworks implement.

The agent loop

Anthropic describes agents as “typically just LLMs using tools based on environmental feedback in a loop.” At each step the agent should “gain ‘ground truth’ from the environment”, such as a tool result, and it is “common to include stopping conditions (such as a maximum number of iterations).”

The OpenAI Agents SDK documents the same loop. It calls the model for the current agent. If the output is final, the loop ends. If the model requests a handoff, the SDK updates the current agent and re-runs the loop. If the model makes tool calls, the SDK runs them, appends the results and re-runs the loop. Past max_turns it raises MaxTurnsExceeded.

input -> model -> tool call? -> run tool -> append
           ^                                 |
           '---------------------------------'
model -> final output -> done
(or max turns -> stop)

Build the smallest version

The OpenAI Agents SDK quickstart defines an agent as a name plus instructions, and runs it with Runner:

agent = Agent(
    name="History Tutor",
    instructions="You answer history questions clearly and concisely.",
)

result = await Runner.run(agent, "When did the Roman Empire fall?")
print(result.final_output)

The SDK’s home page describes agents as “LLMs equipped with instructions and tools”, with handoffs that “allow agents to delegate to other agents for specific tasks”, guardrails that “enable validation of agent inputs and outputs” and sessions as “a persistent memory layer for maintaining working context within an agent loop.” Other frameworks name these parts differently. See LangGraph and Pydantic AI for two more.

Build order that follows from the sources:

1. Write the task and the success criteria in plain words.
2. Write the first evals (next section).
3. Start with one model call, with retrieval or examples if needed.
4. Add tools, then the loop, then a turn limit.
5. Add handoffs or sub-agents only if the evals show one agent cannot do the job.

Design the tools carefully

Anthropic’s third principle is to “carefully craft your agent-computer interface (ACI) through thorough tool documentation and testing.” Its tool tips:

• “Put yourself in the model’s shoes.” Ask whether the tool description is clear without extra context.
• Write the tool description like “a great docstring for a junior developer on your team.”
• “Test how the model uses your tools” and fix the mistakes you see.
• “Poka-yoke your tools. Change the arguments so that it is harder to make mistakes.”

Its other two principles are to “maintain simplicity in your agent’s design” and to “prioritize transparency by explicitly showing the agent’s planning steps.” Tools that follow a standard protocol are covered in Model Context Protocol.

Write evals before you scale

Anthropic’s Demystifying evals for AI agents (Jan 9, 2026) gives the vocabulary:

Term	Definition
Eval	“a test for an AI system: give an AI an input, then apply grading logic to its output to measure success”
Task	“a single test with defined inputs and success criteria”
Trial	“Each attempt at a task”
Grader	“logic that scores some aspect of the agent’s performance”
Transcript	“the complete record of a trial, including outputs, tool calls, reasoning, intermediate results”

It says agent evals “typically combine three types of graders: code-based, model-based, and human.” On size: “20-50 simple tasks drawn from real failures is a great start”, and “Start early and don’t wait for the perfect suite.” It recommends “eval-driven development: build evals to define planned capabilities before agents can fulfill them.”

For how to score outputs, see LLM evaluation.

Trace every run

An eval tells you a run failed. A trace shows which step failed. The OpenAI Agents SDK says tracing “lets you visualize and debug your agentic flows”, and the quickstart points to the Trace viewer in the OpenAI Dashboard. Loops, repeated tool errors and runs that stop at the turn limit all show up in a trace of the full task. See agent observability.

How to do this in HoneyHive

HoneyHive is one of several tools for tracing and evaluating agents, and the steps above work with any of them. Its docs cover both halves:

• Tracing: the tracing quickstart instruments an OpenAI call with pip install honeyhive openai openinference-instrumentation-openai (Python 3.11 or later) and sends the first trace to the Traces page.
• Evals: the experiments quickstart walks through writing the function to test, a dataset of inputs with expected outputs, an evaluator, and a run with evaluate(). Evaluators can be code-based checks, LLM-as-judge scorers or human review, per the evaluation docs.
• CI: the CI regression detection guide covers gating pull requests on evaluation metrics with GitHub Actions.

FAQ

Do I need a framework to build an AI agent?

Not to start. The OpenAI Agents SDK quickstart is a few lines of code, and Anthropic recommends "the simplest solution possible". Frameworks such as LangGraph and Pydantic AI become useful once the loop, tools and state outgrow a script.

When should I build an agent instead of a workflow?

Use a workflow when the steps are known in advance and an agent when the model must choose the steps as it goes. Anthropic recommends "the simplest solution possible", and says a single LLM call with retrieval and examples is often enough.

How many evals do I need before I start?

Fewer than most teams think. Anthropic's evals guide calls "20-50 simple tasks drawn from real failures" a great start, and advises starting early rather than waiting for a perfect suite.