OpenAI Agents: An Artifact Contract for Delivery and Validation

The delivery of an agent is not just a few files. An artifact contract imposes a structure, evidence, and a review status so that a human or a service can utilize it. Supported by OpenAI's Agents API, this framework proposes five concrete components, from the output surface to the transfer rules.

A Practical Implementation with Manifest, Unique Run, and Dedicated Directories

A practical organization involves grouping each agent execution under a dedicated output directory, such as /workspace/outputs/run-<id>, clearly separating the manifest, deliverables, evidence, and checks. A unique run identifier prevents overlaps between parallel tasks. The manifest should remain explicit and factual, with the narrative reserved for the README. An example of manifest.json includes contract_version, run_id, task_type, status, summary_path, the list of deliverables, checks, open_questions, and a review block. In this example, the status is needs_review, and a review is required with a designated owner (sre-on-call). The manifest does not include an unlimited notes field or promises of unapproved actions. This organization aligns with the use of /workspace/outputs mentioned for results, evidence, and recommended mitigations.

Why Raw Outputs Fail at Transfer

An agent that declares itself finished does not necessarily deliver a usable item. In practice, locating the actual work proves difficult in temporary spaces or confusing trees, and this gap becomes costly as workflows become asynchronous or involve handoffs. Without evidence, a manager cannot approve a mitigation, and a service cannot ingest a report whose name varies with each execution. A second agent cannot interpret an empty folder. Common pitfalls include: useful deliverables drowned in temporary artifacts, declared checks without command or status, confusion between observation, hypothesis, and change, cross-over of outputs by generic names, valid but incomplete JSON, secrets or raw data mistakenly output from the sandbox. Artifact metadata, limited to technical information, does not indicate task adequacy or supporting sources.

Five Components to Frame a Usable Delivery

The artifact contract is structured into five parts. First, declare the delivery surface: output directory, required files, and artifact types, explicitly integrating the write location within the task. The expectation is not a simple report, but a human-readable report, a machine-readable manifest with status and inventory, and the supporting files named in the output space. Next, assign a role to each file: README.md as the human entry point, manifest.json as the machine entry point with status and inventory, evidence/ for pieces, deliverables/ for the requested work, and checks/ for tests and logs. This separation avoids interpreting a terminal transcript as a conclusion. More broadly, a transfer is a small verifiable package that clarifies existence, relevance, and remaining decisions. The contract makes these expectations explicit before execution, resembles an API contract while integrating human review and operational proof, and acknowledges that a JSON schema alone does not guarantee correctness, timeliness, or safe usage.

Require Evidence Linked to Claims

Every claim must be supported by evidence. For code, this includes a test result and a diff; for an incident investigation, timestamped log queries, snapshots of metrics, and a list of open questions; for data, the input version, transformation script, line counts, and validations. Trust, while relevant, does not replace evidence. The agent must report its uncertainties and inventory missing evidence. This framework transforms an agent execution into a review journey rather than an opaque accumulation of outputs.

Validate the Package and Distinguish Execution from Approval

Validation must be as deterministic as possible: presence of required files, correct analysis of the manifest, existence of referenced files, confinement of paths within the output space, and adherence to a size limit. If the task includes a test, the designated command must complete without error. In cases where human intervention is required, the package should carry the status needs_review rather than complete. It is important not to equate the agent's completion of the mission with the organization's validation.

Transfer, Retention, and Integration Rules in the Prompt

The contract concludes with transfer and retention rules, specifying an owner and a next action, such as SRE review before restart, CI signing off in a pull request, or publication decision by a research lead. It indicates the duration of package availability, items to purge, and reminds that immutability does not replace access control. Identifiers, raw client data, screenshots, and logs must be handled with care. To avoid inconsistent artifacts, these requirements should be included in the task prompt: strict location of outputs (e.g., /workspace/outputs/run-8f3c), required files, separation between observations, hypotheses, and recommendations, prohibition of unapproved external actions, and self-checks before closure. This approach allows the agent to be useful without claiming authority, while providing humans visibility on remaining decisions and systems with reliable and repeatable collection. It relies on OpenAI's Agents API and its environments capable of executing code, managing files, and exposing immutable session artifacts, while remaining independent of beta-phase API names.