Connect a CopilotKit chat over AG-UI

Connect a CopilotKit v2 chat to an Awaken Agent through the AG-UI endpoint. Start with a direct local HttpAgent, send one task, and confirm that the same thread can be read from committed history before choosing the production path.

Goal

Finish with a CopilotKit chat that renders Awaken’s AG-UI event stream and uses one stable threadId. You will also know which component must own authentication when the browser connection moves beyond local development.

Prerequisites

• Run awaken and complete self-hosting setup.
• Publish a runnable model and, if needed, the Agent the chat will use.
• Use a Node.js React project.
• Decide whether this is a local direct connection or a production connection. CopilotKit gives those paths different configuration and security boundaries.

1. Choose the connection boundary

The next steps use the local path so you can verify the protocol without adding a second server.

2. Install CopilotKit and the AG-UI client

npm install @copilotkit/react-core@1 @ag-ui/client@0.0.58

The example uses CopilotKit’s v2 exports. Keep the versions selected by your application lockfile and review CopilotKit’s migration notes before changing its major API surface.

3. Register Awaken as a local HttpAgent

Use the default endpoint first, or replace the URL with /v1/ag-ui/agents/<agent_id> to select one published Agent:

"use client";

import { HttpAgent } from "@ag-ui/client";
import { CopilotChat, CopilotKit } from "@copilotkit/react-core/v2";

const awakenAgent = new HttpAgent({
  url: "http://localhost:8080/v1/ag-ui",
  threadId: "copilotkit-demo-1",
});

export default function App() {
  return (
    <CopilotKit
      agent="awaken"
      agents__unsafe_dev_only={{ awaken: awakenAgent }}
    >
      <CopilotChat agentId="awaken" />
    </CopilotKit>
  );
}

The registry key awaken is the ID CopilotKit components use. The endpoint path selects the Awaken Agent. The explicit threadId keeps subsequent runs on the same committed Session.

Do not replace agents__unsafe_dev_only with runtimeUrl=".../v1/ag-ui". runtimeUrl expects the Copilot Runtime API, including discovery behavior that a raw AG-UI run endpoint does not provide.

4. Verify

1. Open the page and send a recognizable task, such as:

   List the two decisions in this note: choose an owner, then choose a deadline.

2. Confirm CopilotChat renders the response as it arrives.

3. Read the same thread from Awaken:

   curl -sS http://localhost:8080/v1/ag-ui/threads/copilotkit-demo-1/messages

4. Confirm the returned items contain the submitted task and the committed Agent response.

An HttpAgent keeps messages in browser memory while the page is open. If the product must survive a refresh, load committed history before constructing the Agent and provide those messages as initialMessages.

5. Move to a production path

Before traffic reaches the endpoint:

1. Choose Copilot Runtime proxying or the supported production selfManagedAgents path for your CopilotKit plan.
2. Authenticate the caller and authorize the selected Workspace, Agent, and thread at the server boundary.
3. If the browser calls Awaken directly, have your backend mint a short-lived application access token limited to ag-ui, the required thread operations, and the authorized Session binding. An application token may be sent as the HttpAgent bearer header; provider credentials and Workspace service keys may not.
4. Terminate CORS and TLS at the owning ingress or same-origin application server.
5. Re-run the task and committed-history check through the production URL.

Troubleshooting

If the table does not resolve the problem, record the selected connection path, package versions, route, HTTP status, thread ID, and correlation ID before contacting support. Remove tokens and message content first.

Next steps

• Read the AG-UI protocol reference before handling tool calls, state, context, resume input, or custom events.
• Use Manage a Session for interrupt, archive, and lifecycle decisions.
• Review Console and authentication ownership before exposing an application route.
• Use the AI SDK guide if your UI already owns a Vercel AI SDK useChat surface.