Programmatic Control

What is this?

Programmatic control lets you run agents outside of a chat UI — trigger agent runs, access results, and manage state entirely from code. Build agent-powered features that don't require a chat window.


export function AgentButton() {
const { agent } = useAgent();
const { copilotkit } = useCopilotKit();

  const handleClick = async () => {
    await copilotkit.runAgent("Analyze the current data");
  };

  return (
    <button onClick={handleClick} disabled={agent.isRunning}>
      {agent.isRunning ? "Analyzing..." : "Run Analysis"}
    </button>
  );

}

You can also execute individual tools programmatically — no LLM turn needed:


export function ToolButton() {
  const { copilotkit } = useCopilotKit();

  useFrontendTool({
    name: "summarize",
    description: "Summarize the document",
    handler: async () => { /* ... */ },
  });

  return (
    <button onClick={() => copilotkit.runTool({ name: "summarize" })}>
      Summarize
    </button>
  );
}

When should I use this?

Use programmatic control when you want to:

  • Trigger agent runs from buttons, forms, or other UI elements
  • Execute specific tools directly from UI interactions (without an LLM turn)
  • Build agent features without a chat window
  • Access agent state and results programmatically
  • Create fully custom agent-driven workflows

Get started by choosing your AI backend

See Integrations for all available frameworks (programmatic-control).
2087950ee