CopilotKit

import { HttpAgent } from '@ag-ui/client';
import { CopilotRuntime, createCopilotRuntimeHandler, InMemoryAgentRunner } from '@copilotkit/runtime/v2';
import { ScriptedAgent } from '@/lib/scripted-agent';

// CopilotKit's runtime with one AG-UI agent and no model adapter: it passes the agent's events to the
// page. AGENT_URL points it at your AG-UI server (LangGraph, Mastra, CrewAI, Pydantic AI and others).
const runtime = new CopilotRuntime({
  agents: { default: process.env.AGENT_URL ? new HttpAgent({ url: process.env.AGENT_URL }) : new ScriptedAgent() },
  runner: new InMemoryAgentRunner(),
});

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

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

'use client';

import { CopilotKitProvider } from '@copilotkit/react-core/v2';
import { Suspense, type ReactNode } from 'react';

export function Providers({ children }: { children: ReactNode }) {
  // With cacheComponents (on in new Next.js 16.4 apps), `next build` fails without this boundary:
  // the provider reads the clock (Date.now()) while it renders, which a prerender may not.
  return (
    <Suspense fallback={null}>
      <CopilotKitProvider runtimeUrl="/api/copilotkit">{children}</CopilotKitProvider>
    </Suspense>
  );
}

'use client';

import { ToolCallStatus, useHumanInTheLoop } from '@copilotkit/react-core/v2';
import { ToolApprovalCard, type ApprovalPolicy, type ToolPart } from 'signoff-ui';
import { z } from 'zod';

/** The answer respond sent, or undefined when the result is something else, such as an error. */
function readAnswer(result: string) {
  try {
    return JSON.parse(result) as { approved: boolean; reason?: string };
  } catch {
    return undefined;
  }
}

/** The call as the AI SDK tool part ToolApprovalCard reads: waiting for a person, or answered. */
function toToolPart(toolCallId: string, input: unknown, result: string | undefined): ToolPart {
  const part = { type: 'dynamic-tool', toolName: 'run_command', toolCallId, input } as const;
  if (result === undefined) return { ...part, state: 'approval-requested', approval: { id: toolCallId } };
  // Complete: the answer respond sent, or an error (a stopped run, arguments that didn't parse).
  const answer = readAnswer(result);
  const reason = answer ? answer.reason : result;
  return answer?.approved
    ? { ...part, state: 'approval-responded', approval: { id: toolCallId, approved: true, reason } }
    : { ...part, state: 'output-denied', approval: { id: toolCallId, approved: false, reason } };
}

export function RunCommandApproval({ policy }: { policy: ApprovalPolicy }) {
  useHumanInTheLoop(
    {
      name: 'run_command',
      description: 'Run a shell command, once the user approves it',
      parameters: z.object({ command: z.string() }),
      render: ({ toolCallId, args, status, respond, result }) => {
        // The arguments are still streaming in, and there is no respond to answer with yet.
        if (status === ToolCallStatus.InProgress) return null;
        return (
          <ToolApprovalCard
            part={toToolPart(toolCallId, args, result)}
            policy={policy}
            onRespond={({ approved, reason }) => respond?.({ approved, reason })}
          />
        );
      },
    },
    // CopilotKit registers render once: these deps register it again when the rules change, so a
    // rule added with Always answers the next call. It compares them as JSON, so list data.
    [policy.rules, policy.ready],
  );
  return null;
}

'use client';

import { ToolCallStatus, useHumanInTheLoop } from '@copilotkit/react-core/v2';
import { DiffReview, decisionsFromToolOutput, reviewToolOutput } from 'signoff-ui';
import { z } from 'zod';

const file = z.object({ path: z.string(), oldContent: z.string().optional(), newContent: z.string().optional() });

/** The review respond sent, or undefined when the result is something else, such as an error. */
function readReview(result: string): unknown {
  try {
    return JSON.parse(result);
  } catch {
    return undefined;
  }
}

export function ReviewChanges() {
  useHumanInTheLoop({
    name: 'review_changes',
    description: 'Propose edits to files, which apply once the user reviews them',
    parameters: z.object({ files: z.array(file) }),
    render: ({ args, status, respond, result }) => {
      // The files are still streaming in, and may be cut short.
      if (status === ToolCallStatus.InProgress) return null;
      return (
        <DiffReview
          files={args.files}
          // Answered: the review stays on the page, read-only, with the decisions it sent.
          readOnly={status === ToolCallStatus.Complete}
          decisions={status === ToolCallStatus.Complete ? decisionsFromToolOutput(readReview(result)) : undefined}
          onSubmit={(review) => respond?.(reviewToolOutput(review))}
        />
      );
    },
  });
  return null;
}

'use client';

import type { Message } from '@ag-ui/client';
import { useAgent, useInterrupt } from '@copilotkit/react-core/v2';
import { ApprovalCard } from 'signoff-ui';

/** The name and arguments of the call an interrupt guards, from the agent's messages. */
function callOf(messages: readonly Message[], toolCallId: string | undefined) {
  for (const message of messages) {
    if (message.role !== 'assistant') continue;
    const call = message.toolCalls?.find((c) => c.id === toolCallId);
    if (!call) continue;
    try {
      return { name: call.function.name, input: JSON.parse(call.function.arguments) as unknown };
    } catch {
      return { name: call.function.name, input: call.function.arguments };
    }
  }
  return undefined;
}

export function DeployApproval() {
  const { agent } = useAgent();
  useInterrupt({
    // The interrupts that guard a tool call; give the others a UI of their own.
    enabled: ({ value }) => !!(value as { toolCallId?: string } | undefined)?.toolCallId,
    render: ({ interrupt, resolve }) => {
      const call = callOf(agent.messages, interrupt?.toolCallId);
      return (
        <ApprovalCard
          toolName={call?.name ?? 'tool'}
          input={call?.input}
          description={interrupt?.message}
          onDecide={async ({ decision, reason }) => {
            await resolve({ approved: decision.startsWith('allow'), reason });
          }}
        />
      );
    },
  });
  return null;
}

'use client';

import { CopilotChat } from '@copilotkit/react-core/v2';
import { useApprovalPolicy } from 'signoff-ui';
import { DeployApproval } from './deploy-approval';
import { ReviewChanges } from './review-changes';
import { RunCommandApproval } from './run-command-approval';

export default function Page() {
  // The rules For this session and Always add: the next call they cover is answered without asking.
  const policy = useApprovalPolicy();
  return (
    <>
      <RunCommandApproval policy={policy} />
      <ReviewChanges />
      <DeployApproval />
      <CopilotChat className="chat" />
    </>
  );
}

const { copilotkit } = useCopilotKit();
const { agent } = useAgent();
// A frontend tool: CopilotKit sends it with each run it starts, and runs it when the agent calls it.
useFrontendTool({
  name: 'notify',
  description: 'Post a message in a team channel',
  parameters: z.object({ channel: z.string(), text: z.string() }),
  handler: async ({ channel }) => `Posted in ${channel}`,
});
const { messages, status, respond } = useAgUiAgent(agent, {
  // Resume through CopilotKit, so the run that resumes has the frontend tools too.
  runAgent: (parameters) => copilotkit.runAgent({ agent, ...parameters }),
});