Agents SDK workflows

Purpose and Scope

This page explains how agent-oriented workflows relate to the openai TypeScript and JavaScript SDK. The official Agents documentation describes agents as applications that plan, call tools, collaborate across specialists, and keep enough state to complete multi-step work. In this repository, the requested source evidence is narrower: it shows the generated Admin API resource that retrieves and updates project-level hosted tool permissions. That resource is still important for agent systems because hosted tools such as Code Interpreter, file search, image generation, MCP, and web search are capabilities an organization may need to enable, disable, or audit before application code relies on them.

Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts

The practical boundary is that openai-node is the OpenAI API SDK, not the separate code-first Agents SDK repository referenced by the platform documentation. Use this SDK when your agent application needs typed access to OpenAI API resources, including model calls, tool-enabled workflows, evaluation APIs, and administrative controls. Use the Agents SDK documentation when your application owns orchestration concerns such as the run loop, handoffs, tool execution, approvals, and state. The source-backed surface on this page is the governance layer for hosted tools, which is commonly part of preparing agent deployments for production.

Relevant Source Files

• src/resources/admin/organization/projects/hosted-tool-permissions.ts — Defines the generated HostedToolPermissions API resource, its retrieve and update methods, the returned ProjectHostedToolPermissions shape, and update parameter types for hosted tool enablement.
• tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts — Verifies the generated client path client.admin.organization.projects.hostedToolPermissions, including raw response access, parsed response access, and combined data/response access for both retrieval and update calls.

Core Primitives

An agent workflow usually combines a model interaction surface, instructions, tools, state, and observability. Instructions tell the model what role or policy to follow. Tools expose actions the model may request, such as searching files, calling an MCP server, generating an image, or using a hosted execution environment. State lets a later turn continue from earlier model outputs or from a managed conversation. Evaluation closes the loop by checking whether a workflow selected the right tool, followed instructions, or handled handoffs correctly. The hosted tool permissions resource sits underneath those higher-level primitives by controlling whether specific hosted tools are enabled for a project.

Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts

The permission model in the generated type is explicit rather than free-form. ProjectHostedToolPermissions contains one permission state for each supported hosted tool in this source: code_interpreter, file_search, image_generation, mcp, and web_search. Each tool-specific object has an enabled boolean. That means application code can inspect the project configuration before starting an agent workflow, and administrative automation can update only the capabilities it intends to change. MCP deserves special attention because it represents external tool/server integration, whereas hosted tools such as file search or Code Interpreter are OpenAI-managed capabilities exposed through API workflows.

System-to-Code Mapping

The generated resource is mounted under the administrative organization project namespace: client.admin.organization.projects.hostedToolPermissions. Calling retrieve(projectID, options?) performs a GET request to the project hosted-tool-permissions endpoint and returns an APIPromise<ProjectHostedToolPermissions>. Calling update(projectID, body, options?) performs a POST to the same project-scoped endpoint with a HostedToolPermissionUpdateParams body. Both methods attach admin API key security, so they are intended for administrative configuration rather than ordinary end-user model turns.

Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts, tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts

This mapping is useful when designing deployment checks around agents. A setup script can retrieve permissions for a project, verify that the workflow’s required tools are enabled, and fail early if a capability is unavailable. A controlled rollout can update only web_search, file_search, mcp, or another named permission while leaving other tool states unchanged. Because the update parameter properties are optional and nullable, callers should treat the body as a patch-like administrative request: include the permissions they mean to alter and avoid constructing broad updates accidentally.

Execution Flow

A typical production flow starts outside the model run. First, an administrator or deployment job constructs an OpenAI client with both a regular API key and an admin API key, as shown by the test setup. Next, the job retrieves hosted tool permissions for the target project. If the agent workflow depends on file search, Code Interpreter, web search, image generation, or MCP, it compares the returned enabled flags with the workflow requirements. Only after the project passes that check should the application start runs that ask the model to use those capabilities.

Sources: tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts

The generated tests also demonstrate the promise ergonomics that apply to this resource. A call returns a response promise that can be awaited for parsed data, converted to a raw Response with asResponse(), or resolved with both parsed data and raw response metadata through withResponse(). Those forms matter for operational agents because administrative automation often needs response headers, status details, or logging context in addition to the typed permission object. The tests validate this behavior for both retrieve and update, giving maintainers a signal that the generated resource follows the SDK’s standard API-resource contract.

API Components

Component	Contract	Notes
HostedToolPermissions.retrieve(projectID, options?)	Returns APIPromise<ProjectHostedToolPermissions>	Reads project hosted tool permissions using admin API key security.
HostedToolPermissions.update(projectID, body, options?)	Returns APIPromise<ProjectHostedToolPermissions>	Updates project hosted tool permissions using a typed request body.
ProjectHostedToolPermissions	Contains code_interpreter, file_search, image_generation, mcp, and web_search	Each permission state exposes an enabled: boolean field.
HostedToolPermissionUpdateParams	Optional per-tool update fields	Lets callers submit targeted changes for individual hosted tools.

The API surface is intentionally compact because it represents configuration, not agent execution. Agent runs still need the appropriate model, instructions, input, state strategy, tool definitions, and evaluation loop. This resource answers a different question: whether the project is permitted to use specific OpenAI-hosted capabilities at all. Treat it as part of environment readiness, alongside API-key management, project selection, observability setup, and evaluation planning. If a workflow spans local tools, MCP connections, and hosted tools, keep these categories separate in documentation and checks so failures are easy to diagnose.

Testing Signals and Next Steps

The test file confirms that the generated namespace, method names, and promise helpers are usable from the public OpenAI client. It constructs a client with apiKey, adminAPIKey, and baseURL, then exercises both operations against the test API base. For readers building agent systems, the immediate next step is to pair this administrative check with the workflow surface you actually run: Responses for model-plus-tool calls, evals for repeatable assessment, and the official Agents SDK guides for orchestration patterns such as tool execution, approvals, handoffs, sessions, and tracing.

Sources: tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts