Programmatic Control

Drive agent runs from code in a React Native app, with no chat UI required.

What is this?

Programmatic control is what you reach for when you want to drive an agent run from code rather than from a chat composer: a button, a form, a push notification, a voice transcript, or a background task. CopilotKit gives you three primitives that cover every trigger:

  • agent.addMessage(...): add a message to the conversation without running the agent. Pair it with copilotkit.runAgent({ agent }) when the message should start a turn.
  • copilotkit.runAgent({ agent }): the same entry point the prebuilt chat calls. It runs frontend tools, follow-up runs, and the subscriber lifecycle.
  • agent.subscribe(subscriber): a low-level AG-UI event subscription (onCustomEvent, onRunStartedEvent, onRunFinalized, onRunFailed, and more). Use it with copilotkit.runAgent({ agent, resume }) for standard AG-UI interrupts, or with copilotkit.runAgent({ agent, forwardedProps: { command: { resume, interruptEvent } } }) for the on_interrupt custom events that the LangGraph adapter sends.

When should I use this?

Use programmatic control when you want to:

  • Start agent runs from buttons, forms, or other views
  • Run one of your frontend tools directly, without an LLM turn
  • Build agent features without a chat screen (to build your own chat, see Headless UI)
  • Read agent state and results from code
  • Send a speech-to-text transcript as a user turn

Sending a message from code

Run Claude through an AG-UI endpoint

Programmatic control starts from the same AG-UI run boundary as the chat UI. Wrap Claude Agent SDK once to expose that endpoint. The frontend patterns on this page then use the same agent connection, whether they trigger a run, render a headless chat, or resolve an interrupt.

Add a user message with agent.addMessage, then call copilotkit.runAgent({ agent }). Call copilotkit.stopAgent({ agent }) to cancel a run in flight.

src/AgentTrigger.tsx
import { Button, Text, View } from "react-native";
import { useAgent, useCopilotKit } from "@copilotkit/react-native/headless";

export function AgentTrigger({ agentId }: { agentId: string }) {
  const { agent } = useAgent({ agentId });
  const { copilotkit } = useCopilotKit();

  const run = async () => {
    if (agent.isRunning) return;

    agent.addMessage({
      id: `user-${Date.now()}`,
      role: "user",
      content: "Summarize the latest sales data",
    });

    try {
      await copilotkit.runAgent({ agent });
    } catch (error) {
      console.error("CopilotKit runAgent failed:", error);
    }
  };

  const last = agent.messages[agent.messages.length - 1];

  return (
    <View>
      <Button title="Run agent" onPress={run} disabled={agent.isRunning} />
      <Button
        title="Stop"
        onPress={() => copilotkit.stopAgent({ agent })}
        disabled={!agent.isRunning}
      />
      {last?.role === "assistant" && last.content ? <Text>{last.content}</Text> : null}
    </View>
  );
}

Tap Run agent. The agent's reply streams into agent.messages, and the last assistant message shows under the buttons.

The message id comes from a timestamp. The React Native polyfills install crypto.getRandomValues, not crypto.randomUUID.

copilotkit.runAgent() vs agent.runAgent()

Both methods start the agent, but they work at different levels:

  • copilotkit.runAgent({ agent }): the default. It runs the full lifecycle: it executes frontend tools, handles follow-up runs, and sends errors to the subscriber system and the provider's onError.
  • agent.runAgent(options): the low-level method on the agent instance. It sends the request to the runtime but does not execute frontend tools or chain follow-ups. Use it only when you need direct control.

Running a tool without the model

copilotkit.runTool() runs a registered frontend tool directly. The handler runs, the tool's render shows in the chat, and both the tool call and its result are added to agent.messages. No LLM turn happens unless you ask for one.

const { copilotkit } = useCopilotKit();

const { result, error } = await copilotkit.runTool({
  name: "filter_tasks",
  parameters: { status: "open" },
  // false (default): no follow-up. "generate": the agent responds to the result.
  followUp: false,
});

The tool must be registered with useFrontendTool somewhere under the provider. See Frontend Tools.

Subscribing to agent events

agent.subscribe(subscriber) returns { unsubscribe }. The subscriber accepts every AG-UI lifecycle callback: onCustomEvent, onRunStartedEvent, onRunFinalized, onRunFailed, and the streaming deltas. Use it to drive your own progress UI, to send events to analytics, or to catch pause and resume events and answer them, as shown below.

Subscribe in an effect and unsubscribe in its cleanup:

import { useEffect } from "react";

useEffect(() => {
  const { unsubscribe } = agent.subscribe({
    onRunStartedEvent: () => setStatus("working"),
    onRunFinalized: () => setStatus("done"),
    onRunFailed: () => setStatus("failed"),
  });
  return unsubscribe;
}, [agent]);

useAgent can swap in a new agent object once the runtime connects, so keep agent in the effect's dependencies.

Resolving a frontend tool call from a button

Promise-based integrations have no native interrupt. Use useFrontendTool with a handler that returns a Promise. The handler stores its resolve callback and the pending request, your screen renders the choice anywhere, and the user's tap resolves the Promise that the agent's tool call waits on:

src/useMeetingRequest.ts
import { useCallback, useRef, useState } from "react";
import { useFrontendTool } from "@copilotkit/react-native/headless";
import { z } from "zod";

type Request = { topic: string };

export function useMeetingRequest() {
  const [request, setRequest] = useState<Request | null>(null);
  const resolver = useRef<((answer: unknown) => void) | null>(null);

  useFrontendTool({
    name: "schedule_meeting",
    description: "Ask the user to pick a meeting time.",
    parameters: z.object({ topic: z.string() }),
    handler: (args) =>
      new Promise((resolve) => {
        resolver.current = resolve;
        setRequest(args);
      }),
  });

  const answer = useCallback((value: unknown) => {
    resolver.current?.(value);
    resolver.current = null;
    setRequest(null);
  }, []);

  return { request, answer };
}

Render request in any view, and call answer({ chosen_time: "..." }) or answer({ cancelled: true }) when the user taps. The agent doesn't know that a button answered instead of a chat card. To pause inside the chat, see Human-in-the-Loop.

For every method on the core, see the useCopilotKit reference.

How is this guide?