Quickstart
Run an OpenAI Agents SDK agent behind CopilotKit.
Start with your coding agent
Use this prompt to connect your OpenAI Agents SDK agent to CopilotKit and verify a working conversation. Your coding agent will follow this guide in your project, or you can work through the manual steps below.
Open your coding agent in your project's folder, or in an empty folder for a new app.This runs in a coding agent on your computer.
This quickstart gives you two working paths:
- Start from scratch to scaffold the OpenAI Agents SDK starter.
- Use an existing agent to expose your own OpenAI Agents SDK agent over AG-UI and connect it to a React app.
Prerequisites
Before you begin, you'll need the following:
- Node.js 20+
- Python 3.10+ (the starter needs 3.12+)
uvfor Python dependency management- An OpenAI API key, as
OPENAI_API_KEY
Getting started
Choose your starting point
Run the CLI
npx copilotkit@latest init --framework openai-agents-pythonThe starter contains four pieces:
agent/src/agent.py- the OpenAI Agents SDK agent and its toolsagent/src/main.py- the FastAPI server that mounts the agent with the adapter'sadd_openai_agents_fastapi_endpointand serves it over AG-UI on port 8000src/app/api/copilotkit/[[...slug]]/route.ts- the CopilotKit runtime route that connects the page to the agent serversrc/app/page.tsx- a page with shared state, a rendered backend tool, a frontend tool and a human-in-the-loop approval
Configure your environment
The CLI copies the starter's .env.example to .env in the generated project root. Set your key there:
OPENAI_API_KEY=your_openai_api_keyThe same file sets AGENT_URL=http://localhost:8000, which is where the starter's agent server listens, and COPILOTKIT_AGENT_MODEL, which picks the OpenAI model. To send the model calls to another OpenAI-compatible server, such as a gateway, also set OPENAI_BASE_URL.
Install dependencies
npm installnpm install also runs the agent's uv sync (postinstall), so the
Python side is installed too. Make sure uv is on your PATH
before running it.
Start the development server
npm run devThis starts both the Next.js app and the Python agent server.
Verify the integration
Open http://localhost:3000 and ask:
Tell me in one sentence what this app can do.If the chat streams a response, CopilotKit is connected to your OpenAI Agents SDK agent.
- If the runtime cannot reach the agent, check that the FastAPI server is running and that
AGENT_URLpoints at the AG-UI endpoint:http://localhost:8000in the starter,http://localhost:8000/agentin the existing-agent example. - If every chat turn fails with an authentication error, set
OPENAI_API_KEYin the environment of the agent process, not only in the frontend. - If a run stops right after a tool call, check whether the tool is a frontend tool. Those end the run until the browser answers, and the next request carries the result back to the model.
- If a run keeps ending with the same interrupt, an approval for a
needs_approval=Truetool is still open. A new message does not decide it; resume the interrupt with{"approved": true}or{"approved": false}.
Open Inspector and confirm setup
On localhost, click the Inspector button in the corner of the app.
- Open Inspect, then Agent. Your agent is listed.
- Send a chat message. Open Inspect, then AG-UI Events. Events are moving.
- Open Rich Threads. The list is unlocked (Intelligence is on), or locked with Copy setup prompt (Intelligence is off).
More detail: Inspector.
How is this guide?