OpenAI Agents API: The Harness Is Now a Product. Your Agent Design Still Is Not.

OpenAI's Agents API puts a useful sentence into production: the harness can be somebody else's product. The public beta exposes a managed loop for long-running work, including durable sessions, context management, tool use, hosted or external environments, and parallel subagents. That removes a pile of plumbing that many teams were rebuilding, unevenly, around each new model release.

It does not remove the work that makes an agent trustworthy in a real product. An agent still needs a task contract, an authorization model, a source of truth, a budget, an approval path, and evidence that it did what it claims. The API can operate the loop. It cannot know whether your billing system, deployment pipeline, customer records, or codebase should be changed.

The useful mental model is simple: the harness is the runtime; the agent design is the product. Confusing the two is how a clean demo turns into a very expensive helper with production credentials.

What OpenAI Actually Shipped

OpenAI introduced the Agents API as a public beta built on the harness behind Codex. A session is created with an agent configuration, a task, tools, optional vaults, and an execution environment. OpenAI operates the harness while the developer chooses the environment, capabilities, and workflow-specific context.

The Runtime Owns the Repetitive Loop

Long-running agents have boring but consequential jobs: keep useful context while a task spans multiple windows, decide which tool definitions to load, execute compatible calls, collect results, and continue after a partial result. Those jobs are easy to underestimate because an early prototype can just append messages to an array. They get harder when the task runs for hours, tool schemas change, and a large transcript starts hiding the instruction that mattered.

The API's automatic context compaction, tool search, programmatic tool calling, and multi-agent support are attempts to make that runtime behavior consistent. That is valuable. It means a product team can spend more time defining the work than maintaining another private orchestration framework.

The Application Still Owns the Consequences

An agent that reads a repository and suggests a patch is different from an agent that merges the patch, deploys it, and sends a customer email. The surface may look like one assistant conversation. The authorization should not.

Keep side effects behind tools whose permissions are narrower than the model's task description. A deployment tool should not silently have production database access. A customer-data tool should not double as a shell. The runtime coordinates; your application decides which gates exist.

Start With a Task Contract

The most common agent bug is not a hallucination. It is an underspecified job. "Fix the checkout failures" contains a possible repository edit, an unclear definition of success, a likely dependency on test infrastructure, and perhaps a production deployment. Nobody should have to infer all of that from a chat turn.

Make Done Observable

Convert the request into a contract before tools are available. Name the repository or records in scope, the allowed operations, the tests to run, the budget, and the event that requires human approval. The model may help propose the plan, but the surrounding service should store the decision.

type TaskContract = {
  objective: string;
  allowedTools: ("repo.read" | "repo.patch" | "ci.run")[];
  forbiddenEffects: ("merge" | "deploy" | "secrets.read")[];
  verification: string[];
  maxToolCalls: number;
  approvalRequiredFor: string[];
};

The exact shape does not matter. Separating intent from authority does. If an instruction asks for a write action that is not in the contract, the tool call should fail before the model is asked to justify it eloquently.

Preserve Checkpoints, Not Just Chat History

Durable sessions solve the mechanics of continuing work. They should not become the only place your system remembers the task. Persist checkpoints outside the conversation: the approved plan, files inspected, evidence gathered, proposed change, test output, and approval decision.

That is useful even when the model is correct. A retried job can resume from validated evidence rather than replaying an old conversation and guessing whether a command already ran. It is also useful when the model is wrong, because a reviewer can see where the task changed direction.

Pick the Environment as an Operations Decision

OpenAI supports hosted sandboxes and integrations with external environment providers. The hosted sandbox can run code, work with files, and produce artifacts. It is an attractive default for work that needs an isolated workspace without a custom VM lifecycle.

A Sandbox Is a Boundary, Not a Blank Cheque

Isolation does not make every operation harmless. A sandbox with a broad cloud credential can still cause a broad cloud incident. Decide which packages can be installed, whether outbound network access is required, what data may be mounted, how secrets are scoped, and when the workspace expires.

Use per-task credentials where possible. A code-review task may need a read-only repository token and a disposable checkout. It has no reason to receive the credential that can edit organization settings. If a task needs a privileged action, offer a separate tool that presents the proposed effect and requests approval.

Treat Files as Evidence With a Lifecycle

Artifacts are one of the useful features of a real agent environment: reports, patches, generated assets, and test output can outlive a model response. Give them clear ownership and retention rules. A private incident report should not be copied into a general workspace because it was convenient for the next subagent.

The question is not merely where files are stored. It is who can retrieve them, which task produced them, and how a reviewer knows they are the files that were actually verified.

Tools Need Product-Level Interfaces

The Agents API supports MCP, custom functions, and built-in tools. That makes tool availability flexible. It also makes tool design the center of agent safety.

Give Tools Small Verbs

Avoid a run_anything tool. Prefer operations whose inputs, outputs, and effects are narrow enough to test: read_pull_request, create_patch, run_named_test, open_change_request. The model gets a simpler choice set and the organization gets a smaller blast radius.

