Headers in TypeScript SDK

Define and validate HTTP headers in the TypeScript SDK to pass dynamic context for personalized agent interactions.

Overview

Headers allow you to pass request-specific values (like user IDs, authentication tokens, or organization metadata) to your Agent at runtime via HTTP headers. These values are validated, cached per conversation, and made available throughout your Agent system for:

Context Fetchers: Dynamic data retrieval based on request values
External Tools: Authentication and personalization for API calls
Agent Prompts: Personalized responses using context variables

Passing context via headers

Include context values as HTTP headers when calling your agent API. These headers are validated against your configured schema and cached for the conversation.

curl -N \
  -X POST "http://localhost:3003/api/chat" \
  -H "Authorization: Bearer $INKEEP_API_KEY" \
  -H "user_id: u_123" \
  -H "auth_token: t_abc" \
  -H "org_name: Acme Corp" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [ { "role": "user", "content": "What can you help me with?" } ],
    "conversationId": "conv-123"
  }'

Note

Header keys are normalized to lowercase. Define them as lowercase in your schema and reference them as lowercase in templates.

Configuring headers

Define a schema for your headers and configure how it's used in your agent. You must include the headers schema in your context config.

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


// Define schema for expected headers (use lowercase keys)
const personalAgentHeaders = headers({
  schema: z.object({
    user_id: z.string(),
    auth_token: z.string(),
    org_name: z.string().optional()
  });
});

// Create a context fetcher that uses header values with type-safe templating
const userFetcher = fetchDefinition({
  id: "user-info",
  name: "User Information",
  trigger: "initialization",
  fetchConfig: {
    url: `https://api.example.com/users/${personalAgentHeaders.toTemplate('user_id')}`,
    method: "GET",
    headers: {
      Authorization: `Bearer ${personalAgentHeaders.toTemplate('auth_token')}`,
    },
    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(),
    }),
  }),
  defaultValue: "Guest User"
});

// Configure context for your agent
const personalAgentContext = contextConfig({
  headers: personalAgentHeaders,
  contextVariables: {
    user: userFetcher,
  },
});

// Create a Sub Agent that uses context variables
const personalAssistant = subAgent({
  id: "personal-assistant",
  name: "Personal Assistant",
  description: "Personalized AI assistant",
  prompt: `You are a helpful assistant for ${personalAgentContext.toTemplate('user.name')} from ${personalAgentHeaders.toTemplate('org_name')}.

  User ID: ${personalAgentHeaders.toTemplate('user_id')}

  Provide personalized assistance based on their context.`,
});

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

How it works

Validation: Headers are validated against your configured schema when a request arrives

Caching: Validated context is cached per conversation for reuse across multiple interactions

Reuse: Subsequent requests with the same conversationId automatically use cached context values

Updates: Provide new header values to update the context for an ongoing conversation

Tip

Context values persist across conversation turns. To update them, send new header values with the same conversation ID.

Using headers in your agents

Header values can be used in your agent prompts and fetch definitions using JSONPath template syntax {{headers.field_name}}. You can use the headers schema's toTemplate() method for type-safe templating with autocomplete and validation.

In Context Fetchers

Use header values to fetch dynamic data from external APIs:

// Define schema for expected headers (use lowercase keys)
const personalAgentHeaders = headers({
  schema: z.object({
    user_id: z.string(),
    auth_token: z.string(),
    org_name: z.string().optional()
  });
});


const userDataFetcher = fetchDefinition({
  id: "user-data",
  name: "User Data",
  fetchConfig: {
    url: `https://api.example.com/users/${personalAgentHeaders.toTemplate('user_id')}/profile`,
    headers: {
      Authorization: `Bearer ${personalAgentHeaders.toTemplate('auth_token')}`,
      "X-Organization": personalAgentHeaders.toTemplate('org_name')
    },
    body: {
      includePreferences: true,
      userId: personalAgentHeaders.toTemplate('user_id')
    }
  },
  responseSchema: z.object({
    name: z.string(),
    preferences: z.record(z.unknown())
  })
});

// Configure context for your Agent
// You must include the headers schema and fetchers in your context config.
const personalAgentContext = contextConfig({
  headers: personalAgentHeaders,
  contextVariables: {
    user: userFetcher,
  },
});

In Agent Prompts

Reference context directly in agent prompts for personalization using the context config's template method:

// Create context config with both headers and fetchers
const userContext = contextConfig({
  headers: requestHeaders,
  contextVariables: {
    userName: userDataFetcher,
  },
});

const assistantAgent = subAgent({
  prompt: `You are an assistant for ${userContext.toTemplate('userName')} from ${requestHeaders.toTemplate('org_name')}.

  User context:
  - ID: ${requestHeaders.toTemplate('user_id')}
  - Organization: ${requestHeaders.toTemplate('org_name')}

  Provide help tailored to their organization's needs.`
});

