What OpenAI's Agents API actually gives you

Why code belongs inside some agent runs

Consider an incident investigation that produces more logs than the model should read directly. Programmatic tool calling lets code fetch, filter and aggregate those logs, then return the smaller result the model needs to interpret[11]. That is a division of labour. The model chooses and explains; code performs repeatable reduction.

It is also why “just give the model all the context” is a poor architecture. Raw data can be expensive to move, hard to inspect and easy to truncate. A programmatic step should produce a named artifact with the filters, time window and row counts retained beside it. Do not hide the method inside a clever prompt.

Compaction is continuity, not memory magic

Long investigations need a way to continue after the working context becomes crowded. Compaction creates a summary of earlier work so the agent can proceed[7]. That summary is useful, but it is still a derived representation. Keep the original tool results and decisions in files or structured state so a reviewer can recover the evidence.

The practical rule is simple: summarise for continuity, preserve for verification. A compacted context should point to the evidence it summarises, name unresolved uncertainty and state what the agent is allowed to do next.

Does an agent automatically create a swarm?

No. Multi-agent orchestration is an optional design choice. The current SDK describes two common patterns. With agents as tools, a manager keeps control and asks a specialist for a bounded result. With a handoff, a triage agent transfers the active conversation to a specialist[12].

One useful arrangement is to let a specialist inspect recent code changes while another checks telemetry, then ask a lead agent to unify the findings[1]. That is a sensible pattern when the work is genuinely independent and the merge is reviewable. It is wasteful when the task is a short lookup or when no one can say what each specialist is responsible for.

Workflow or agent?

A fixed workflow and an agent are not competing moral positions. They are different control choices. Anthropic's architecture guidance recommends starting with the simplest augmented model, adding a workflow when the path is predictable and using an agent when the model needs to direct flexible steps[13].

Choose the control shape

Let the uncertainty decide.

Keep the boundaries deterministic even when the route inside them is adaptive.

Known path

Use a workflow.

Choose it when the same stages run in the same order, each stage has a clear input and output, and a normal program can validate the transition. A scheduled report with fixed extracts and checks belongs here.

Changing evidence

Use an agent inside boundaries.

Choose it when the next useful action depends on what the previous tool reveals, the evidence is messy and a person would normally investigate by choosing among several known actions.

Mixed work

Use both.

Put permissions, schemas, review gates and output formats in ordinary code. Let the agent choose the bounded investigation steps between those gates.

A Digital Performance Investigation Agent

Imagine a request: “Investigate the fall in paid-search enquiries last week and prepare a report for the performance meeting.” The following is a proposed architecture, not a deployed Meeno system and not a result from real data.

1. Define the contract.

   Record the site, channel, local-time window, enquiry event, comparison period, source systems and the decision the report will support.

2. Give the lead agent read-only tools.

   It can query approved analytics, retrieve the release log and read the measurement runbook. It cannot edit tags, publish a campaign or change a dashboard.

3. Let code reduce the evidence.

   A programmatic call groups events by day, checks the event definition and writes a small evidence file with filters and freshness attached.

4. Delegate only when the evidence requires it.

   A telemetry specialist can inspect a release change or a data-quality specialist can reconcile a missing day. Each returns a structured finding, uncertainty and source reference.

5. Assemble a report.

   The lead agent separates observed change, possible explanations, evidence still missing and suggested next checks. It does not call a correlation a cause.

6. Pause for the meeting owner.

   A human accepts the scope and decides what action to take. The run ends with a shareable report and its evidence bundle.

The interesting part is the contract and the stop condition. The agent is allowed to investigate, not to turn an uncertain explanation into a production change. That boundary makes the result easier to review and the next run easier to improve.

A safer way to build the first one

Start small enough that a person can inspect every turn. The OpenAI SDK documentation recommends monitoring, specialised agents where they are useful, structured outputs and evals as systems become more complex[12]. A practical sequence is:

1. Start with one bounded agent

   One agent, one read-only tool and one defined output.

2. Make the output inspectable

   Structured output with explicit unknowns, sources and stop reasons.

3. Test the failure paths

   Trace the run and test tool errors, empty results, stale data and refusal paths.

4. Reuse a stable procedure

   Add a skill when the procedure is stable enough to reuse.

5. Connect a separate system

   Add MCP when a separate system needs a standard, permissioned connector.

6. Contain code execution

   Add a sandbox when code, files or packages need an execution boundary.

7. Add a specialist selectively

   Add a specialist only when the subtask is independent and its handoff can be checked.

8. Keep the human decision gate

   Keep a human approval gate for consequential actions and publish a report of what happened.

OpenAI's SDK provides deterministic testing utilities for SDK-owned tool execution, handoffs, guardrails, retries, sessions and sandbox capabilities, while provider behaviour still needs integration testing[14]. That distinction is easy to lose in a demo. A green orchestration test proves that the plumbing followed the contract; it does not prove that the model understood a messy business question.

The question to ask before adding another agent

Before you add a specialist, ask: What decision will this extra agent make, what evidence will it receive, and how will the lead agent know whether its answer is usable? If those answers are vague, another agent will add motion without adding control.

The useful boundary is this: a model can sit inside a longer, tool-using, observable run without you writing every piece of session and context plumbing from scratch. The engineering responsibility remains yours: define the boundary, keep the evidence visible, test the handoff and give a person a clear place to stop the system.