useAgentContext

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

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

function useAgentContext(context: AgentContextInput): void;

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` automatically. Accepts a plain value, a ref, a computed, or a getter function. </PropertyReference> </PropertyReference>

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

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

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

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>

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 previous context entry is removed and the new value is re-registered, keeping the agent in sync.
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.
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.

useCopilotKit - access the underlying CopilotKit instance
CopilotKitProvider - provides the CopilotKit instance to descendant composables