# useAgent

> Vue 3 composable for accessing AG-UI agent instances

## Overview [#overview]

`useAgent` is a Vue 3 composable that returns a reactive reference to an [AG-UI AbstractAgent](https://docs.ag-ui.com/sdk/js/client/abstract-agent) instance. The composable subscribes to agent changes and triggers reactive updates when the agent's state, messages, or execution status changes.

The composable returns `{ agent }`, where `agent` is typed as a Vue `shallowRef<AbstractAgent | null>` for API compatibility. During setup, the composable sets `agent` to an existing agent or a provisional one. If it can find neither, it throws. So `agent.value` is never `null` in practice. Access the underlying instance with `agent.value` in `<script setup>`, or rely on auto-unwrapping in `<template>`. Optional chaining remains useful when consuming the nullable public type.

<Callout type="warn">
  Throws an error if no agent can be resolved for the given `agentId` after the runtime has synced (for example, when the id does not match any agent reported by your runtime `/info` or registered via `agents__unsafe_dev_only`).
</Callout>

## Signature [#signature]

```ts
import { useAgent } from "@copilotkit/vue/v2";
import type { ShallowRef } from "vue";
import type { AbstractAgent } from "@ag-ui/client";

function useAgent(props?: UseAgentProps): {
  agent: ShallowRef<AbstractAgent | null>;
};
```

## Parameters [#parameters]

Reactive props accept `MaybeRefOrGetter`, so you can pass a plain value, a `ref`, or a getter function. The composable responds to each input according to the behavior described below.

<PropertyReference name="props" type="UseAgentProps">
  Configuration object for the composable.

  <PropertyReference name="agentId" type="MaybeRefOrGetter<string | undefined>" default='"default"'>
    ID of the agent to resolve. Resolution uses the explicit `agentId`, then the surrounding chat configuration's `agentId`, then `DEFAULT_AGENT_ID`. The id may resolve to an agent discovered by the runtime or registered by the provider. For thread-scoped use, it is the local id under which the private proxy is registered.
  </PropertyReference>

  <PropertyReference name="runtimeAgentId" type="MaybeRefOrGetter<string>">
    Runtime agent id for thread-scoped use. Pass it together with `agentId` and `threadId` (all three are required) to register a private local proxy routed to this runtime agent. Partial combinations are invalid.
  </PropertyReference>

  <PropertyReference name="threadId" type="MaybeRefOrGetter<string>">
    ID of the conversation thread for thread-scoped use. Pass it with `agentId` and `runtimeAgentId` to register the private proxy, route it to the runtime agent, and pin this thread onto the current proxy. Changing `threadId` repins that proxy. In the shared-agent form, omit it; an explicit thread from the current chat configuration is used when present.
  </PropertyReference>

  <PropertyReference name="updates" type="UseAgentUpdate[]" default="[OnMessagesChanged, OnStateChanged, OnRunStatusChanged]">
    Controls which agent changes trigger reactive updates. Options:
    - `UseAgentUpdate.OnMessagesChanged` - update when messages change
    - `UseAgentUpdate.OnStateChanged` - update when state changes
    - `UseAgentUpdate.OnRunStatusChanged` - update when execution status changes

    Pass an empty array `[]` to prevent automatic reactive updates.
  </PropertyReference>

  <PropertyReference name="throttleMs" type="MaybeRefOrGetter<number | undefined>">
    Throttle interval (in milliseconds) for updates triggered by `onMessagesChanged` and `onStateChanged`. Useful to reduce update frequency during high-frequency streaming.

    Resolved as `throttleMs ?? provider defaultThrottleMs ?? 0`. Passing `throttleMs: 0` explicitly disables throttling even when the provider specifies a non-zero `defaultThrottleMs`.

    Run lifecycle callbacks (`onRunInitialized`, `onRunFinalized`, `onRunFailed`, `onRunErrorEvent`) always fire immediately, regardless of throttling.
  </PropertyReference>
</PropertyReference>

## Return Value [#return-value]

<PropertyReference name="object" type="{ agent: ShallowRef<AbstractAgent | null> }">
  Object containing the reactive agent reference.

  <PropertyReference name="agent" type="ShallowRef<AbstractAgent | null>">
    A Vue `shallowRef` holding the AG-UI agent instance. Read it with `agent.value` in `<script setup>`, or directly (auto-unwrapped) in `<template>`. The examples below retain `agent?.` / `v-if` guards because callers consume the nullable public type.

    The examples below use these members of the unwrapped agent (`agent.value`):

    - `messages`: the conversation messages, as AG-UI `Message` objects.
    - `state`: the state that the app and the agent share.
    - `isRunning`: `true` while the agent runs.
    - `setState(newState)`: updates the shared state.
    - `subscribe(subscriber)`: subscribes to agent events. Returns `{ unsubscribe }`.

    For the other members, see the [AbstractAgent documentation](https://docs.ag-ui.com/sdk/js/client/abstract-agent).

    <PropertyReference name="runAgent" type="(parameters?: RunAgentParameters, subscriber?: AgentSubscriber) => Promise<RunAgentResult>">
      Low-level: sends a run to the agent and resolves with a `RunAgentResult` (`{ result, newMessages }`) once the run finalizes. `result` is the final value of the run and `newMessages` are the messages produced during it.

      It does not send your registered frontend tools or context, does not execute frontend tool calls, and does not chain follow-up runs. For a normal run, call `copilotkit.value.runAgent({ agent: agent.value })` from [`useCopilotKit`](/reference/vue/hooks/useCopilotKit) instead. It takes the same `forwardedProps` and resolves with the same `RunAgentResult`. Unlike `agent.runAgent()`, it does not reject when the run itself fails. The core reports the error (code `AGENT_RUN_FAILED`) to its error subscribers and resolves with `{ result: undefined, newMessages: [] }`.

      **Parameters:**
      - `parameters.forwardedProps?: any` - data to pass to the agent execution context

      To answer an interrupt, use [`useInterrupt`](/reference/vue/hooks/useInterrupt). It resumes the run for you. To resume by hand, pass the standard `resume` array with the id of the interrupt that the paused run reported: `copilotkit.value.runAgent({ agent: agent.value, resume: [{ interruptId: interrupt.id, status: "resolved", payload }] })`. If your agent emits an `on_interrupt` custom event, pass the answer as `forwardedProps: { command: { resume } }`.

      **Example:**
      ```ts
      const { copilotkit } = useCopilotKit();

      if (agent.value) {
        const { result, newMessages } = await copilotkit.value.runAgent({
          agent: agent.value,
          // Any data your agent reads from the run input.
          forwardedProps: { source: "refresh-button" },
        });
      }
      ```
    </PropertyReference>

  </PropertyReference>
</PropertyReference>

## Usage [#usage]

### Basic Usage [#basic-usage]

```vue
<script setup lang="ts">
import { useAgent } from "@copilotkit/vue/v2";

const { agent } = useAgent();
</script>

<template>
  <div v-if="agent">
    <div>Agent: {{ agent.agentId }}</div>
    <div>Messages: {{ agent.messages.length }}</div>
    <div>Running: {{ agent.isRunning ? "Yes" : "No" }}</div>
  </div>
</template>
```

### Accessing and Updating State [#accessing-and-updating-state]

```vue
<script setup lang="ts">
import { useAgent } from "@copilotkit/vue/v2";

const { agent } = useAgent();

function updateState() {
  if (!agent.value) return;
  agent.value.setState({ ...agent.value.state, count: 1 });
}
</script>

<template>
  <div>
    <pre>{{ JSON.stringify(agent?.state, null, 2) }}</pre>
    <button @click="updateState">Update State</button>
  </div>
</template>
```

### Event Subscription [#event-subscription]

```vue
<script setup lang="ts">
import { watchEffect } from "vue";
import { useAgent } from "@copilotkit/vue/v2";

const { agent } = useAgent();

watchEffect((onCleanup) => {
  if (!agent.value) return;
  const { unsubscribe } = agent.value.subscribe({
    onRunStartedEvent: () => console.log("Started"),
    onRunFinalized: () => console.log("Finished"),
  });

  onCleanup(unsubscribe);
});
</script>

<template>
  <div />
</template>
```

### Multiple Agents [#multiple-agents]

```vue
<script setup lang="ts">
import { useAgent } from "@copilotkit/vue/v2";

const { agent: primary } = useAgent({ agentId: "primary" });
const { agent: support } = useAgent({ agentId: "support" });
</script>

<template>
  <div>
    <div>Primary: {{ primary?.messages?.length ?? 0 }} messages</div>
    <div>Support: {{ support?.messages?.length ?? 0 }} messages</div>
  </div>
</template>
```

### Thread-scoped Agent [#thread-scoped-agent]

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useAgent } from "@copilotkit/vue/v2";

const threadId = ref("thread-1");

// Registers a local proxy routed to the runtime agent and pins it to this thread.
const { agent } = useAgent({
  agentId: "thread-1",
  runtimeAgentId: "default",
  threadId,
});
</script>

<template>
  <div v-if="agent">Thread: {{ agent.threadId }} ({{ agent.messages.length }} messages)</div>
</template>
```

### Optimizing Reactive Updates [#optimizing-reactive-updates]

```vue
<script setup lang="ts">
import { useAgent, UseAgentUpdate } from "@copilotkit/vue/v2";

// Only update when messages change.
const { agent } = useAgent({
  updates: [UseAgentUpdate.OnMessagesChanged],
});
</script>

<template>
  <div>Messages: {{ agent?.messages?.length ?? 0 }}</div>
</template>
```

### Throttling High-Frequency Updates [#throttling-high-frequency-updates]

```ts
import { useAgent } from "@copilotkit/vue/v2";

// Coalesce streaming message and state updates into at most one update
// per 100ms. Run lifecycle callbacks still fire immediately.
const { agent } = useAgent({ throttleMs: 100 });
```

## Behavior [#behavior]

- **Reactive updates**: The `agent` ref triggers reactivity when state, messages, or execution status changes (configurable via the `updates` parameter).
- **Reactive inputs**:
  - `agentId` and `runtimeAgentId`: register the private proxy.
  - `agentId`: selects the agent, together with core registry and connection changes.
  - `threadId`: pins or repins the current agent.
  - `updates`, `throttleMs`, and the provider's `defaultThrottleMs`: control the subscription.
- **Agent binding**: The shared-agent form resolves the explicit `agentId`, then the chat configuration's `agentId`, then `DEFAULT_AGENT_ID`, and may return an agent discovered by the runtime or registered by the provider. The thread-scoped form registers a private proxy under the local `agentId`, routes it to `runtimeAgentId`, and pins `threadId` to that proxy. All three thread-scoped properties are required together; changing `threadId` repins the existing proxy.
- **Throttling**: Message and state updates can be throttled via `throttleMs`, resolved as `throttleMs ?? provider defaultThrottleMs ?? 0`. Run lifecycle callbacks always fire immediately.
- **Error handling**: Throws an error if no agent can be resolved for the specified `agentId` after the runtime has synced.
- **State synchronization**: State updates via `setState()` are immediately available to both app and agent.