const createChangeRequest = {
  name: "create_change_request",
  description: "Create a reviewable change request. It cannot merge or deploy.",
  input_schema: {
    type: "object",
    properties: { branch: { type: "string" }, summary: { type: "string" } },
    required: ["branch", "summary"],
  },
};

Small tools are not a bureaucratic flourish. They make it possible to answer a basic post-incident question: what exactly was the agent allowed to do?

MCP Is a Supply-Chain Boundary

Remote MCP servers can expose powerful capabilities with an approachable interface. Treat them like any other dependency that can read data or act on the outside world. Allowlist servers, pin transport details where possible, isolate credentials, validate inputs and outputs, and record the server identity in the trace.

An agent does not need to be malicious for a tool integration to be dangerous. A confused server response, an ambiguous command, or a changed schema is enough. Capability discovery should never be capability inheritance.

Long Context Is Not State Management

The API's context compaction is designed to preserve important information across long sessions. That is an important runtime feature. It is not a substitute for a domain model.

Separate Facts, Plans, and Preferences

Store factual evidence with provenance. Store a plan as a versioned object. Store a user preference as a preference with scope and expiry. Do not flatten all three into prose and hope the model rediscovers the difference on turn 147.

For example, a verified test failure is evidence. "Do not touch payment capture" is a task constraint. "Prefer TypeScript examples" is a presentation preference. They deserve different storage, review, and retention rules.

Compact With an Audit Trail

When a long task is summarized, preserve a link to the evidence that supports the summary. A compacted statement like "tests passed" should identify the command, environment, exit code, and artifact. That is what makes a compact context useful to the next agent and defensible to the human who has to approve the result.

Subagents Are for Parallelism, Not Plausible Deniability

OpenAI's multi-agent support lets a primary agent delegate independent pieces of work to focused subagents. This is a good fit for tasks such as checking separate services, comparing competing implementation options, or collecting evidence from distinct source sets.

Partition by Evidence and Authority

Give each subagent a bounded question and only the tools it needs. One subagent can inspect tests; another can inspect deployment logs. Neither needs merge permission. The primary agent combines evidence and produces a proposal.

The primary agent should not merely summarize votes. It should resolve conflicts, cite the evidence, and state uncertainty. More agents do not convert an uncertain premise into a fact. They can, however, find independent evidence quickly when the work genuinely separates.

Avoid Fan-Out as a Default

Parallel work consumes money, creates more context to reconcile, and can multiply calls to sensitive systems. Start with a small concurrency limit and an evaluation that proves it helps the task. The most satisfying architecture diagram is not always the least wasteful one.

Budgets Must Map to Work

The API charges for the models and tools an agent uses. That makes task-level budgets part of application behavior, not an accounting afterthought.

Limit More Than Tokens

Set ceilings for model tokens, tool calls, elapsed time, sandbox runtime, external API spend, and concurrent jobs. A token limit does not stop an agent from retrying a flaky build or opening several expensive browser sessions. A task budget gives it a graceful exit: summarize what is known, preserve the evidence, and ask for a decision.

Attribute Every Request

Link model and tool activity to a task ID, project, user or service identity, policy version, model configuration, and environment. A chart showing rising token spend is a start. A trace showing that a new prompt version doubled build retries is something an engineer can fix.

Build an Agent Trace, Not a Model Log

The agent has crossed boundaries by the time it reaches a final answer. A useful trace connects them.

request -> task contract -> policy decision -> session
        -> model configuration -> tool proposal -> approval
        -> tool result -> verification artifact -> final effect

Keep Proof With the Claim

If an agent says it fixed a bug, the response should point to the diff and the relevant test output. If it says a record was updated, the audit record should identify the exact operation. This is better than asking a model to sound more certain. Confidence is not evidence.

Log Versions That Change Behavior

Record the prompt, model, reasoning setting, tool schema, MCP server identity, environment image, and policy version. A small change to any of them can alter behavior. Without version data, a production regression becomes a folklore project.

Evaluate the Whole Workflow

An agent evaluation should include the model's answer, but it should not end there. Create representative tasks that test tools, permissions, approvals, retries, evidence collection, and refusal behavior.

Test the Bad Paths on Purpose

Ask whether the agent attempts an unapproved deploy, mishandles a tool timeout, treats untrusted text as a command, or claims success when verification failed. The best time to find an authority bug is before the task has a real customer attached to it.

Ship Narrowly, Then Expand

Start with an observable task that has a bounded environment and a clear human approval point. Learn where the interface is ambiguous. Tighten the tool boundary. Only then expand scope. A managed harness makes this iteration faster. It does not make the iteration optional.

The Useful Division of Labour

OpenAI is offering to operate the machinery that keeps an agent session moving: context, tools, parallel work, and environments. That is a meaningful shift for teams that have spent too much time rebuilding it.

The part that remains is the interesting engineering: define the job, constrain authority, preserve evidence, budget the work, and make a human decision legible when it matters. If those pieces are weak, a better harness simply runs the weak design more reliably. If they are strong, the Agents API gives the team more time to improve the thing only it can build.

---