Agent definitions and instructions

Purpose and Scope

An agent definition is the reusable description of how a model should behave in a workflow. In the OpenAI platform docs, an agent packages a model, instructions, and optional runtime behavior such as tools, handoffs, MCP servers, and structured outputs. In this SDK page, the practical mapping is the Responses request shape: the caller chooses a model, supplies instructions or prompt-like context, provides input, and can attach tool or output-format configuration. The repository evidence shows the Responses namespace as a first-class resource export and tests the same fields that make an agent run reproducible.

Sources: src/resources/responses/index.ts, tests/api-resources/responses/responses.test.ts

This page is for developers who are turning agent design decisions into SDK calls. It focuses on the definition layer rather than orchestration: the stable choices that should travel with a specialist agent, such as the model family, the instruction text, the allowed tools, and output parsing expectations. Runtime concerns such as streaming, retries, or multi-turn state are related topics, but the starting point is a typed request object that gives the model a role, a task, and the capabilities it may use.

Sources: tests/api-resources/responses/responses.test.ts, tests/lib/ResponsesParser.test.ts

Core Primitives

The most important primitive is the Responses resource. The generated index for the resource family exports Responses, InputItems, InputTokens, and WebSocket option types, which signals that response creation, response replay input, token counting, and realtime-style connection options are grouped under the same API area. For agent definitions, this matters because the definition is not only a prompt string. It can include the model choice, instructions, input items, tool lists, tool choice behavior, structured text format, and parameters that influence how the response can be continued or compacted later.

Sources: src/resources/responses/index.ts

Instructions are the durable behavioral contract for a specialist. The README example uses a coding assistant instruction, while the source tests demonstrate instructions as a request field in responses.compact. Treat this field as the place for role, constraints, style, and domain rules that should apply regardless of the current user input. The input field should carry the current task or conversation content. Keeping those concepts separate makes the agent easier to review, update, and test, especially when the same specialist handles many user requests or is embedded inside a larger workflow.

Sources: tests/api-resources/responses/responses.test.ts

Model configuration is the second durable part of the definition. The API resource tests call client.responses.compact with model: 'gpt-5.4', while the parser tests use a Responses create parameter object with model: 'gpt-5.4-mini'. Those examples show the SDK contract at the request-object level: a model identifier belongs beside input and output-format configuration. In agent terms, pick the model for the specialist’s expected reasoning, latency, cost, and modality needs, then keep that choice close to its instructions so future maintainers can understand why the agent behaves as it does.

Sources: tests/api-resources/responses/responses.test.ts, tests/lib/ResponsesParser.test.ts

Relevant Source Files

• api.md - Generated API reference for the SDK; use it as the broad method and type reference when expanding from the conceptual guidance on this page.
• src/resources/responses/index.ts - Exports the Responses resource family, input item helpers, token-counting resource, and WebSocket option types that form the SDK namespace around response-based agent runs.
• tests/api-resources/responses/responses.test.ts - Exercises concrete Responses methods and request fields, including create, retrieve, delete, cancel, compact, instructions, previous_response_id, cache options, and service tier.
• tests/lib/ResponsesParser.test.ts - Shows how typed Responses create parameters combine model, input, structured text format, tools metadata, and parsed output behavior.

System-to-Code Mapping

Agent definition concept	SDK surface shown by the repository	Why it matters
Model choice	model in Responses request parameters	Selects the model that will execute the specialist behavior.
Instructions	instructions in Responses request parameters	Carries role, constraints, and style separate from the user task.
Current task or state	input, response output items, and continuation identifiers	Supplies user work and replayable context for a run.
Tools	tools, tool_choice, and parallel_tool_calls on response objects	Describes callable capabilities and how the model may invoke them.
Structured outputs	text.format with JSON schema and parsed response fields	Makes downstream workflow steps consume typed output instead of free text.
Lifecycle methods	create, retrieve, delete, cancel, and compact	Lets a workflow start, inspect, terminate, and summarize response state.

