Connections

Purpose and Scope

Connections are the way an agent-style or response-driven workflow reaches beyond the model request itself. In this SDK, the clearest source-backed anchor for those workflows is the generated Responses surface: it is exported as a top-level resource namespace, and its tests exercise creation, retrieval, cancellation, compaction, response metadata access, and include options for tool-related results. The repository evidence does not show a standalone Connections resource class, so this page documents the practical connection pattern: configure the OpenAI client, call Responses, and request or preserve the external-service artifacts that a connected workflow needs. Sources: src/resources/responses/index.ts, tests/api-resources/responses/responses.test.ts

A useful mental model is that a connection is not just an HTTP base URL or an API key. It is the contract between a model workflow and an integration surface such as a hosted tool, a file-search result set, an MCP-style server, an OpenAPI-backed action, or another external capability surfaced through the platform. The SDK participates by giving TypeScript and JavaScript applications typed request methods, response objects, raw response access, and request options. The platform documentation supplies the higher-level agent vocabulary, while this repository shows how a code-first application reaches those surfaces through generated client resources. Sources: api.md, src/resources/responses/index.ts

Core Primitives

The core SDK primitive is the OpenAI client instance. The Responses resource is reachable from that client and is exported from the generated responses index alongside input item and input token helper resources. That export layout matters because connected workflows usually combine several concerns: sending a model request, counting or replaying input, reading response output items, and optionally reconnecting to streaming or WebSocket-oriented flows. The index file shows that the Responses namespace is part of the generated public surface rather than an example-only helper, so application code should treat it as the stable entrypoint for response-centered integrations. Sources: src/resources/responses/index.ts

The second primitive is the response promise wrapper returned by generated SDK calls. The tests show three access modes for a Responses call: awaiting the promise for parsed data, calling the wrapper for the raw Fetch API response, or requesting both data and transport response together. That distinction is especially important for connected workflows because integration debugging often requires headers, request identifiers, or raw status details in addition to model output. When a workflow calls an external tool or returns connected results, keeping access to both parsed data and transport metadata gives operators a better path for tracing and troubleshooting. Sources: tests/api-resources/responses/responses.test.ts

The third primitive is request-level configuration. The retrieval test passes include-style parameters and an explicit request option object, proving that callers can combine endpoint parameters with per-call transport overrides. The visible example requests file-search call results through an include value, which is a concrete sign that connected tool artifacts may be opt-in rather than always expanded. For connection-heavy agents, that means application code should ask for the details it plans to inspect, store, display, or evaluate, rather than assuming the default response payload contains every external-service result. Sources: tests/api-resources/responses/responses.test.ts

System-to-Code Mapping

Concept	SDK surface	What the source evidence shows
Response-centered workflow	client.responses	The generated index exports Responses as a public resource namespace.
Input and replay support	InputItems, InputTokens	The same index exports input item listing and input token counting resources beside Responses.
Connected result expansion	retrieve parameters such as include	The response retrieval test requests file_search_call.results.
Transport inspection	.asResponse() and .withResponse()	Tests verify raw Response access and combined data-plus-response access.
Conversation compaction	client.responses.compact()	Tests cover required and optional compaction parameters, including prior response linkage.

This mapping is intentionally narrow. The page is not claiming that every external integration has a dedicated class named connection in this package. Instead, it maps the first-party connection idea to the concrete places where a JavaScript application interacts with connected model work: the generated Responses namespace, request parameters, expanded result fields, and response wrappers. That framing helps avoid a common mistake in agent code: treating integration results as opaque text only. If a downstream step needs tool outputs, file-search citations, or traceable call information, the application should model those artifacts explicitly and request the appropriate expanded data. Sources: api.md, tests/api-resources/responses/responses.test.ts

Execution Flow

A typical connected workflow starts by constructing an OpenAI client with the credentials and endpoint appropriate for the deployment. The Responses test client is configured with an API key, an admin API key, and a base URL, which demonstrates that resource calls are made through a shared client configuration rather than per-resource constructors. In production code, that same structure is where teams choose their platform endpoint, provider integration, custom fetch behavior, or organization-level settings. Once the client exists, the workflow calls the Responses resource and treats the returned object as the authoritative record for model output and connected activity. Sources: tests/api-resources/responses/responses.test.ts

