---
title: Quickstart
description: Set up Agent Spec + AG‑UI and connect a CopilotKit UI. Includes per‑adapter install steps and a minimal endpoint.
icon: "lucide/Play"
hideTOC: true
---
<OpsPlatformCTA
  variant="card"
  title="Ship Agent Spec to production"
  body="Add persistent threads, observability, and the inspector with the Enterprise Intelligence Platform."
  ctaLabel="Create a free account"
  surface="docs_agent_spec_quickstart"
/>

## Prerequisites

- Node.js 20+
- Python 3.10–3.13

## Getting started

<Steps>
  <Step>
    ### Create a free account

    <SignupLink surface="docs_agent_spec_quickstart_step1">Sign up for a free developer account</SignupLink> on our Enterprise Intelligence Platform to get a license key. You'll use it later to enable persistent threads, observability, and the inspector.
  </Step>

  <Step>
      ### 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) 

          The AG‑UI integration for Agent Spec lives in `ag-ui/integrations/agent-spec/python`. You will need it to activate your agent environment in the starter. Here's how to install 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
          ```

          This will setup AG-UI integration which will be used by the starter repository to install starter templates agent. This is only for agent environment setup
          As this integration package uses `uv` as the package manager, you can easily install it with:

          ```bash
          uv sync
          ```

          Agent Spec is a specification language that declares the structure of your agents and workflows. Agent Spec agents can be run on various agent frameworks. Currently, we support LangGraph and WayFlow (Oracle's reference agent framework, with native support for Agent Spec).
          Here are the different installation options depending on which agent framework you want to execute your Agent Spec agent on:

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

          Alternatively, you can use `pip`:

          ```bash
          pip install -e .[wayflow]
          pip install -e .[langgraph]
          pip install -e .[wayflow,langgraph]
          ```

          Note: these commands would install [`pyagentspec`](https://github.com/oracle/agent-spec) and [`wayflowcore`](https://github.com/oracle/wayflow) packages from source (i.e. the respective GitHub repos).
          Instead, you can install these packages from PyPI separately:

          ```bash
          pip install pyagentspec[langgraph]
          pip install wayflowcore
          ```

          or you can also use uv (In case you encounter any issues with pip installation)

          ```bash
          uv add pyagentspec[langgraph]
          uv add wayflowcore
          ```
        
      </Step>
      <Step>
          ### Configure your environment

          ```bash
          export OPENAI_API_KEY=...
          export OPENAI_MODEL=gpt-5.4
          ```

          Note that these environment variables can point to any OpenAI-compatible LLM provider (e.g., local vLLM server, Together AI), but the variable names need to be `OPENAI_API_KEY` and `OPENAI_MODEL`.

          Reference: Agent Spec docs AG‑UI tutorial at https://oracle.github.io/agent-spec/26.1.0/howtoguides/howto_ag_ui.html.
      </Step>
      <Step>
          ### 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
          ```

      </Step>
      <Step>
          ### Install Dependencies

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

          ```bash
          pnpm install
          ```
          
      </Step>
      <Step>
          ### Run your project

          ```bash
          pnpm dev
          # or npm run dev / yarn dev / bun dev
          ```
      </Step>
      <Step>
        ### 🎉 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 you're having connection issues, try using `0.0.0.0` or `127.0.0.1` instead of `localhost`
                - Make sure your agent is running on port 8000
                - Check that your OpenAI API key is correctly set
                - Verify that the `@ag-ui/client` package is installed in your frontend
            </Accordion>
        </Accordions>

    </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)

          The AG‑UI integration for Agent Spec lives in `ag-ui/integrations/agent-spec/python`. Here's how to install 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
          ```

          As this integration package uses `uv` as the package manager, you can easily install it with:

          ```bash
          uv sync
          ```

          Agent Spec is a specification language that declares the structure of your agents and workflows. Agent Spec agents can be run on various agent frameworks. Currently, we support LangGraph and WayFlow (Oracle's reference agent framework, with native support for Agent Spec).
          Here are the different installation options depending on which agent framework you want to execute your Agent Spec agent on:

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

          Alternatively, you can use `pip`:

          ```bash
          pip install -e .[wayflow]
          pip install -e .[langgraph]
          pip install -e .[wayflow,langgraph]
          ```

          Note: these commands would install [`pyagentspec`](https://github.com/oracle/agent-spec) and [`wayflowcore`](https://github.com/oracle/wayflow) packages from source (i.e. the respective GitHub repos).
          Instead, you can install these packages from PyPI separately:

          ```bash
          pip install pyagentspec[langgraph]
          pip install wayflowcore
          ```

           or you can also use uv (In case you encounter any issues with pip installation)

          ```bash
          uv add pyagentspec[langgraph]
          uv add wayflowcore
          ```
      </Step>
      <Step>
          ### Configure your environment

          ```bash
          export OPENAI_API_KEY=...
          export OPENAI_MODEL=gpt-5.4
          ```

          Note that these environment variables can point to any OpenAI-compatible LLM provider (e.g., local vLLM server, Together AI), but the variable names need to be `OPENAI_API_KEY` and `OPENAI_MODEL`.

          Reference: Agent Spec docs AG‑UI tutorial at https://oracle.github.io/agent-spec/26.1.0/howtoguides/howto_ag_ui.html.
      </Step>
      <Step>
          ### Set up your Agent

          Go to ag_ui_agentspec directory

          ```bash
          cd ag_ui_agentspec
          ```

          create a main.py file in the ag_ui_agentspec directory 


          ```bash
          #file path: ag-ui/integrations/agent-spec/python/ag_ui_agentspec/main.py
          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="gpt-5.4",
                  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

          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

          ```npm
          npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/client
          ```
      </Step>
      <Step>
          ### Setup Copilot Runtime

          Create an API route to connect CopilotKit to your Pydantic AI agent:

          ```tsx title="app/api/copilotkit/route.ts"
          import {
            CopilotRuntime,
            ExperimentalEmptyAdapter,
            copilotRuntimeNextJSAppRouterEndpoint,
          } from "@copilotkit/runtime";
          import { HttpAgent } from "@ag-ui/client";
          import { NextRequest } from "next/server";

          const serviceAdapter = new ExperimentalEmptyAdapter();

          const runtime = new CopilotRuntime({
            agents: {
              my_agent: new HttpAgent({ url: "http://localhost:8000/" }),
            }
          });

          export const POST = async (req: NextRequest) => {
            const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
              runtime,
              serviceAdapter,
              endpoint: "/api/copilotkit",
            });

            return handleRequest(req);
          };
          ```
      </Step>
      <Step>
          ### Configure CopilotKit Provider

          Wrap your application with the CopilotKit provider:

          ```tsx title="app/layout.tsx"
          import { CopilotKit } from "@copilotkit/react-core/v2"; // [!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] */}
                  <CopilotKit runtimeUrl="/api/copilotkit" agent="my_agent">
                    {children}
                  </CopilotKit>
                </body>
              </html>
            );
          }
          ```
      </Step>
      <Step>
        ### Add the chat interface

        Add the CopilotSidebar component to your page:

        ```tsx title="app/page.tsx"
        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

           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

           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!

        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 you're having connection issues, try using `0.0.0.0` or `127.0.0.1` instead of `localhost`
                - Make sure your agent is running on port 8000
                - Check that your OpenAI API key is correctly set
                - Verify that the `@ag-ui/client` package is installed in your frontend
            </Accordion>
        </Accordions>

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

## Tools and tool registry

If your Agent Spec includes server-side tools that execute in the same environment as the agent, map them by name to Python callables in a dictionary `tool_registry` when loading `AgentSpecAgent`.

```python title="Bind backend tools by name"
from __future__ import annotations
from fastapi import FastAPI
from ag_ui_agentspec.agent import AgentSpecAgent
from ag_ui_agentspec.endpoint import add_agentspec_fastapi_endpoint

