feat(core): expose request headers to dynamic agents (#1218)

Author: omeraplak

.changeset/expose-request-headers-dynamic-agents.md

@@ -0,0 +1,43 @@
+---
+"@voltagent/core": patch
+"@voltagent/server-core": patch
+"@voltagent/server-hono": patch
+"@voltagent/server-elysia": patch
+"@voltagent/serverless-hono": patch
+---
+
+feat(agent): expose request headers to dynamic agent configuration
+
+Dynamic `instructions`, `model`, and `tools` functions now receive a `headers` map in
+`DynamicValueOptions` when an agent is called through the built-in HTTP endpoints. This makes it
+possible to configure tenant-aware models and request-scoped tools from headers such as
+`authorization`, `x-tenant-id`, or `x-user-id` without manually copying them into
+`options.context`.
+
+Header names are normalized to lowercase:
+
+```ts
+const agent = new Agent({
+  name: "Tenant Agent",
+  instructions: "You are a tenant-aware assistant.",
+  model: ({ headers }) => {
+    return headers?.["x-tenant-id"] === "enterprise" ? "openai/gpt-4o" : "openai/gpt-4o-mini";
+  },
+  tools: ({ headers }) => {
+    return headers?.authorization ? [createTenantTool(headers.authorization)] : [];
+  },
+});
+```
+
+For direct in-process calls, pass `requestHeaders`:
+
+```ts
+await agent.generateText("Hello", {
+  requestHeaders: {
+    authorization: "Bearer token",
+    "x-tenant-id": "tenant-1",
+  },
+});
+```
+
+Fixes #1201

packages/core/src/agent/agent.spec-d.ts

@@ -227,6 +227,7 @@ describe("Agent Type System", () => {
       // Dynamic model function
       const dynamicModelFn: DynamicValue<AgentModelReference> = async (options) => {
         expectTypeOf(options.context).toMatchTypeOf<Map<string | symbol, unknown>>();
+        expectTypeOf(options.headers).toMatchTypeOf<Record<string, string> | undefined>();
         return mockModel;
       };
 
@@ -257,6 +258,7 @@ describe("Agent Type System", () => {
       // Dynamic value function
       const dynamicInstructions: InstructionsDynamicValue = async (options) => {
         expectTypeOf(options).toMatchTypeOf<{ context?: UserContext }>();
+        expectTypeOf(options.headers).toMatchTypeOf<Record<string, string> | undefined>();
         return "Dynamic instructions";
       };
       expectTypeOf(dynamicInstructions).toMatchTypeOf<InstructionsDynamicValue>();
@@ -277,6 +279,7 @@ describe("Agent Type System", () => {
       // Dynamic model
       const dynamicModel: ModelDynamicValue<ModelRouterModelId> = async (options) => {
         expectTypeOf(options).toMatchTypeOf<{ context?: UserContext }>();
+        expectTypeOf(options.headers).toMatchTypeOf<Record<string, string> | undefined>();
         return "openai/gpt-4o-mini";
       };
       expectTypeOf(dynamicModel).toMatchTypeOf<ModelDynamicValue<ModelRouterModelId>>();
@@ -311,6 +314,7 @@ describe("Agent Type System", () => {
       // Dynamic tools
       const dynamicTools: ToolsDynamicValue = async (options) => {
         expectTypeOf(options).toMatchTypeOf<{ context?: UserContext }>();
+        expectTypeOf(options.headers).toMatchTypeOf<Record<string, string> | undefined>();
         return [tool];
       };
       expectTypeOf(dynamicTools).toMatchTypeOf<ToolsDynamicValue>();
@@ -430,6 +434,10 @@ describe("Agent Type System", () => {
         maxSteps: 5,
         signal: new AbortSignal(),
         context: new Map(),
+        requestHeaders: {
+          authorization: "Bearer token",
+          "x-tenant-id": "tenant-1",
+        },
       };
 
       const legacyOptions: PublicGenerateOptions = {

packages/core/src/agent/agent.spec.ts

@@ -4672,6 +4672,55 @@ Use pandas and summarize findings.`.split("\n"),
       expect(systemMessage.content).toContain("Use markdown to format your answers");
     });
 
+    it("should expose request headers to dynamic model, tools, and instructions", async () => {
+      const requestHeaders = {
+        authorization: "Bearer test-token",
+        "x-tenant-id": "tenant-1",
+      };
+      const dynamicInstructions = vi.fn().mockResolvedValue("Dynamic content");
+      const dynamicModel = vi.fn().mockResolvedValue(mockModel as any);
+      const dynamicTools = vi.fn().mockResolvedValue([]);
+
+      const agent = new Agent({
+        name: "TestAgent",
+        instructions: dynamicInstructions,
+        model: dynamicModel,
+        tools: dynamicTools,
+      });
+
+      vi.mocked(ai.generateText).mockResolvedValue({
+        text: "Response",
+        content: [{ type: "text", text: "Response" }],
+        reasoning: [],
+        files: [],
+        sources: [],
+        toolCalls: [],
+        toolResults: [],
+        finishReason: "stop",
+        usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+        warnings: [],
+        request: {},
+        response: {
+          id: "test",
+          modelId: "test-model",
+          timestamp: new Date(),
+          messages: [],
+        },
+        steps: [],
+      } as any);
+
+      await agent.generateText("Hello", {
+        requestHeaders,
+      });
+
+      expect(dynamicInstructions.mock.calls[0][0].headers).toEqual(requestHeaders);
+      expect(dynamicModel.mock.calls[0][0].headers).toEqual(requestHeaders);
+      expect(dynamicTools.mock.calls[0][0].headers).toEqual(requestHeaders);
+
+      const callArgs = vi.mocked(ai.generateText).mock.calls[0][0] as Record<string, unknown>;
+      expect(callArgs.requestHeaders).toBeUndefined();
+    });
+
     it("should add retriever context correctly through enrichInstructions", async () => {
       // Create mock retriever
       const mockRetriever = {

packages/core/src/agent/agent.ts

@@ -845,6 +845,14 @@ export interface BaseGenerationOptions<TProviderOptions extends ProviderOptions
    */
   conversationId?: string;
   context?: ContextInput;
+  /**
+   * HTTP request headers associated with this call.
+   *
+   * Server adapters populate this from the incoming request and expose it to
+   * dynamic `model`, `instructions`, and `tools` callbacks as `headers`.
+   * This is separate from AI SDK/provider `headers`.
+   */
+  requestHeaders?: Record<string, string>;
   elicitation?: (request: unknown) => Promise<unknown>;
 
   // Parent tracking
@@ -1259,6 +1267,7 @@ export class Agent {
               conversationId,
               memory: _memory,
               context, // Explicitly exclude to prevent collision with AI SDK's future 'context' field
+              requestHeaders: _requestHeaders,
               parentAgentId,
               parentOperationContext,
               hooks,
@@ -1877,6 +1886,7 @@ export class Agent {
           conversationId,
           memory: _memory,
           context, // Explicitly exclude to prevent collision with AI SDK's future 'context' field
+          requestHeaders: _requestHeaders,
           parentAgentId,
           parentOperationContext,
           hooks,
@@ -2780,6 +2790,7 @@ export class Agent {
               conversationId,
               memory: _memory,
               context, // Explicitly exclude to prevent collision with AI SDK's future 'context' field
+              requestHeaders: _requestHeaders,
               parentAgentId,
               parentOperationContext,
               hooks,
@@ -3153,6 +3164,7 @@ export class Agent {
           conversationId,
           memory: _memory,
           context, // Explicitly exclude to prevent collision with AI SDK's future 'context' field
+          requestHeaders: _requestHeaders,
           parentAgentId,
           parentOperationContext,
           hooks,
@@ -4058,6 +4070,7 @@ export class Agent {
     return {
       operationId,
       context,
+      requestHeaders: options?.requestHeaders ?? options?.parentOperationContext?.requestHeaders,
       systemContext,
       isActive: true,
       logger,
@@ -5080,6 +5093,7 @@ export class Agent {
 
     const dynamicValueOptions: DynamicValueOptions = {
       context: oc.context,
+      headers: oc.requestHeaders,
       prompts: promptHelper,
     };
 
@@ -5541,10 +5555,12 @@ export class Agent {
         (this.prompts
           ? {
               context: oc.context,
+              headers: oc.requestHeaders,
               prompts: this.prompts,
             }
           : {
               context: oc.context,
+              headers: oc.requestHeaders,
               prompts: {
                 getPrompt: async () => ({ type: "text" as const, text: "" }),
               },

packages/core/src/agent/types.ts

@@ -1078,6 +1078,9 @@ export interface CommonGenerateOptions {
   // Optional user-defined context to be passed from a parent operation
   context?: UserContext;
 
+  // HTTP request headers associated with this generation call, when available.
+  requestHeaders?: Record<string, string>;
+
   // Optional hooks to be included only during the operation call and not persisted in the agent
   hooks?: AgentHooks;
 }
@@ -1306,6 +1309,9 @@ export type OperationContext = {
   /** User-managed context map for this operation */
   readonly context: Map<string | symbol, unknown>;
 
+  /** HTTP request headers associated with this operation, when available */
+  readonly requestHeaders?: Record<string, string>;
+
   /** System-managed context map for internal operation tracking */
   readonly systemContext: Map<string | symbol, unknown>;
 

packages/core/src/voltops/types.ts

@@ -56,6 +56,8 @@ export type PromptHelper = {
 export interface DynamicValueOptions {
   /** User context map */
   context: Map<string | symbol, unknown>;
+  /** HTTP request headers for server-triggered agent calls, when available */
+  headers?: Record<string, string>;
   /** Prompt helper (available when VoltOpsClient is configured) */
   prompts: PromptHelper;
 }

packages/server-core/src/handlers/agent.handlers.spec.ts

@@ -1,5 +1,6 @@
 import { ToolDeniedError } from "@voltagent/core";
 import { describe, expect, it, vi } from "vitest";
+import { processAgentOptions } from "../utils/options";
 import { handleChatStream, handleGenerateText } from "./agent.handlers";
 
 describe("server-core: agent.handlers ClientHTTPError mapping", () => {
@@ -56,6 +57,71 @@ describe("server-core: agent.handlers ClientHTTPError mapping", () => {
       error: "Model timeout",
     });
   });
+
+  it("handleGenerateText should pass request headers into agent options", async () => {
+    const logger = { error: vi.fn() } as any;
+
+    const mockAgent = {
+      generateText: vi.fn(async () => ({
+        text: "ok",
+        usage: undefined,
+        finishReason: "stop",
+        toolCalls: [],
+        toolResults: [],
+        feedback: null,
+      })),
+    } as any;
+
+    const deps = {
+      agentRegistry: {
+        getAgent: vi.fn(() => mockAgent),
+      },
+    } as any;
+
+    const headers = new Headers({
+      Authorization: "Bearer test-token",
+      "X-Tenant-ID": "tenant-1",
+    });
+
+    const res = await handleGenerateText(
+      "agent-1",
+      { input: "hi" },
+      deps,
+      logger,
+      undefined,
+      headers,
+    );
+
+    expect(res.success).toBe(true);
+    expect(mockAgent.generateText).toHaveBeenCalledWith(
+      "hi",
+      expect.objectContaining({
+        requestHeaders: {
+          authorization: "Bearer test-token",
+          "x-tenant-id": "tenant-1",
+        },
+      }),
+    );
+  });
+});
+
+describe("server-core: processAgentOptions", () => {
+  it("processAgentOptions should lowercase Headers entries", () => {
+    const headers = new Headers();
+    vi.spyOn(headers, "entries").mockReturnValue(
+      [
+        ["Authorization", "Bearer test-token"],
+        ["X-Tenant-ID", "tenant-1"],
+      ][Symbol.iterator]() as HeadersIterator<[string, string]>,
+    );
+
+    const options = processAgentOptions({ options: {} }, undefined, headers);
+
+    expect(options.requestHeaders).toEqual({
+      authorization: "Bearer test-token",
+      "x-tenant-id": "tenant-1",
+    });
+  });
 });
 
 describe("server-core: agent.handlers resumable memory envelope", () => {