Quickstart

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

Prerequisites#

Node.js 20+
Python 3.10–3.13

Getting started#

Create a free account#

Sign up for a free developer account on our Enterprise Intelligence Platform to get a license key. You'll use it later to enable persistent threads, observability, and the inspector.

Choose your starting point#

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

Start from scratch

Get started quickly with our ready-to-go Agent Spec starter.

Use an existing agent

I already have an Agent Spec setup and want to connect CopilotKit UI.

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:

# 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:

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:

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:

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

Note: these commands would install pyagentspec and wayflowcore packages from source (i.e. the respective GitHub repos). Instead, you can install these packages from PyPI separately:

pip install pyagentspec[langgraph]
pip install wayflowcore

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

uv add pyagentspec[langgraph]
uv add wayflowcore

Configure your environment#

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.

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. Run the following commands

Go to your root directory

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

Clone the starter template

git clone https://github.com/CopilotKit/with-agent-spec.git
cd with-agent-spec

Install Dependencies#

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

pnpm install

Run your project#

pnpm dev
# or npm run dev / yarn dev / bun dev

🎉 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?

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

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.

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 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 and WayFlow integration.

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