The OpenAI Agents SDK is a light, extensible toolkit that turns prompts and language models into runnable agents. It coordinates models, tools, typed data, and execution flows so an assistant can move from conversation to real work. section 2.0 section 2.3
Think of the SDK as the orchestration layer between a model and an application. Prompting shapes behavior, model settings tune the task, schemas stabilize inputs and outputs, tools provide agency, and tracing exposes the execution path. Compared with a single prompt-and-response integration, an agent can chain multiple tool calls autonomously. section 2.6
A practical SDK workflow adds capabilities in stages:
- Create an agent from a prompt, then pin the model and generation parameters for its task. section 2.6
- Use Pydantic input and output schemas instead of brittle string parsing. section 2.6
- Attach a focused set of local functions or MCP-hosted services, limiting unnecessary tools to reduce overhead and failure risk. section 2.6
- Inspect built-in traces to debug model interactions, tool invocations, decision paths, and performance bottlenecks. section 2.6
- Deploy the resulting system inside an application, in containers, or across coordinated agents, with security and operating concerns addressed separately. section 8.0
Browser voice agent
A real-time voice agent can run in a browser through JavaScript or be built with the Python SDK. The browser receives a short-lived client key; production systems should mint that key on an authenticated backend rather than exposing a durable secret. section 8.1.1
Listing 8.1 01_embedded_agent_speech.html (agent only)
<footer> #1
<div>Get a <strong>client ephemeral key</strong> (valid briefly):</div>
<pre class="kbd"># PowerShell (no jq needed)
(Invoke-RestMethod -Uri "https://api.openai.com/v1/realtime/sessions" -Method POST `
-Headers @{ Authorization = "Bearer $env:OPENAI_API_KEY" } `
-ContentType "application/json" `
-Body '{"model":"gpt-4o-realtime-preview-2025-06-03"}').client_secret.value</pre>
<div>In production, mint the key on your backend and pass it to the browser after auth.</div>
</footer> #1
<!-- #2
Option: Bash (commented out). Uncomment below if you prefer to use curl + jq to obtain the ephemeral key.
<div>Get a <strong>client ephemeral key</strong> using Bash:</div>
<pre class="kbd"># Bash (curl + jq)
curl -s -X POST "https://api.openai.com/v1/realtime/sessions" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o-realtime-preview-2025-06-03"}' | jq -r '.client_secret.value'
</pre>
--> #2
const agent = new RealtimeAgent({ #3
name: 'Assistant',
instructions: 'You are a helpful, concise voice assistant. Speak naturally and keep replies brief unless asked for detail.',
}); #4
Inspect the embedded browser-agent listing for the ephemeral-key flow and the boundary between demonstration code and production authentication. section 8.1.1