The test fixtures make the mapping concrete. A synthetic response object in the parser tests contains instructions, model, output, output_text, parallel_tool_calls, temperature, tool_choice, tools, top_p, and status. Even though many values are null or empty in the fixture, the shape is important: the response echoes the configuration and runtime state needed by an agent workflow. The completed case produces parsed structured data, while the incomplete case preserves incomplete details and leaves parsed output empty, which is safer for callers that need to inspect failure or truncation state.

Sources: tests/lib/ResponsesParser.test.ts

Execution Flow

A typical definition-to-run flow begins by writing the agent’s instructions in natural language, selecting the model, and deciding whether the current input is a plain string or a list of richer input items. The caller then invokes the Responses resource, usually through client.responses.create, and awaits the SDK promise. The resource tests demonstrate that SDK promises can be consumed as parsed data, as the raw Fetch Response, or as a combined data-and-response pair. That is useful for agent platforms that need both the model result and request metadata for tracing, debugging, or observability.

Sources: tests/api-resources/responses/responses.test.ts

After the first response, workflow designers choose how state should continue. The compact test shows previous_response_id, prompt_cache_key, prompt_cache_retention, and service_tier traveling with a model and instructions. In agent-definition terms, these are not the personality of the agent, but they are configuration choices that affect how a deployed workflow manages history, cache behavior, and service handling. Keep them near the code that starts or resumes a run, and document whether your workflow relies on previous response state or reconstructs input explicitly.

Sources: tests/api-resources/responses/responses.test.ts

Structured output adds another execution branch. The parser tests build a Responses create parameter object with a JSON schema text format, then parse a completed response into an output_parsed object. When the response is incomplete because the maximum output token limit is hit, parsing is intentionally not forced; the response status and incomplete details remain inspectable, and the message content records a null parsed value. Agent workflows should follow that pattern: validate parsed results only after completion, and route incomplete results to recovery, retry, summarization, or user-facing clarification.

Sources: tests/lib/ResponsesParser.test.ts

API Components

Use the following compact reference as the checklist for implementing a response-backed agent definition in this SDK. The fields shown here are grounded in the request and response shapes exercised by the repository tests, not a separate hand-written agent class. The generated API reference remains the canonical place to inspect every overload and type, but these names are the practical minimum for connecting agent-design language to code.

Sources: api.md, tests/api-resources/responses/responses.test.ts, tests/lib/ResponsesParser.test.ts

• client.responses.create(params) starts a response run from a typed request object.
• client.responses.retrieve(responseID, params?, options?) reads an existing response and accepts include and streaming-related query parameters in the tested call shape.
• client.responses.delete(responseID) removes a response object when the API supports deletion for that resource.
• client.responses.cancel(responseID) cancels a response that is still in progress.
• client.responses.compact(params) creates a compacted representation using fields such as model, input, instructions, previous_response_id, cache configuration, and service tier.
• Response objects expose output_text for convenient text access and preserve richer output items for workflows that need message, reasoning, tool, or parsed-output details.
• Structured-output requests can use text.format with a JSON schema; completed responses may expose parsed data, while incomplete responses keep parsing null so status details remain available.

Testing Signals and Edge Cases

The tests highlight a few edge cases that agent builders should intentionally handle. First, a response promise is not just plain JSON; it can expose raw and combined response accessors, so instrumentation code should avoid accidentally consuming the wrong layer. Second, retrieval supports request options, and the test deliberately passes an invalid path to assert error behavior. Third, response objects can be incomplete, and parser behavior is conservative in that state. Finally, tool-related properties may exist even when no tools are configured, so code should read the response shape defensively rather than assuming every agent has callable capabilities.

Sources: tests/api-resources/responses/responses.test.ts, tests/lib/ResponsesParser.test.ts

Next Steps

When you implement a new specialist, start with a small definition: one model, clear instructions, and one representative input. Add tools only after the base behavior is understandable, then add structured output if another service or workflow node needs a predictable data contract. For multi-turn work, read the conversation-state guidance next so you preserve replayable output items correctly. For tool execution, continue to the tools and approvals page. For evented output, continue to streaming and events before building user interfaces around partial responses.