Agent Development Without the Mystery

An Agent is easier to understand once you stop treating it as a special kind of intelligence. In software terms, it is usually a loop around a language model. The model reads the current state, decides whether to answer or use a tool, receives the tool result, and makes another decision.

That loop can search documents, call an API, write a file, or ask a person for approval. The model chooses the next action, but ordinary code still controls what actions exist and what the system is allowed to do.

This article explains the parts you need for a first Agent and the engineering work that turns a demo into a dependable application.

Start with the task, not the framework

Before choosing a library, write down one job the Agent should complete. "Help users with research" is too broad. "Find three relevant sources, extract their publication dates, and return a cited summary" is testable.

A useful task definition answers four questions:

• What input does the Agent receive?
• What result counts as complete?
• Which actions may it take?
• Which actions require human approval?

The stop condition matters as much as the prompt. Without one, an Agent can repeat a failed tool call, keep gathering unnecessary context, or spend far more tokens than the task is worth. Set a maximum number of steps, a time limit, and a clear success condition in code.

The smallest useful execution loop

Most tool-using Agents follow the same basic flow:

User request
    |
    v
Build model context
    |
    v
Model chooses: answer or tool call
    |                  |
    | answer           | tool call
    v                  v
Return result      Validate and run tool
                       |
                       v
                 Add observation to state
                       |
                       +----> call model again

A framework-neutral version looks like this:

async def run_agent(request, tools, max_steps=8):
    state = [{"role": "user", "content": request}]

    for _ in range(max_steps):
        decision = await model.respond(messages=state, tools=tools.schemas())

        if decision.final_answer:
            return decision.final_answer

        call = tools.validate(decision.tool_call)
        result = await tools.execute(call)
        state.extend([decision.as_message(), result.as_message()])

    raise RuntimeError("Agent reached the step limit")

The language model supplies decision. Your application owns everything around it: tool definitions, validation, execution, state, limits, and error handling. Keeping that boundary visible makes the system easier to debug.

Instructions give the Agent a working contract

A system prompt should tell the Agent what job it has, what information it can trust, how it should use tools, and when it must stop or ask for help. Long prompts are not automatically better. A short contract with specific rules is easier to test than several pages of advice.

For a source research Agent, the contract might say:

Find sources relevant to the user's question.
Use search_source before making factual claims.
Keep the source URL with every extracted fact.
If sources disagree, report the disagreement.
Return a cited summary after enough evidence is available.
Do not invent a citation when a search fails.

Prompt rules cannot enforce security. If a tool must never delete production data without approval, put that rule in application code.

Tools are APIs for the model

A tool is a function the model can request. Its name, description, and input schema are part of the Agent's interface. Vague tools lead to vague behavior.

Prefer a small tool with an explicit contract:

async def search_source(query: str, limit: int = 5) -> list[SearchResult]:
    """Return up to `limit` sources that match a focused search query."""

Avoid a catch-all tool such as do_research(data: dict). The model has to guess what belongs in data, and your logs will not explain what action it intended.

Tool code should validate arguments at the boundary. It should also return useful failures. "Search timed out after 10 seconds" gives the Agent a chance to retry with a smaller query. A raw stack trace usually does not.

Tool descriptions deserve tests because the model sees them as instructions. Check common requests, invalid arguments, empty results, timeouts, and permission failures. You do not need a separate Agent for every tool. One Agent with a clear set of tools is often enough.

State and memory solve different problems

State is the information needed for the current run. It may contain conversation messages, completed steps, tool results, a token budget, and approval status.

Memory carries selected information across runs. A support Agent might remember a user's product preference. A coding Agent might remember repository conventions. Saving the whole conversation forever is rarely a good memory strategy. It increases cost, exposes old sensitive data, and makes irrelevant details compete for attention.

Use three practical buckets:

• Current state for the active task
• A short summary for long conversations
• Persistent memory for facts that remain useful later

Define who can write persistent memory and how users can correct or delete it. A wrong memory can quietly affect every later answer.

Use workflows where order matters

An Agent loop is useful when the next action depends on incomplete information. Ordinary code is better when the order is already known.

Suppose an expense system must parse a receipt, validate the amount, request approval above a limit, and write an accounting record. Those steps have business meaning. Put them in a workflow. The model may help parse the receipt or explain an exception, but it should not decide whether validation happens.

A practical application often mixes both styles:

Deterministic input checks
          |
          v
Agent gathers missing information
          |
          v
Deterministic policy check
          |
          v
Human approval when required
          |
          v
Deterministic write

This split keeps flexible reasoning where it helps and predictable control where the business requires it.

Put approval in front of consequences

Reading a public page and sending an email are different kinds of action. Classify tools by risk before giving them to the Agent.

Read-only tools can often run automatically. Actions that publish content, move money, delete data, change permissions, or contact another person should usually pause for approval. The approval screen needs to show the exact action and arguments, not a vague message such as "The Agent wants to continue."

Also protect tools from prompt injection. Text returned by a website, document, or email is data, even when it contains instructions. Do not let retrieved text grant itself permission to call a sensitive tool.

Failure is part of the loop

Tools time out. APIs rate-limit requests. Models produce invalid arguments. Users change their minds halfway through a task. Plan these cases before deployment.

For each tool, decide:

• Whether a retry is safe
• How many retries are allowed
• Whether the same request could create a duplicate side effect
• What the Agent should tell the user when recovery fails

Use idempotency keys for actions that may be retried, such as creating an order or sending a job to a queue. Keep retry policy in code. The model can choose a different approach after an error, but it should not control an unlimited retry loop.

Trace decisions, not hidden reasoning

You need a record of what the system did: model requests, tool names, validated arguments, tool results, latency, token usage, state changes, approvals, and the final outcome.

Do not depend on private chain-of-thought text for debugging. Observable actions are more useful and easier to handle safely. A trace should let you answer practical questions:

• Which tool failed?
• What input reached it?
• Did the Agent repeat the same action?
• Where did time and tokens go?
• Was the final task actually completed?

Redact secrets and personal data before storing traces. Debugging data is still production data.

Evaluate the task, not the tone

A response can sound confident and still fail the job. Evaluate complete outcomes.

For a research Agent, useful checks include source validity, citation coverage, factual agreement with sources, unnecessary tool calls, cost, and completion time. For an action Agent, also check whether it followed approval and permission rules.

Start with a small set of real examples. Include normal requests, ambiguous requests, missing data, tool failures, and hostile content inside retrieved documents. Save failures as regression cases. This gives you a better signal than asking whether a handful of demo conversations look good.

A sensible build order

Build one narrow path first:

1. Define one task and its stop condition.
2. Add the minimum tools needed for that task.
3. Run the loop with a hard step limit.
4. Record traces and inspect failures.
5. Add approval before sensitive actions.
6. Create an evaluation set from real examples.
7. Add memory or multiple Agents only when a measured problem calls for them.

The last point saves a lot of work. Multi-agent coordination does not repair an unclear task, a weak tool contract, or missing evaluation. A small Agent with good boundaries is a better first system because you can see why it succeeds and why it fails.