---
title: Programmatic Control
icon: "lucide/Terminal"
description: Build non-chat agent experiences with full programmatic control.
hideTOC: true
---
import { IntegrationGrid } from "@/components/content/integration-grid";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";

## 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.

<Tabs items={['page.tsx']}>
  <Tab value="page.tsx">
  ```tsx
  import { useAgent, useCopilotKit } from "@copilotkit/react-core/v2";

  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>
    );
  }
  ```
  </Tab>
</Tabs>

<Callout type="info">
Note: If you are not using CopilotKit Cloud public access/license key, then you need to pass your agentId to useAgent() hook.
```ts
const { agent } = useAgent({agentId: "myAgent"})
````

</Callout>

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

<Tabs items={['tool-button.tsx']}>
  <Tab value="tool-button.tsx">
  ```tsx
  import { useCopilotKit, useFrontendTool } from "@copilotkit/react-core/v2";

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

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

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

## 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

<IntegrationGrid path="programmatic-control" />
