OpenAI Developers

View saved version →

---
name: agents
description: Build agent apps with the Agents API or Agents SDK. Use when adding tools, sessions, sandboxes, handoffs, guardrails, evals, or deployment.
---

# Agents

## Entry points and runtime

Answer explanations without setup or edits. For existing apps, keep their conventions.

- Use the **Agents API with `environment={"type": "openai_hosted"}` by default**. OpenAI runs the agent, manages its sandbox, and stores session state. A background task or application-hosted function does not require the Agents SDK.
- Use the **Agents SDK** when requested, already used by the app, or needed for a caller-owned agent loop, SDK handoffs, or guardrails. Follow [the SDK workflow](references/agents-sdk.md) after credential setup.
- Agents API sandboxes run `codex exec-server`. Neither path provides a caller-hosted `codex app-server`.

For agent-powered websites, also follow frontend guidance. Other websites and simple AI apps do not need this skill.

## Agents API lifecycle

Use the public [Agents API docs][agents-api-docs] and [quickstart][agents-api-quickstart] for the current contract. Append `.md` or request `Accept: text/markdown` for readable source. If docs are unavailable, report the blocker before implementing the API path; do not substitute private repositories or invent methods.

Use `client.beta.agents` in the public [OpenAI Python SDK][python-sdk] (`openai>=3.13.0`) or [TypeScript SDK][typescript-sdk] (`openai>=7.15.0`). These are package versions, not language requirements. The SDKs add `OpenAI-Beta: agents=v1` automatically and expose typed `agent.session.*` events and `session.environment.id`. Include the header explicitly only for raw HTTP requests. Check installed versions before adapting examples; do not mix preview client methods with the released SDK.

### 1. Prepare the project and access

Work in the current directory and reuse the project's environment. Follow this plugin's `openai-platform-api-key` skill before implementation or execution; it owns credential choices and setup. A configured key or installed plugin does not establish Agents API access. Hosted session creation checks access and provisions the sandbox; for self-hosted setups, check access before starting provider compute.

### 2. Confirm the architecture

Use the request and existing app to choose:

| Decision | Choices and consequence |
| --- | --- |
| Interaction | Stream results or collect them later. Disconnecting the observer does not stop the turn. |
| Application tools | Keep function responders available even when the observer disconnects. |
| Environment | `openai_hosted` by default. Use `none` when the user wants no sandbox, or `self_hosted` for private networks, custom images, or the user's chosen compute. Preserve existing app settings. |

Ask only unanswered questions that affect the build. Use a user-input tool with up to three short questions and the recommended option first, labeled `(Recommended)`. Without that tool, use defaults unless blocked.

OpenAI-hosted sandboxes need no provider setup or executor key. Use this default without asking the user to choose a provider. Verify access and a real command or file operation; report access failures rather than silently switching environments. For `self_hosted`, preserve the user's provider choice or offer local/cloud options from the docs, then follow [sandbox setup](references/sandbox-providers.md).

### 3. Start small

Start with one agent in one runnable Python file unless the user prefers another language or app surface. Keep the requested or existing model; otherwise use the current API quickstart's model and verify project access. Use [the worksheet](references/app-template.md) only for complex apps. Add servers, workers, or storage when the workload needs them, not just because a client may disconnect.

### 4. Implement the complete session flow

- Start with `client.beta.agents.sessions.create(..., input=..., stream=True)` in Python (`stream: true` in TypeScript). Include initial input for `none` and streaming `openai_hosted` creation. For an idle Python session, the `sessions.stream(session_id, input=...)` context manager subscribes before sending a follow-up and can run `tool_handlers`. For active sessions or independently managed workers, use `sessions.events.stream` and submit input separately through `sessions.events.create`.
- Pass top-level `agent_id` for a saved agent. Inline `agent` settings replace supplied fields for this session, not the saved agent.
- Handle required actions by type: function calls need an `agent.session.input.tool_result` submitted through `sessions.events.create(..., events=[...])`, with the pending action's `turn_id` and `call_id`. Await calls when using `AsyncOpenAI` or TypeScript. Self-hosted environment connection requests need an executor; OpenAI handles hosted provisioning and connection. `none` needs no executor.
- Check the intended turn's result, not just `idle`. Surface failed or cancelled turns. If text is missing, retrieve persisted items and turn status. Streams have no replay: reconnect before reconciling saved items.
- Save session and turn IDs. Check the outcome before retrying input. Use idempotency only where the API/SDK supports it, keeping the same key and payload for retries of one message.