The next step is to decide how much detail the workflow needs back. For a simple user-facing answer, parsed response data and the output text may be enough; the create and retrieve tests assert that parsed responses expose an output text property. For an agent or integration flow, the caller often needs richer data. The retrieval test shows include parameters for file-search call results, along with pagination-like and streaming-related fields. That pattern is the SDK-level hook for bringing connected artifacts into the application layer where they can be logged, evaluated, shown to users, or passed into another step. Sources: tests/api-resources/responses/responses.test.ts

Finally, long-running or multi-step workflows need state management. The compact tests show a response compaction method with a required model, optional input, instructions, previous response identifier, prompt cache fields, and service tier. That set of options is useful for connection-heavy workflows because external interactions can produce large histories. Compaction gives the application a generated operation for reducing or carrying forward context while preserving the model and instruction choices needed for the next step. Treat this as part of the connection lifecycle: after external calls happen, prepare the conversation state for reliable continuation. Sources: tests/api-resources/responses/responses.test.ts

Compact API Reference

• Responses is exported from src/resources/responses/index.ts as the generated Responses resource namespace.
• InputItems and InputTokens are exported beside Responses, indicating related support for response input inspection and token counting.
• ResponsesWSClientOptions, ResponsesWSReconnectOptions are exported types for WebSocket-oriented Responses behavior.
• client.responses.create(params) returns a generated promise wrapper that can be awaited for parsed data or inspected as a raw response.
• client.responses.retrieve(responseID, params?, options?) accepts endpoint parameters such as include, include_obfuscation, starting_after, and stream in the tested call.
• client.responses.delete(responseID) and client.responses.cancel(responseID) are covered by generated resource tests.
• client.responses.compact(params) is tested with model, input, instructions, previous_response_id, prompt_cache_key, prompt_cache_retention, and service_tier.

Use these names as the SDK-level reference points when wiring external services into an agent workflow. For example, a file-search integration should not only create a response; it should also decide whether retrieval needs expanded file-search call results. A UI that displays integration provenance should preserve raw response metadata when useful. A backend that chains multiple connected steps should consider compaction or previous-response linkage instead of manually discarding structured output items. The API shape encourages applications to separate three concerns: make the model call, request the connected artifacts needed by the next component, and keep enough state to continue safely. Sources: src/resources/responses/index.ts, tests/api-resources/responses/responses.test.ts

Testing Signals

The generated response tests are strong signals for expected SDK behavior around connected workflows. They do not mock a separate connection manager; instead, they verify the resource methods and wrapper semantics that application code relies on. Each core method checks that raw response access returns a Fetch API response object, while awaiting the call returns parsed SDK data. The retrieval test intentionally passes an invalid path through request options and expects a not-found error, which confirms that request options are forwarded. For integration code, that means per-call overrides and error handling should be tested as part of the connection path, not only the happy-path model output. Sources: tests/api-resources/responses/responses.test.ts

Relevant Source Files

• api.md — Generated API reference for the package; use it to confirm the full request and response type surface for Responses and related integration parameters.
• src/resources/responses/index.ts — Public export point for Responses, input items, input token counting, and Responses WebSocket option types.
• tests/api-resources/responses/responses.test.ts — Generated resource tests showing client construction, response creation, retrieval include parameters, deletion, cancellation, compaction, and raw response helpers.

Next Steps

Read this page together with the Responses API concepts page when designing a model-centered workflow, then move to MCP integrations or OpenAPI and GPT Actions when the external capability is provided by a server or an action schema. For observability and quality work, pair connected workflows with evaluation guidance so tool choice, handoffs, and integration outputs can be inspected in traces. If you are implementing the workflow in this SDK, start from the Responses resource, add only the include parameters your application needs, preserve raw response metadata where it helps operations, and keep conversation state explicit before adding more external services.