def get_weather(city: str) -> Dict[str, Any]:
    return {"city": city, "temp_c": 22}

tool_registry = {"get_weather": get_weather}

app = FastAPI()
agent = AgentSpecAgent(
    agent_spec_config=<json/yaml string of your Agent Spec Agent>,
    runtime="langgraph",  # or "wayflow"
    tool_registry=tool_registry,
)
add_agentspec_fastapi_endpoint(app, agentspec_agent=agent, path="/")
```

Frontend tools (corresponding to Agent Spec `ClientTool`) run in the browser and don't need to be added to the tool registry — see [Generative UI Frontend Tools](/agent-spec/frontend-tools) for details.

## What is happening under the hood

Agent Spec, and the `pyagentspec` SDK, helps you define agents and workflows in a readable and portable config object/JSON file.
The different adapters, LangGraph and WayFlow, loads your Agent Spec configs into framework-specific objects and executes them. In other words, Agent Spec is the "compiler", and the frameworks are the "runtimes".
During this conversion process, the adapter configures the loaded object so that it would emit Agent Spec Tracing events. These are standardized across runtimes.
Finally, the AG-UI Agent Spec integration listens to Agent Spec Tracing events and exports them to AG-UI events. These include agent execution, tool calls, messages being sent by the agent, etc.
In other words, if the agent emits an event during execution (this is runtime-dependent), a corresponding AG-UI event will be created.
In the frontend, CopilotKit converts and renders AG-UI events into the UI.

## Next steps

Follow per-adapter tutorials: [LangGraph integration](/agent-spec/langgraph) and [WayFlow integration](/agent-spec/wayflow).

## Learn more

- AG-UI docs: https://docs.ag-ui.com/introduction
- Agent Spec docs: https://oracle.github.io/agent-spec/development/docs_home.html
- Agent Spec x AG-UI tutorial: https://oracle.github.io/agent-spec/26.1.0/howtoguides/howto_ag_ui.html
- Agent Spec Tracing: https://oracle.github.io/agent-spec/development/agentspec/tracing.html