# Quickstart

> Set up Agent Spec + AG‑UI and connect a CopilotKit UI. Includes per‑adapter install steps and a minimal endpoint.

Agent Spec is a specification language that declares the structure of your agents and workflows. You can run an Agent Spec agent on LangGraph or on WayFlow (the Oracle reference framework for Agent Spec). This page connects that agent to a CopilotKit chat.

## Start with your coding agent [#start-with-your-coding-agent]

Use this prompt to connect your Agent Spec 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.

<PageAgentPrompt />

## Prerequisites [#prerequisites]

- Node.js 20+
- Python 3.10 to 3.13

## Getting started [#getting-started]

<Steps>
  <Step>
    ### Set up CopilotKit Intelligence [#set-up-copilotkit-intelligence]

    <SignupLink surface="docs_agent_spec_quickstart_step1">Sign in to cloud-hosted Intelligence</SignupLink>. You will connect the app after you create or clone it below.
  </Step>

  <Step>
      ### Choose your starting point [#choose-your-starting-point]

      You can either start fresh with our starter template or connect CopilotKit to an existing Agent Spec agent.

      <TailoredContent
          className="step"
          id="agent-spec-quickstart-path"
      >
    <TailoredContentOption
      id="starter"
      title="Start from scratch"
      description="Get started quickly with our ready-to-go Agent Spec starter."
    >
      <Step>
          ### Install the Agent Spec AG‑UI adapter (backend) [#install-the-agent-spec-agui-adapter-backend]

          The AG‑UI integration for Agent Spec lives in `ag-ui/integrations/agent-spec/python`. The starter uses it to set up the agent environment. Clone it:

          ```bash
          # Clone the adapter and move into the Python package
          git clone --depth 1 --filter=blob:none --sparse https://github.com/ag-ui-protocol/ag-ui.git
          cd ag-ui
          git sparse-checkout set integrations/agent-spec/python
          cd integrations/agent-spec/python
          ```

          Install the extra for the framework that runs your agent:

          ```bash
          uv sync --extra langgraph                         # for LangGraph
          uv sync --extra wayflow                           # for WayFlow
          uv sync --extra langgraph --extra wayflow         # for both
          ```

      </Step>
      <Step>
          ### Configure your environment [#configure-your-environment]

          ```bash
          export OPENAI_API_KEY=...
          export OPENAI_MODEL=gpt-6-luna
          ```

          To use another OpenAI-compatible provider, such as a local vLLM server or Together AI, also set `OPENAI_BASE_URL` to its endpoint.

          See the [Agent Spec AG-UI tutorial](https://oracle.github.io/agent-spec/26.1.0/howtoguides/howto_ag_ui.html).
      </Step>
      <Step>
          ### Scaffold the UI [#scaffold-the-ui]

          Use our starter repo template: https://github.com/CopilotKit/with-agent-spec. It includes an example definition of an Agent Spec agent [here](https://github.com/CopilotKit/with-agent-spec/blob/main/agent/src/agentspec_agent.py). Run the following commands

          Go to your root directory

          ```bash
          # If you are in the path integrations/agent-spec/python, then run the following command to go to root
          cd ../../../../
          ```
          Clone the starter template

          ```bash
          git clone https://github.com/CopilotKit/with-agent-spec.git
          cd with-agent-spec
          npx copilotkit@latest project select
          ```

          `project select` writes the server-side project API key to `.env` as `CPK_INTELLIGENCE_API_KEY`.

      </Step>
      <Step>
          ### Install Dependencies [#install-dependencies]

          Run the following commands to install your dependencies in the start repository

          ```bash
          pnpm install
          ```

      </Step>
      <Step>
          ### Run your project [#run-your-project]

          ```bash
          pnpm dev
          # or npm run dev / yarn dev / bun dev
          ```
      </Step>
      <Step>
        ### Start chatting [#start-chatting]

        Your AI agent is now ready to use. Navigate to `localhost:3000` and try asking it some questions:

        - Can you tell me a joke?
        - Can you help me understand AI?
        - What do you think about React?

        <Accordions className="mb-4">
            <Accordion title="Troubleshooting">
                - If the chat shows a connection error, make sure that the agent runs on port 8000.
                - If the connection error stays, use `127.0.0.1` or `0.0.0.0` in place of `localhost` in the agent URL.
                - If the agent does not reply, make sure that `OPENAI_API_KEY` is set in the terminal that runs the agent.
                - If the frontend cannot import `@ag-ui/client`, install the package in your frontend.
            </Accordion>
        </Accordions>

    </Step>

    <Step>
        ### Open Inspector and confirm setup [#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](/agent-spec/inspector).
    </Step>

    </TailoredContentOption>
    <TailoredContentOption
      id="bring-your-own"
      title="Use an existing agent"
      description="I already have an Agent Spec setup and want to connect CopilotKit UI."
    >
      <Step>
          ### Install the Agent Spec AG‑UI adapter (backend) [#install-the-agent-spec-agui-adapter-backend-1]

          The AG‑UI integration for Agent Spec lives in `ag-ui/integrations/agent-spec/python`. Clone it:

          ```bash
          # Clone the adapter and move into the Python package
          git clone --depth 1 --filter=blob:none --sparse https://github.com/ag-ui-protocol/ag-ui.git
          cd ag-ui
          git sparse-checkout set integrations/agent-spec/python
          cd integrations/agent-spec/python
          ```

          Install the extra for the framework that runs your agent:

          ```bash
          uv sync --extra langgraph                         # for LangGraph
          uv sync --extra wayflow                           # for WayFlow
          uv sync --extra langgraph --extra wayflow         # for both
          ```
      </Step>
      <Step>
          ### Configure your environment [#configure-your-environment-1]

          ```bash
          export OPENAI_API_KEY=...
          export OPENAI_MODEL=gpt-6-luna
          ```

          To use another OpenAI-compatible provider, such as a local vLLM server or Together AI, also set `OPENAI_BASE_URL` to its endpoint. The `main.py` file below reads `OPENAI_MODEL` and `OPENAI_BASE_URL`.

          See the [Agent Spec AG-UI tutorial](https://oracle.github.io/agent-spec/26.1.0/howtoguides/howto_ag_ui.html).
      </Step>
      <Step>
          ### Set up your Agent [#set-up-your-agent]

          Go to the `ag_ui_agentspec` directory:

          ```bash
          cd ag_ui_agentspec
          ```

          Then create a `main.py` file in it:

          ```bash
          #file path: ag-ui/integrations/agent-spec/python/ag_ui_agentspec/main.py
          import os
          from pyagentspec.agent import Agent
          from pyagentspec.llms import OpenAiCompatibleConfig
          from pyagentspec.serialization import AgentSpecSerializer
          from fastapi import FastAPI
          from ag_ui_agentspec.agent import AgentSpecAgent
          from ag_ui_agentspec.endpoint import add_agentspec_fastapi_endpoint
          import uvicorn

          agentspec_agent = Agent(
              name="AgentSpecAgent",
              description="A starter Agent that can call tools.",
              system_prompt="You are a helpful assistant, named Specky, that speaks a lot.",
              llm_config=OpenAiCompatibleConfig(
                  name="my-llm",
                  model_id=os.getenv("OPENAI_MODEL", "gpt-6-luna"),
                  url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1"),
              ),
          )

          agent_spec_config = AgentSpecSerializer().to_json(agentspec_agent)


          #OR you can specify your own agent_spec_config like below
          #agent_spec_config = <loaded json/yaml string of your Agent Spec agent>

          runtime = "langgraph"  # or "wayflow"

          app = FastAPI()
          agent = AgentSpecAgent(agent_spec_config=agent_spec_config, runtime=runtime)
          add_agentspec_fastapi_endpoint(app, agentspec_agent=agent, path="/")

          if __name__ == "__main__":
              uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)
          ```
      </Step>
      <Step>
          ### Create your frontend [#create-your-frontend]

          CopilotKit works with any React-based frontend. We'll use Next.js for this example.
          Go to your root directory, then create a Next.js project

          ```bash
          npx create-next-app@latest my-copilot-app
          cd my-copilot-app
          ```
      </Step>
      <Step>
          ### Install CopilotKit packages [#install-copilotkit-packages]

          ```npm
          npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/client@1.0.2
          ```
      </Step>
      <Step>
          ### Add the Copilot Runtime route [#add-the-copilot-runtime-route]

          Create an API route to connect CopilotKit to your Agent Spec agent:

          ```tsx title="app/api/copilotkit/[[...slug]]/route.ts" doctest="component"
          import {
            CopilotKitIntelligence,
            CopilotRuntime,
            createCopilotRuntimeHandler,
          } from "@copilotkit/runtime/v2";
          import { HttpAgent } from "@ag-ui/client";

          const runtime = new CopilotRuntime({
            agents: {
              my_agent: new HttpAgent({ url: "http://localhost:8000/" }),
            },
            // [!code highlight:9]
            intelligence: new CopilotKitIntelligence({
              apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
            }),
            // Demo only: the browser sends no x-user-id header, so all visitors share
            // one "anonymous" history. Before you deploy, return the verified session user.
            identifyUser: (request) => ({
              id: request.headers.get("x-user-id") ?? "anonymous",
              name: request.headers.get("x-user-name") ?? "Anonymous",
            }),
          });

          const handler = createCopilotRuntimeHandler({
            runtime,
            basePath: "/api/copilotkit",
          });

          export const GET = handler;
          export const POST = handler;
          export const PATCH = handler;
          export const DELETE = handler;
          ```

          From this frontend app directory, connect the runtime to an Intelligence project:

          ```bash title="Terminal"
          npx copilotkit@latest project select
          ```

          The command writes the server-side project API key to `.env`. The runtime reads it here:

          ```plaintext title=".env"
          CPK_INTELLIGENCE_API_KEY=cpk-...
          ```

          <Callout type="info" title="Running without the Intelligence Platform?">
            Drop the `intelligence` and `identifyUser` options and the runtime falls back
            to SSE mode with an in-memory runner. Chat still works, but Threads and the
            Inspector stay locked and the key is never read. See
            [Connect your runtime to Intelligence](/agent-spec/intelligence/quickstart) for the
            full constructor and how to confirm the key is in use.
          </Callout>
      </Step>
      <Step>
          ### Configure CopilotKit Provider [#configure-copilotkit-provider]

          Wrap your application with the CopilotKit provider:

          ```tsx title="app/providers.tsx"
          "use client";

          import { CopilotKit } from "@copilotkit/react-core/v2";

          export function Providers({ children }: { children: React.ReactNode }) {
            return (
              <CopilotKit runtimeUrl="/api/copilotkit" agent="my_agent" useSingleEndpoint={false}>
                {children}
              </CopilotKit>
            );
          }
          ```

          Render `Providers` around your app in `app/layout.tsx`:

          ```tsx title="app/layout.tsx"
          import { Providers } from "./providers"; // [!code highlight]
          import "@copilotkit/react-core/v2/styles.css";
          import './globals.css';

          // ...

          export default function RootLayout({ children }: {children: React.ReactNode}) {
            return (
              <html lang="en">
                <body>
                  {/* [!code highlight:3] */}
                  <Providers>
                    {children}
                  </Providers>
                </body>
              </html>
            );
          }
          ```

          <Callout type="info" title="This relative runtimeUrl assumes Next.js serves the runtime">
            `/api/copilotkit` resolves only because Next.js serves your app and the runtime from the
            same origin. A client-only frontend has no shared origin, so it needs a standalone runtime
            server of its own and an absolute `runtimeUrl` such as
            `http://localhost:8200/api/copilotkit`. See the [React SPA](/agent-spec/react-spa), [Vue](/vue),
            [Angular](/angular), and [React Native](/react-native) guides for that setup.
          </Callout>
      </Step>
      <Step>
        ### Add the chat interface [#add-the-chat-interface]

        Add the CopilotSidebar component to your page:

        ```tsx title="app/page.tsx"
        "use client"; // [!code highlight]

        import { CopilotSidebar } from "@copilotkit/react-core/v2"; // [!code highlight:1]

        export default function Page() {
          return (
            <main>
              <h1>Your App</h1>
              {/* [!code highlight:1] */}
              <CopilotSidebar />
            </main>
          );
         }
        ```
       </Step>
       <Step>
          ### Start your agent [#start-your-agent]

           From your agent directory, start the agent server:

          ```bash
          cd ..
          cd ag-ui/integrations/agent-spec/python/ag_ui_agentspec
          uv run main.py
          ```

          Your agent will be available at `http://localhost:8000`.
       </Step>
       <Step>
           ### Start your UI [#start-your-ui]

           In a separate terminal, navigate to your frontend directory and start the development server:

           <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
              <Tab value="npm">
                   ```bash
                  cd my-copilot-app
                  npm run dev
                  ```
              </Tab>
              <Tab value="pnpm">
                   ```bash
                   cd my-copilot-app
                   pnpm dev
                   ```
               </Tab>
               <Tab value="yarn">
                   ```bash
                   cd my-copilot-app
                   yarn dev
                   ```
               </Tab>
               <Tab value="bun">
                   ```bash
                   cd my-copilot-app
                   bun dev
                   ```
               </Tab>
           </Tabs>
      </Step>
      <Step>
        ### Start chatting [#start-chatting-1]

        Your AI agent is now ready to use. Navigate to `localhost:3000` and try asking it some questions:

        - Can you tell me a joke?
        - Can you help me understand AI?
        - What do you think about React?

        <Accordions className="mb-4">
            <Accordion title="Troubleshooting">
                - If the chat shows a connection error, make sure that the agent runs on port 8000.
                - If the connection error stays, use `127.0.0.1` or `0.0.0.0` in place of `localhost` in the agent URL.
                - If the agent does not reply, make sure that `OPENAI_API_KEY` is set in the terminal that runs the agent.
                - If the frontend cannot import `@ag-ui/client`, install the package in your frontend.
            </Accordion>
        </Accordions>

    </Step>

    <Step>
        ### Open Inspector and confirm setup [#open-inspector-and-confirm-setup-1]

        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](/agent-spec/inspector).
    </Step>

    </TailoredContentOption>
  </TailoredContent>
  </Step>
</Steps>

## Next steps [#next-steps]

Follow per-adapter tutorials: [LangGraph integration](/agent-spec/langgraph) and [WayFlow integration](/agent-spec/wayflow). To bind backend tools to your agent, see "Bind backend tools" on the [LangGraph](/agent-spec/langgraph#bind-backend-tools) or [WayFlow](/agent-spec/wayflow#bind-backend-tools) page.
