Skip to main content

Frameworks

CopilotKit Integration

Add a CopilotKit chat panel to a Next.js App Router application and send its model calls through your Verdictan gateway. The browser only talks to your own server route; the server route holds the Verdictan application token and calls the gateway.

The example uses CopilotKit's v2 runtime API with the AI SDK OpenAI provider in Chat Completions mode.

Before you start​

  • A running gateway from the quickstart, with its application token and a configured model.
  • A Next.js App Router project.

Configure the client​

Set three variables in the terminal that runs the Next.js server:

export VERDICTAN_GATEWAY_URL="http://127.0.0.1:41002/v1"
export VERDICTAN_CLIENT_TOKEN="<application-token>"
export VERDICTAN_MODEL="<configured-model>"

If the gateway runs on another host, use its base URL instead, still ending in /v1. Restart the server after you change them.

Install the packages:

npm install @copilotkit/runtime @copilotkit/react-core @ai-sdk/openai

Send a request​

  1. Create the runtime route. In a project with src/app/, put it under src/app/ instead.

    app/api/copilotkit/[[...path]]/route.ts
    import { createOpenAI } from "@ai-sdk/openai";
import { BuiltInAgent, CopilotRuntime, createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

const provider = createOpenAI({
  baseURL: requiredEnv("VERDICTAN_GATEWAY_URL"),
  apiKey: requiredEnv("VERDICTAN_CLIENT_TOKEN"),
});
const copilot = new CopilotRuntime({
  agents: {
    default: new BuiltInAgent({
      model: provider.chat(requiredEnv("VERDICTAN_MODEL")),
      maxRetries: 0,
      maxSteps: 1,
    }),
  },
});
const handler = createCopilotRuntimeHandler({
  runtime: copilot,
  basePath: "/api/copilotkit",
});
export const GET = handler;
export const POST = handler;

  2. Create a chat page:

    app/chat/page.tsx
    "use client";

import { CopilotChat, CopilotKitProvider } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export default function ChatPage() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      <main style={{ height: "100vh" }}>
        <CopilotChat agentId="default" />
      </main>
    </CopilotKitProvider>
  );
}

  3. Start the app with npm run dev, open /chat, and send Reply with Hello.

The assistant replies.

warning

Keep the Verdictan token on the server. Never put it in a NEXT_PUBLIC_* variable or a client prop, and protect /api/copilotkit with your application's authentication before real users can reach it.

Handle gateway decisions​

The example allows one agent step (maxSteps: 1) and no model retries. With tools, one user message can produce several model calls. Verdictan governs each model call; your application runs the tools.

When the chat shows an error or no answer, look up the gateway record:

  • A block is a refusal.
  • A budget or permission error needs a configuration change.
  • An escalation is waiting for human review. Your UI should show that state.
  • With output policies that need the complete answer, the stream arrives in one piece at the end.

A working chat does not prove tools or escalation handling. Add and test those one at a time. See Error Handling and the CopilotKit documentation.

Find the request in Verdictan​

  1. Send the test message from /chat.
  2. Find the model request in History (with capture on) or the delivered gateway events.
  3. Check that the provider, model, decision, and time match your chat.
  4. After you add tools, compare the number of model records with the agent's steps.

The browser-to-Next.js request and the server-to-gateway request are separate, so their request IDs can differ.

Next steps​