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 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+)
  • uv for 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-python

The starter contains four pieces:

  • agent/src/agent.py - the OpenAI Agents SDK agent and its tools
  • agent/src/main.py - the FastAPI server that mounts the agent with the adapter's add_openai_agents_fastapi_endpoint and serves it over AG-UI on port 8000
  • src/app/api/copilotkit/[[...slug]]/route.ts - the CopilotKit runtime route that connects the page to the agent server
  • src/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:

.env
OPENAI_API_KEY=your_openai_api_key

The 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 install

npm 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 dev

This 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.

Open Inspector and confirm setup

On localhost, click the Inspector button in the corner of the app.

  1. Open Inspect, then Agent. Your agent is listed.
  2. Send a chat message. Open Inspect, then AG-UI Events. Events are moving.
  3. 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?