Add Insights to Agent Context

Agent Context Insights tracks and analyzes your agent conversations

Agent Context Insights captures conversations between your users and your AI agent and classifies them with an LLM. Once set up, the Insights dashboard appears automatically in Studio, showing where the agent succeeds, where it struggles, and what content is missing. Use this data to improve the agent over time.

Insights has two parts that work together:

• Telemetry: saves conversations from your chat application to Sanity.
• Classification: a scheduled function that analyzes saved conversations with AI, extracting success scores, sentiment, and content gaps.

Telemetry alone stores raw conversations. Classification populates the dashboard. You need both.

• Code running Agent Context: Follow the setup instructions. The code examples below will add to your existing implementation.
• Sanity project ID and dataset name: Check your sanity.config.ts file, or visit Manage.
• A write token with the Editor role or similar: This is used to save conversations to your app. Note that this differs from the read token used in the setup guide. You’ll still use that to configure Agent Context. If you’re using more granular permissions, you can limit writes to the sanity.agentContextConversation document _type.
• LLM API key: For classifying conversations, you’ll need an API key from an LLM provider (Anthropic, OpenAI, etc.).

import {sanityInsightsIntegration} from '@sanity/agent-context/ai-sdk'
import {streamText} from 'ai'

const result = streamText({
  model: yourModel,
  messages,
  experimental_telemetry: {
    isEnabled: true,
    integrations: [
      sanityInsightsIntegration({
        client: writeClient,  // Sanity client with Editor permissions
        agentId: 'my-agent',  // Groups conversations by agent
        threadId: chatId,     // Unique ID per conversation
      }),
    ],
  },
})

import {saveConversation} from '@sanity/agent-context/insights'

await saveConversation({
  client: writeClient,
  agentId: 'my-agent',
  threadId: chatId,
  messages: [
    {role: 'user', content: 'How do I return an item?'},
    {role: 'assistant', content: 'You can return items within 30 days...'},
  ],
})

The classification function is a scheduled job that runs outside your app using Sanity Functions. It finds unclassified conversations and analyzes them with an LLM of your choice. The classification interval, how often the function runs, is up to you. You may want it to run once a day to accommodate daily updates, or more frequently if your agent receives more traffic.

Here’s an example function:

import {createClient} from '@sanity/client'
import {
  classifyConversation,
  getConversationsToClassify,
  getPreviousContentGaps,
} from '@sanity/agent-context/insights'
import {scheduledEventHandler} from '@sanity/functions'
import {anthropic} from '@ai-sdk/anthropic'
import {env} from 'node:process'

export const handler = scheduledEventHandler(async ({context}) => {
  if (!context.clientOptions?.token) {
    console.error('[classify-conversations] No robot token available')
    return
  }

  const client = createClient({
    projectId: env.SANITY_PROJECT_ID,
    dataset: env.SANITY_DATASET,
    apiVersion: '2026-02-27',
    token: context.clientOptions.token,
    useCdn: false,
  })

  const [conversations, previousContentGaps] = await Promise.all([
    getConversationsToClassify({client}),
    getPreviousContentGaps({client}),
  ])

  await Promise.allSettled(
    conversations.map((conv) =>
      classifyConversation({
        client,
        conversationId: conv._id,
        model: anthropic('claude-sonnet-4-5'),
        messages: conv.messages,
        previousContentGaps,
      })
    )
  )
})

For blueprint configuration, deployment, and token setup, see the Sanity Functions documentation.

The Insights studio integration is enabled by default with agentContextPlugin(). To disable it:

agentContextPlugin({insights: {enabled: false}})

This removes the conversation schema and dashboard from your Studio.

When using conversation classification, you can opt in to share classification data with Sanity. Both levels are off by default.

• shareMetrics: shares classification metrics (scores, sentiment, content gap counts), message shapes, model info, and token usage. No conversation content is included.
• shareConversations: also shares actual message contents. Provide a contact so the team can reach out and help dial in your agent.

await classifyConversation({
  client,
  conversationId: conv._id,
  model: anthropic('claude-sonnet-4-5'),
  messages: conv.messages,
  modelProvider: conv.modelProvider,
  modelId: conv.modelId,
  tokenUsage: conv.tokenUsage,
  telemetry: {
    shareMetrics: true,
    shareConversations: true,
    contact: 'you@company.com',
  },
})