Field guide / 9 min
Make Responses the system boundary
Design around typed items, state choices, and observable output.
The Responses API is the recommended starting point for new OpenAI integrations. Treat it as an application boundary—not a thin text-generation wrapper—so messages, tool calls, tool results, and future input types remain explicit.
Working principles
Items over strings
Preserve typed input and output items. A message, function call, and function result are different events with different ownership.
Choose state deliberately
Decide whether your server stores conversation history, chains a previous response, or uses a persistent conversation. Make retention and deletion visible.
Normalize at your edge
Expose a stable application response type to the rest of your code instead of leaking every provider response field through the product.
Field procedure
- 01
Write the product contract
List the input modalities, expected output, allowed side effects, latency budget, and evidence the caller needs.
- 02
Map input to typed items
Convert user text, system instructions, files, and prior context into an explicit input sequence.
- 03
Choose the state path
Document whether each request is stateless, response-chained, or conversation-backed. Add a deletion path before production.
- 04
Parse the output ledger
Handle message items, tool calls, tool results, and refusals as separate branches. Never assume the first item is final text.
- 05
Record acceptance evidence
Capture request IDs, timing, tool outcomes, validation results, and the application decision without logging sensitive content by default.
PASS / FAIL
Acceptance checklist
- Typed request adapter exists.
- State and retention policy is documented.
- Every output item type has an explicit branch.
- Tests cover empty, refused, tool-using, and malformed outcomes.
WATCH / REJECT
Failure patterns
- Passing raw provider objects across the whole codebase.
- Treating stored response state as your product database.
- Reading only convenience text and losing tool or refusal events.