In External Tools

Configure external agents or MCP servers with dynamic headers using the headers schema:

// Define schema for expected headers (use lowercase keys)
const personalAgentHeaders = headers({
  schema: z.object({
    user_id: z.string(),
    auth_token: z.string(),
    org_name: z.string().optional()
  });
});

// Configure external agent
const externalAgent = externalAgent({
  id: "external-service",
  baseUrl: "https://external.api.com",
  headers: {
    Authorization: `Bearer ${personalAgentHeaders.toTemplate('auth_token')}`,
    "X-User-Context": personalAgentHeaders.toTemplate('user_id'),
    "X-Org": personalAgentHeaders.toTemplate('org_name')
  }
});

// Configure context for your Agent with your headers schema.
const personalAgentContext = contextConfig({
  headers: personalAgentHeaders,
});

Verified claims from authenticated sessions

When using authenticated chat sessions, non-standard claims from the customer-signed JWT are automatically extracted and made available as verified claims in the conversation context. Unlike headers and userProperties, verified claims are cryptographically verified and cannot be modified by the client.

Source	Trust level	Mutability
Headers	Validated against schema	Updated per-request
User properties	Unverified, client-provided	Client can modify freely
Verified claims	Cryptographically signed via JWT	Immutable for the session

Verified claims are available at metadata.verifiedClaims in the execution context and are persisted in conversation metadata. Any non-standard claims in the JWT (e.g., email, org_id, role, or custom claims) are extracted automatically. Standard JWT claims (iss, aud, exp, iat, nbf, jti) are excluded.

Note

Verified claims are limited to 1KB. Tokens with claims exceeding this limit are rejected.

Using verified claims in prompts

You can reference verified claims to personalize agent behavior with trusted identity data:

const supportAgent = subAgent({
  id: "support-agent",
  name: "Support Agent",
  description: "Authenticated support assistant",
  prompt: `You are a support assistant.

  The user has been authenticated. Use their verified identity
  to provide personalized, account-specific assistance.

  Verified claims from their session are available in the conversation context
  and can be trusted for authorization decisions.`,
});

Tip

Use verified claims for authorization and identity decisions. Use headers and userProperties for non-sensitive personalization like display preferences.

For setup instructions, see Authenticated chat sessions.

Best practices

Use lowercase keys: Always define schema properties in lowercase and reference them as lowercase in templates
Validate early: Test your schema configuration with sample headers before deploying
Cache wisely: Remember that context persists per conversation - design accordingly
Secure sensitive data: For long-lived secrets, use the Credentials system instead of headers
Keep it minimal: Only include context values that are actually needed by your agents

Common use cases

Multi-tenant applications

Pass tenant-specific configuration to customize agent behavior per customer:

// Headers
"tenant_id: acme-corp"
"tenant_plan: enterprise"
"tenant_features: advanced-analytics,custom-branding"

User authentication

Provide user identity and session information for personalized interactions:

// Headers
"user_id: user_123"
"user_role: admin"
"session_token: sk_live_..."

API gateway integration

Forward headers from your API gateway for consistent authentication:

// Headers
"x-api-key: your-api-key"
"x-request-id: req_abc123"
"x-client-version: 2.0.0"

When using the Inkeep chat components, the following headers are automatically sent with each request:

Header	Description	Example Value
`x-inkeep-client-timestamp`	The client's current timestamp in ISO 8601 format	`2025-01-30T18:15:00.000Z`
`x-inkeep-client-timezone`	The client's timezone identifier	`America/New_York`

These headers are useful for providing time-aware responses:

const timeAwareHeaders = headers({
  schema: z.object({
    'x-inkeep-client-timestamp': z.string().optional(),
    'x-inkeep-client-timezone': z.string().optional(),
  }),
});

const timeAwareContext = contextConfig({
  headers: timeAwareHeaders,
});

const assistantAgent = subAgent({
  prompt: `You are a helpful assistant.

  The user's current time is: ${timeAwareHeaders.toTemplate('x-inkeep-client-timestamp')}
  The user's timezone is: ${timeAwareHeaders.toTemplate('x-inkeep-client-timezone')}

  Use this information to provide time-relevant responses when appropriate.`
});

Troubleshooting

Invalid headers errors

If you receive a 400 error about invalid headers:

Verify your schema matches the headers you're sending
Ensure all header keys are lowercase
Check that required fields are present
Validate the data types match your schema

Context not persisting

If context values aren't available in subsequent requests:

Ensure you're using the same conversationId across requests
Verify headers are being sent correctly
Check that your context config is properly attached to the Agent

Context Fetchers - Learn about fetching and caching external data
External Agents - Configure external agent integrations
Credentials - Manage secure credentials for your Agents
App Credentials - Authentication for chat components, including authenticated sessions