# useAgentContext

> Vue 3 composable for providing reactive context to agents

## Overview [#overview]

`useAgentContext` registers reactive contextual data that is sent with agent runs. The context entry is added while the composable is active and removed automatically on scope cleanup, so the agent always sees an up-to-date snapshot of your application state without manual teardown.

Because the parameters accept `MaybeRefOrGetter`, you can pass plain values, refs, computeds, or getter functions. When any reactive source changes, the registered context is updated automatically. This lets you surface any serializable application state (user preferences, selected items, computed values, etc.) as context that agents can reference when generating responses or making decisions.

<Callout type="info">
  `useAgentContext` must be called within a component that has access to the
  CopilotKit instance provided by [`CopilotKitProvider`](/reference/vue/components/CopilotKitProvider). Like all Vue
  composables, call it synchronously inside `<script setup>` or a `setup()`
  function so its reactive scope is bound to the component lifecycle.
</Callout>

## Signature [#signature]

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

function useAgentContext(context: AgentContextInput): void;
```

## Parameters [#parameters]

<PropertyReference name="context" type="AgentContextInput" required>
  An object describing the context to expose to the agent.

  <PropertyReference name="description" type="MaybeRefOrGetter<string>" required>
    A human-readable description of the context. The agent uses this to
    understand what the value represents and when to reference it. Accepts a
    plain string, a ref, a computed, or a getter function.
  </PropertyReference>

  <PropertyReference name="value" type="MaybeRefOrGetter<JsonSerializable>" required>
    The context value to provide. Must resolve to a JSON-serializable value:
    `string`, `number`, `boolean`, `null`, arrays, or plain objects with string
    keys and serializable values. Non-string values are serialized with
    `JSON.stringify` before they are sent, so the agent receives a JSON string
    rather than the value you passed.
    See [What the agent receives](#what-the-agent-receives).
    Accepts a plain value, a ref, a computed, or a getter function.
  </PropertyReference>
</PropertyReference>

## Usage [#usage]

### Basic Usage [#basic-usage]

Provide simple, static application state as context for the agent.

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

useAgentContext({
  description: "Current workspace",
  value: "copilotkit-vue",
});
</script>

<template>
  <div>Workspace ready</div>
</template>
```

### Reactive Context from Component State [#reactive-context-from-component-state]

Pass refs or getters so the context updates automatically whenever the underlying state changes. There is no need to re-register.

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

const selectedCategory = ref("electronics");
const priceRange = ref({ min: 0, max: 500 });

useAgentContext({
  description: "The user's current product filter settings",
  value: () => ({
    category: selectedCategory.value,
    priceRange: priceRange.value,
  }),
});
</script>

<template>
  <select v-model="selectedCategory">
    <option value="electronics">Electronics</option>
    <option value="books">Books</option>
    <option value="clothing">Clothing</option>
  </select>
  <!-- ... price range controls ... -->
</template>
```

### Using a Computed Value [#using-a-computed-value]

A `computed` ref works anywhere a `MaybeRefOrGetter` is accepted, including the `description`.

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

const props = defineProps<{
  user: { name: string; role: string };
}>();

const userContext = computed(() => ({
  name: props.user.name,
  role: props.user.role,
}));

useAgentContext({
  description: computed(() => `Profile for ${props.user.name}`),
  value: userContext,
});
</script>

<template>
  <div>Welcome, {{ user.name }}</div>
</template>
```

### Multiple Contexts [#multiple-contexts]

Each component can register its own context. All registered contexts are visible to the agent simultaneously.

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

const collapsed = ref(false);

useAgentContext({
  description: "Current dashboard view and layout",
  value: { view: "analytics", columns: 3 },
});

useAgentContext({
  description: "Sidebar navigation state",
  value: () => ({ collapsed: collapsed.value, activeSection: "reports" }),
});
</script>

<template>
  <div>
    <!-- dashboard layout -->
  </div>
</template>
```

## What the agent receives [#what-the-agent-receives]

Every registered entry reaches the agent as `{ description, value }`, and `value` is a **JSON string** - not the object or array you passed. The AG-UI protocol types it as a string, so this is not an implementation detail you can ignore when writing the agent.

Registering this:

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

useAgentContext({
  description: "Incident dashboard records",
  value: [{ id: "INC-1041", severity: "sev1" }],
});
</script>
```

delivers this to the agent:

```json
{
  "description": "Incident dashboard records",
  "value": "[{\"id\":\"INC-1041\",\"severity\":\"sev1\"}]"
}
```

Parse it before reading any field. In a Python agent:

```python
import json

def dashboard_records(context):
    entry = next(
        (item for item in context if item["description"] == "Incident dashboard records"),
        None,
    )
    return None if entry is None else json.loads(entry["value"])
```

In a TypeScript agent:

```ts
const entry = context.find(
  (item) => item.description === "Incident dashboard records",
);
const records = entry ? JSON.parse(entry.value) : undefined;
```

Where that context list surfaces in your agent depends on your framework's AG-UI adapter - see your integration's guide for the field it populates.

<Callout type="warn">
  Do not type-check `value` against the shape you registered.
  `isinstance(entry["value"], list)` in Python, or `Array.isArray(entry.value)`
  in TypeScript, can never be true, because `value` is always a string on the
  wire. If the agent treats a failed check as "no context was sent", it refuses
  every request. The UI cannot show this fault, because the app registers the
  context correctly.
</Callout>

## Behavior [#behavior]

- **Scope lifecycle**: The context is registered while the composable's reactive scope is active and is removed automatically on scope cleanup (component unmount). No manual cleanup is required.
- **Reactive updates**: `description` and `value` are resolved with `toValue`, so refs, computeds, and getters are tracked. When a resolved value changes, the composable removes the old entry and registers the new value. The agent then sees the current value.
- **Serialization**: String values are passed through as-is. Any other value is serialized with `JSON.stringify`, so it must conform to `JsonSerializable` (`string | number | boolean | null | JsonSerializable[] | { [key: string]: JsonSerializable }`). Non-serializable values such as functions, class instances, or symbols will not serialize correctly. The agent therefore always reads a string - see [What the agent receives](#what-the-agent-receives).
- **Multiple contexts**: Multiple `useAgentContext` calls across your component tree are all visible to the agent concurrently. Each is identified internally by an ID returned from `addContext` and removed on cleanup.
- **No return value**: The composable returns `void`.
