CopilotKit

useAgentContext

Vue 3 composable for providing reactive context to agents

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.

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.

Signature

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

function useAgentContext(context: AgentContextInput): void;

Parameters

Prop

Type

Usage

Basic Usage

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

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

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

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

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

Related