Context Fetchers

Overview

Context fetchers allow you to embed real-time data from external APIs into your agent prompts. Instead of hardcoding information in your agent prompt, context fetchers dynamically retrieve fresh data for each conversation.

Key Features

Dynamic data retrieval: Fetch real-time data from APIs.
Dynamic Prompting: Use dynamic data in your agent prompts
Headers integration: Use request-specific parameters to customize data fetching.
Data transformation: Transform API responses into the exact format your agent needs.

Context Fetchers vs Tools

Context Fetchers: Pre-populate agent prompts with dynamic data
- Run automatically before/during conversation startup
- Data becomes part of the agent's system prompt
- Perfect for: Personalized agent personas, dynamic agent guardrails
- Example Prompt: You are an assistant for ${userContext.toTemplate('user.name')} and you work for ${userContext.toTemplate('user.organization')}
Tools: Enable agents to take actions or fetch data during conversations
- Called by the agent when needed during the conversation
- Agent decides when and how to use them
- Example Tool Usage: Agent calls a "send_email" tool or "search_database" tool

Basic Usage

Let's create a simple context fetcher that retrieves user information:

import { agent, subAgent } from "@inkeep/agents-sdk";
import { contextConfig, fetchDefinition, headers } from "@inkeep/agents-core";
import { z } from "zod";

// 1. Define a schema for headers validation. All header keys are converted to lowercase.
// In this example all incoming headers will be validated to make sure they include user_id and api_key.
const personalAgentHeaders = headers({
  schema: z.object({
    user_id: z.string(),
    api_key: z.string(),
  })
});

// 2. Create the fetcher with
const userFetcher = fetchDefinition({
  id: "user-info",
  name: "User Information",
  trigger: "initialization", // Fetch only once when a conversation is started with the Agent. When set to "invocation", the fetch will be executed every time a request is made to the Agent.
  fetchConfig: {
    url: `https://api.example.com/users/${personalAgentHeaders.toTemplate('user_id')}`,
    method: "GET",
    headers: {
      Authorization: `Bearer ${personalAgentHeaders.toTemplate('api_key')}`,
    },
    transform: "user", // Extract user from response, for example if the response is { "user": { "name": "John Doe", "email": "john.doe@example.com" } }, the transform will return the user object
  },
  responseSchema: z.object({
    user: z.object({
      name: z.string(),
      email: z.string(),
    }),
  }), // Used to validate the result of the transformed api response.
  defaultValue: "Unable to fetch user information",
});

// 3. Configure context
const personalAgentContext = contextConfig({
  headers: personalAgentHeaders,
  contextVariables: {
    user: userFetcher,
  },
});

// 4. Create and use the Sub Agent
const personalAssistant = subAgent({
  id: "personal-assistant",
  name: "Personal Assistant",
  description: "A personalized AI assistant",
  prompt: `Hello ${personalAgentContext.toTemplate('user.name')}! I'm your personal assistant.`,
});

// Initialize the Agent
export const myAgent = agent({
  id: "personal-agent",
  name: "Personal Assistant Agent",
  defaultSubAgent: personalAssistant,
  subAgents: () => [personalAssistant],
  contextConfig: personalAgentContext,
});

Using Context Variables

Context variables can be used in your agent prompts using JSONPath template syntax {{contextVariableKey.field_name}}. Use the context config's toTemplate() method for type-safe templating with autocomplete and validation.

const personalGraphContext = contextConfig({
  headers: personalGraphHeaders,
  contextVariables: {
    user: userFetcher,
  },
});

const personalAgent = subAgent({
  id: "personal-agent",
  name: "Personal Assistant",
  description: "A personalized AI assistant",
  prompt: `Hello ${personalGraphContext.toTemplate('user.name')}! I'm your personal assistant.`,
});

Context variables are resolved using JSONPath notation.

Data transformation

The transform property on fetch definitions lets you extract exactly what you need from API responses using JSONPath notation:

// API returns: { "user": { "profile": { "displayName": "John Doe" } } }
transform: "user.profile.displayName"; // Result: "John Doe"

// API returns: { "items": [{ "name": "First Item" }, { "name": "Second Item" }] }
transform: "items[0].name"; // Result: "First Item"

Best Practices

Use Appropriate Triggers
- initialization: Use when data rarely changes
- invocation: Use for frequently changing data
Handle Errors Gracefully
- Always provide a defaultValue
- Use appropriate response schemas

Headers - Learn how to pass dynamic context to your agents via HTTP headers

On this page