For hosted files, use `environment.files` or the environment Files API for inputs. Write results to `/workspace/outputs`, then use `sessions.artifacts.list` and `sessions.artifacts.content` to download the artifact matching the completed turn and path. Workspaces are separate per session.

### 5. Verify and iterate

Test the app and, when authorized, run a bounded live check. Verify search sources and actual file contents, not just successful requests. Report failures and skipped checks; a completed turn does not prove every tool succeeded.

### 6. Deliver and account for resources

Provide the run command, outputs, and test results. Keep resources needed for follow-ups. When finished, download artifacts before deleting the session. Attempt self-hosted sandbox termination separately, even if session cleanup fails or setup only partly succeeded. Report remaining resource IDs without exposing secrets.

On deletion `409`, stop new input, cancel active work if needed, and retry after setup or execution settles. Limit retries; cancellation may not clear a connection wait. Hosted sandbox cleanup runs asynchronously after session deletion.

Use [the evals](references/evals.md) to check skill activation and interaction.

[agents-api-docs]: https://developers.openai.com/api/docs/guides/agents-api/overview
[agents-api-quickstart]: https://developers.openai.com/api/docs/guides/agents-api/quickstart
[python-sdk]: https://github.com/openai/openai-python
[typescript-sdk]: https://github.com/openai/openai-node

Referenced files: 5

View saved version →

---
name: devday-guide
description: Help with OpenAI DevDay attendance, onsite logistics, session schedules, personal plans, livestreams, recordings, and DevDay Exchanges. Use for DevDay-specific questions, not general OpenAI API or app development.
---

# DevDay Guide

Help the user attend, follow, or learn from DevDay. Public event questions do not require an API key, Platform account connection, or developer onboarding.

## Verify event information

