Prepare your project
Install the current openai package with npm install openai, or pip install --upgrade openai for Python. Create an application API key with api.agents.read, api.agents.write, and api.responses.write permissions. Export OPENAI_API_KEY in your server or terminal environment. Keep it outside the agent sandbox and browser.
Run the example
The example creates an OpenAI-hosted environment and asks the agent to write a report. Save it as quickstart.mjs and run node quickstart.mjs. It makes a real, billable request when executed. The model below follows the official quickstart; your project needs access to it.
import OpenAI from "openai";
const client = new OpenAI();
const events = await client.beta.agents.sessions.create({
agent: { model: "gpt-6-astra" },
environment: { type: "openai_hosted" },
input: "Write a short report to /workspace/outputs/report.md",
stream: true,
});
try {
for await (const event of events) {
console.log(JSON.stringify(event));
}
} finally {
events.controller.abort();
}Read the outcome
Watch for agent.session.turn.completed and inspect the output. A completed turn is not proof that every tool succeeded. Handle turn.failed, turn.cancelled, and session.failed. An idle event alone does not establish success. Save the session ID to continue work.
Clean up deliberately
Download needed artifacts before deleting a session. If the stream disconnects, retrieve the existing session and saved items before retrying. Blindly creating another session can repeat work. Raw HTTP requests require OpenAI-Beta: agents=v1; official SDKs add the header.
Read the official reference
Check the source for current API fields, account requirements, and service limits.
OpenAI: quickstart