- Start with [the official DevDay site](https://devday.openai.com/) for the program, attendance FAQ, livestream, recordings, and accessibility information. For regional events, use [DevDay Exchanges](https://events.openai.com/devdayexchange2026) and official links from the DevDay site.
- Match the requested year and city. If a landing page has rolled over to another event, find an official page for the requested edition rather than substituting the latest agenda.
- For onsite questions about September 29, 2026 in San Francisco, read [the bundled attendee guide](references/devday-2026-attendee-guide.md). It contains dated logistics from the event guide, not a live agenda. Use it for check-in, wayfinding, meals, activities, and attendee services; prefer newer official event communications and onsite signage when details change.
- Check current public sources for session schedules, speakers, ticket availability, livestreams, and recordings, and cite the relevant pages. If a detail is only in the bundled guide, attribute it to the September 27 attendee-guide snapshot rather than implying it was verified on the website. Say when a current detail cannot be verified; do not fill gaps from memory.
- Apart from the curated bundled attendee guide, use public, unauthenticated sources for event facts, not employee-only repositories, Slack, Drive, planning documents, or previews. Do not fetch the source planning document at runtime. User-provided registration details can inform their own answer, but are not public event information.
- Preserve the published date, time zone, and overlapping sessions. A programming window is not a list of individual talks, and a venue address does not establish a check-in entrance or room map.

## Shape the answer to the request

- For a specific question, answer directly with the official link. Do not open an agenda or propose a personal plan unless it helps with the request.
- For a schedule, use a compact table of verified times, sessions, and locations. Leave unpublished durations or locations unspecified.
- For a personal plan, use the user's interests and availability; ask a brief follow-up only if it would change the recommendation. Show conflicts and alternatives rather than silently assigning overlapping sessions. Recommendations do not reserve a seat or change registration.
- For onsite help, give the relevant location and service hours. Do not infer walking times, accessible routes, room positions, or access privileges beyond the guide; use onsite signage or event staff for details. LaunchPad recommendations do not book an appointment.
- For "what is on now," check the current date and event-local time. Only call a session ongoing when its published start and end support that claim; before the event, help plan, and after it, look for published recordings.
- For livestreams or recordings, follow official links and distinguish planned coverage from a video that is actually available. Do not invent a transcript or announcements from a session title.
- For building something inspired by a session, use the relevant public docs and available developer skills. Let the user's chosen project drive the handoff rather than forcing an API-key setup or a particular framework.

## Work with the existing DevDay sidebar

When the OpenAI Developers sidebar is available, direct users to its DevDay tab to browse sessions and use its save controls. Do not create a second agenda widget or call tools that are not available in the current session.

Saved selections live in the sidebar; this skill does not have a tool to read or change them. If the user wants advice based on their saved sessions, ask them to share the relevant selection. Do not claim a chat recommendation has been saved, synchronized across devices, or added to a calendar. Do not add a notebook or notes workflow.

If the user wants to share their schedule, direct them to the sidebar's explicit sharing controls when available. Explain that this creates a public schedule link; do not publish a schedule just because the user requested a personal plan.

Referenced files: 2

View saved version →

---
name: openai-api-troubleshooting
description: Use when an OpenAI API request fails and Codex needs to classify the likely cause, explain the next step, and route to the right follow-up. Covers common runtime failures such as blocked outbound network access, invalid credentials, exhausted API quota or credits, rate limits, and model, project, or organization access issues; delegate key provisioning to openai-platform-api-key and current documentation lookups to openai-docs.
---

# OpenAI API Troubleshooting

Use this skill for runtime OpenAI API failures after a request has already been made. Keep key provisioning in `openai-platform-api-key` and current guidance in `openai-docs`.

## Routing

1. **Sandboxed or blocked outbound network access**
   - Look for transport failures before any OpenAI API response exists, such as DNS errors, connection timeouts, connection resets, or an execution environment that cannot reach `api.openai.com`.
   - Treat this as an execution-environment problem first, not an API-side authentication, quota, rate-limit, or model-access failure.
   - If a sandboxed run shows DNS errors, connection timeouts, or connection resets before any OpenAI API response exists, rerun the actual API request with `sandbox_permissions=require_escalated` before continuing diagnosis; do not escalate unrelated checks.
   - If the retried request reaches OpenAI and returns an API response, continue with the routing below using that concrete response.

2. **Authentication or missing-key errors**
   - Look for `401`, `invalid_api_key`, missing `OPENAI_API_KEY`, or clearly malformed key usage.
   - Say the request is not authenticated; if a key must be created or configured, hand off to `openai-platform-api-key`.

3. **Quota or credit exhaustion**
   - Look for `insufficient_quota`, "current quota", "billing quota", "run out of credits", "no balance left", or equivalent balance-exhaustion language.
   - Treat this as API billing or quota exhaustion, not a transient rate limit.
   - For exhausted balance or credits, link to billing: `https://platform.openai.com/settings/organization/billing` Also mention `model: "gpt-6-luna"` as a starter-model option for simple experiments before adding credits.
   - For a monthly spend cap or usage limit, link to limits: `https://platform.openai.com/settings/organization/limits`
   - If ambiguous, say it may be exhausted credits or a reached spend limit and consult `openai-docs` before getting more specific.
   - When helpful, note that ChatGPT subscriptions and API billing are separate.

4. **Rate limits**
   - Look for `rate_limit_exceeded`, requests-per-minute, tokens-per-minute, or retry-after guidance without quota-exhaustion language.
   - Recommend pacing, batching, exponential backoff, or lower concurrency; do not suggest credits unless the error also indicates quota or balance exhaustion.

5. **Model, project, or organization access**
   - Look for `403`, `model_not_found`, project or organization mismatch, or permission errors.
   - Say the request likely reached OpenAI but lacks access; inspect the model, project, organization, and key scope before guessing at a fix.

## Rules

- Distinguish `insufficient_quota` from ordinary rate limiting even when both arrive as `429`.
- Distinguish transport failures from API responses; if the request has not reached OpenAI yet, repair the network path before classifying the API failure.
- Prefer the concrete error code and message over broad heuristics.
- Do not create or rotate API keys in this skill.
- Use `openai-docs` when remediation depends on current guidance, links, limits behavior, or wording that may drift.
- Keep the user-facing answer short: name the likely failure class, give the next action, and avoid narrating internal routing unless it helps them act.

## References

- `references/evals.md`: trigger, routing, and runner-ready eval cases for this skill.

Referenced files: 2

View saved version →

---
name: openai-platform-api-key
description: 'Use when Codex is asked to build, run, test, debug, or configure an OpenAI-backed or provider-unspecified AI app, UI, script, CLI, generator, or tool, especially requests phrased only as "using AI" or generators driven by forms/user input; also use for OPENAI_API_KEY or sk-proj setup. Treat this as the credential gate: inspect safely, ask reuse-vs-new before API work, and never expose plaintext.'
---

# OpenAI API Key

Use this skill only in Codex local/app sessions. Create keys through the secure OpenAI Platform connector, keep plaintext out of normal tool output, and write secrets only to a confirmed local destination.

## When To Use

Use this skill as the credential gate for API-backed work, not as the app, docs, or frontend implementation skill.

Use it when:

- The user asks for an OpenAI API key, `OPENAI_API_KEY`, or an `sk-proj` key.
- Codex will build, implement, run, test, debug, or configure an app, script, CLI, generator, UI, or tool that calls the OpenAI API, even before a live request and even if a usable key already exists.
- The user asks Codex to build, implement, run, or configure an app, script, CLI, generator, or tool that uses AI to produce outputs from user input.
- The user asks for an AI-powered app or UI that generates output from one or more input fields, forms, prompts, files, or other user-provided values.
- The user says "using AI" in an app/script/build request and does not name a different provider.

Do not use it when:

- The user only wants documentation, citations, model or API guidance, conceptual explanation, or code examples without asking Codex to build, run, configure, or debug an API-backed artifact.
- The user asks for a static frontend, visual mockup, design concept, or placeholder UI with no API-backed behavior.
- The user only asks Codex to write a one-off output directly and no app, script, generator, or API-backed tool is being built or run.
- The user names a different AI provider for the artifact.

If API access is needed and no usable key is found, offer secure key provisioning instead of leaving only placeholder docs or manual setup steps.

## Coordination With Implementation Skills

When another implementation skill also applies, run this skill first only to inspect credentials safely and send the credential decision message. Until reuse-existing-key vs create-new-key is resolved, it outranks design-first and implementation-first flows, including `build-web-apps:frontend-app-builder`; do not design UI, choose architecture, inspect API examples, write code, or run smoke tests. After the user answers, hand off to the appropriate implementation, docs, or frontend skill.

## Safety Rules

- Never request, print, summarize, quote, or paste a plaintext API key.
- Never inspect credentials with commands that can print secret values, such as `cat .env*`, `grep OPENAI_API_KEY .env*`, or `rg OPENAI_API_KEY .env*`. Use silent exit-status checks or redacted summaries only.
- Use the Platform connector `open_codex_api_key_setup` tool when it is available. Do not send local workspace paths, env-file paths, or target arrays to the picker.
- Do not use the ChatGPT-only browser/widget `_start_api_key_setup` flow from Codex.
- Only pass public JWK material (`kty`, `n`, `e`) to the connector.
- Before creating a key or writing any secret, obtain explicit confirmation. Prefer the hosted Platform picker plus local destination confirmation when it is available; if it is unavailable, fall back to a typed local destination question, then wait.
- Prefer ignored or untracked env files. In git repos, avoid tracked targets unless the user explicitly confirms that choice.
- The local helper may handle plaintext in memory and write it to the confirmed file. Its stdout/stderr must not include the key.
- When decrypting in a repo, pass the repo root as `--workspace`; the helper refuses symlink targets and targets outside that workspace.
- Keep user-facing messages concise. Unless the user asks or a failure requires it, say only that Codex will create the key securely and write it to the confirmed env file.
- Do not narrate deterministic mechanics such as helper discovery, encryption, decryption, RSA, JWKs, ciphertext, temporary files, cleanup, permissions checks, or redacted verification unless an error requires user action.
- Report only safe metadata: path, env var name, key name, org/project names, and whether an existing env var was updated.

## Mandatory First Step

Before editing, testing, running, debugging, or configuring any code that calls the OpenAI API:

1. Inspect for a usable `OPENAI_API_KEY` without printing it.
2. Unless the user explicitly asked for a new key, ask whether to reuse an existing key or create a new one. If none exists, ask whether to create one.
3. Stop until the user answers.

This applies even if:

- a usable key already exists
- no live API call will be made
- no secret will be written
- the task is "just create a script"

Finding an existing key is not permission to proceed. It only changes the question you ask.

The credential decision is a hard stop. Before the user answers, do not create directories, scaffold files, draft implementation plans, wire API-dependent code, run smoke tests, or give placeholder/manual key setup instructions. The only allowed pre-gate work is safe repo convention discovery and credential presence checks that do not print secrets.

## Credential Decision Messages

Required progress updates before or during credential inspection may be brief and limited to saying that Codex is checking credentials or opening secure key setup. They must not describe implementation plans, architecture, file choices, local destination details, or credential conclusions before the credential decision or picker handoff.

After inspecting credentials, the next substantive user-facing message must be the credential decision message. Do not send another substantive message before this decision.

Use one of these branches:

- Existing usable key found, and the user did not explicitly ask for a new key: make clear that the OpenAI API will power the app, script, or project, say that an existing usable `OPENAI_API_KEY` was found without revealing it, then ask whether to reuse that key or create a new one.
- No usable key found: make clear that the OpenAI API will power the app, script, or project, say that no usable `OPENAI_API_KEY` was found, then ask whether to create one securely.
- User explicitly asked for a new key: skip the reuse question and open the Platform picker directly when available.

After sending the credential decision message, stop until the user answers.

## Workflow

1. Inspect before acting:
   - look for a usable key without printing secret values in the current environment and likely local env files such as `.env.local`, `.env`, and ignored framework-specific env files
   - inspect env files only with no-output checks that reveal presence/absence, never with commands that echo matching lines or whole files
   - check README/setup docs, `OPENAI_BASE_URL`, and framework env docs for repo conventions separately from secret-bearing env files
   - prefer ignored or untracked env files; avoid tracked targets unless the user explicitly confirms that choice
   - default to `.env.local` and `OPENAI_API_KEY` when no stronger convention exists
2. Based on that inspection:
   - for tasks that will call the OpenAI API, when asking this up-front question, mention that the OpenAI API will power the app, script, or project before mentioning whether an existing key was found in the environment or local env files
   - if the user explicitly asked for a new key, no reuse decision is needed
   - otherwise, before building, implementing, running, testing, debugging, or configuring an app or script that calls the OpenAI API, ask up front whether to reuse an existing usable key or create a new one
   - if no usable key exists, ask whether to create one before building the rest of the app
   - ask this up front even before any live request; after asking, stop without adding an app plan, file list, code sketch, manual `OPENAI_API_KEY` instructions, or fallback placeholder setup
   - do not silently reuse a detected key for implementation, verification, smoke tests, or other live requests just because the user did not ask about credentials
   - treat requests to create or configure a key as ambiguous unless the user says they want a new key
   - if the user chooses reuse and a persistent file write is still needed, confirm the destination file/env var before writing
3. When creation is the chosen path, confirm the destination file/env var before writing. If the user has not already explicitly asked for a new key, ask whether to create one first.
   - Prefer the hosted Platform picker:
     - use `tool_search` to load `open_codex_api_key_setup`
     - call `open_codex_api_key_setup` directly with no arguments (`{}`). Do not send a key name, local paths, workspace arguments, or target arrays. The picker collects the key name, organization/project, and expiration, and sends a later widget-authored follow-up with the confirmed key name, selected opaque ids, and optional `expires_in_seconds`
     - after `open_codex_api_key_setup` returns without an error, end the current turn immediately and wait for the widget-generated follow-up prompt. Do not inspect or interpret the launch payload, search for connector contract details, run local-save steps, make another tool call, or send any non-empty user-facing message, including a picker-open confirmation, in that turn
   - After the widget follow-up, or if the picker tool is unavailable or fails before the widget opens, choose the best local env-file target from repo conventions, defaulting to `.env.local` and `OPENAI_API_KEY`.
   - Use `tool_search` to load the OpenAI Developers MCP `confirm_openai_api_key_local_destination` tool. If available, call it with the absolute workspace root, the recommended env-file target, and `OPENAI_API_KEY`. The form shows the recommended location and lets the user replace it before continuing.
   - If the local destination tool returns `approved`, use its returned `targetPath` exactly and do not ask a second destination question. If it is declined or canceled, stop.
   - If the local destination tool is unavailable, ask exactly one short question and stop: `Save the new key to <path>? Reply yes to continue, another workspace-relative env-file path to change it, or decline.` If the user declines, stop; otherwise use the confirmed path.
   - Silently check whether the selected target is tracked. If it is tracked, stop and obtain explicit confirmation that a secret will be written there. In this local fallback, do not claim the user selected an explicit organization/project target.
4. After confirmation, run the app tool preflight:
   - use `tool_search` to load `create_encrypted_openai_api_key`
   - if missing and `tool_suggest` is available, suggest installing connector `connector_2de447f3f15448ebab48783d7e4f5d81`
   - if unavailable or auth fails, ask the user to connect OpenAI Platform from `/apps` or the `$` app picker, then retry `tool_search` after they finish
5. Run `prepare`, keep `private_key_path`, and send only `recipient_public_key_jwk` to the connector.
6. Call `create_encrypted_openai_api_key` with the confirmed key name plus the picker-confirmed `organization_id` and `project_id` when the picker path was used. In the text-only fallback, omit those fields so the connector preserves its default organization/project behavior.
   - Forward the widget-confirmed `expires_in_seconds` unchanged. Its absence means Never: omit the argument, including for older widget follow-ups. Do not send `0`.
   - If creation fails, explain the returned error and stop. Do not automatically retry or change any of the user's confirmed inputs.
7. Run `decrypt` with the encrypted ciphertext, confirmed target path, env var name, and repo root as `--workspace`.
8. Verify by running the relevant project command when practical. Do not reveal or inspect the secret value directly.

## Helper

Use the helper by absolute path. `prepare` creates the temporary private key file plus a request JSON containing only the public JWK and requested key name:

```bash
node "<plugin root>/scripts/openai-platform-api-key.mjs" prepare --name "Codex"
```

After the connector returns `encrypted_api_key.ciphertext`, decrypt and write the key locally:

```bash
node "<plugin root>/scripts/openai-platform-api-key.mjs" decrypt \
  --private-key "<private key path from prepare>" \
  --ciphertext "<encrypted_api_key.ciphertext from connector result>" \
  --target "<confirmed env file path>" \
  --workspace "<repo root>" \
  --env-name OPENAI_API_KEY
```

The decrypt command updates or appends the env var, prints only safe write metadata, and refuses symlink or out-of-workspace targets.

## References

- `references/evals.md`: trigger and routing eval cases for this skill.

Referenced files: 2