make sure requiredToFetch context reflects that the context fetch was intentionally skipped rather than failed

Author: amikofalvy

agents-docs/content/docs/typescript-sdk/context-fetchers.mdx

@@ -130,6 +130,59 @@ transform: "user.profile.displayName"; // Result: "John Doe"
 transform: "items[0].name"; // Result: "First Item"
 ```
 
+## Optional Context Fetches
+
+Sometimes you want to fetch context data only when certain conditions are met—for example, when a specific header is provided. The `requiredToFetch` property lets you specify template variables that must resolve to non-empty values for the fetch to execute.
+
+If any required variable is missing or resolves to an empty string, the fetch is **skipped** (not treated as an error), and the `defaultValue` is used if provided.
+
+```typescript
+import { agent, subAgent } from "@inkeep/agents-sdk";
+import { contextConfig, fetchDefinition, headers } from "@inkeep/agents-core";
+import { z } from "zod";
+
+// Define headers schema - x-conversation-id is optional
+const chatHeaders = headers({
+  schema: z.object({
+    "x-tenant-id": z.string(),
+    "x-project-id": z.string(),
+    "x-conversation-id": z.string().optional(), // Optional header
+  })
+});
+
+// This fetch only runs when x-conversation-id header is provided
+const conversationHistoryFetcher = fetchDefinition({
+  id: "conversation-history",
+  name: "Conversation History",
+  trigger: "initialization",
+  fetchConfig: {
+    url: `https://api.example.com/conversations/${chatHeaders.toTemplate('x-conversation-id')}`,
+    method: "GET",
+    // Only fetch if x-conversation-id header is present and non-empty
+    requiredToFetch: [chatHeaders.toTemplate('x-conversation-id')],
+  },
+  responseSchema: z.object({
+    messages: z.array(z.object({
+      role: z.string(),
+      content: z.string(),
+    })),
+  }),
+  defaultValue: { messages: [] }, // Used when header is not provided
+});
+
+const chatContext = contextConfig({
+  headers: chatHeaders,
+  contextVariables: {
+    history: conversationHistoryFetcher,
+  },
+});
+```
+
+**When to use `requiredToFetch`:**
+- Fetching user-specific data when an optional user ID header is provided
+- Loading conversation history only when continuing an existing conversation
+- Conditional data loading based on optional API keys or authentication headers
+
 ## Best Practices
 
 1. **Use Appropriate Triggers**
@@ -142,6 +195,11 @@ transform: "items[0].name"; // Result: "First Item"
    - Always provide a `defaultValue`
    - Use appropriate response schemas
 
+3. **Use `requiredToFetch` for Optional Dependencies**
+
+   - Specify required template variables for conditional fetches
+   - Provide a `defaultValue` to handle skipped fetches gracefully
+
 ## Related documentation
 
 - [Headers](/typescript-sdk/headers) - Learn how to pass dynamic context to your agents via HTTP headers

agents-docs/content/docs/visual-builder/context-fetchers.mdx

@@ -53,6 +53,7 @@ Each key in the JSON should map to a fetch definition with the following propert
   - **`body`** (optional): Request body for POST/PUT/PATCH requests
   - **`transform`** (optional): JSONPath expression or JavaScript transform function to extract specific data from the response
   - **`timeout`** (optional): Request timeout in milliseconds (defaults to 10000)
+  - **`requiredToFetch`** (optional): Array of template variables that must resolve to non-empty values for the fetch to execute. If any variable is missing or empty, the fetch is skipped and `defaultValue` is used instead. Useful for optional fetches that depend on request headers.
 - **`responseSchema`** (optional): Valid JSON Schema object to validate the API response structure.
 - **`defaultValue`** (optional): Default value to use if the fetch fails or returns no data
 - **`credential`** (optional): Reference to stored credentials for authentication
@@ -91,6 +92,33 @@ Here is an example of a valid Context Variables JSON object:
 }
 ```
 
+### Optional Context Fetches
+
+Use `requiredToFetch` when you want a fetch to only execute when certain headers are provided. This is useful for optional data that enhances the agent experience but isn't required.
+
+Here's an example that fetches conversation history only when the `x-conversation-id` header is provided:
+
+```json
+{
+  "conversationHistory": {
+    "id": "conversation-history",
+    "name": "Conversation History",
+    "trigger": "initialization",
+    "fetchConfig": {
+      "url": "https://api.example.com/conversations/{{headers.x-conversation-id}}",
+      "method": "GET",
+      "requiredToFetch": ["{{headers.x-conversation-id}}"]
+    },
+    "defaultValue": { "messages": [] }
+  }
+}
+```
+
+When `x-conversation-id` is not provided in the request headers:
+- The fetch is **skipped** (not treated as an error)
+- The `defaultValue` is used instead
+- The agent continues normally with an empty message history
+
 ## Using Context Variables
 Once you have defined your context variables, you can use them in your agent prompts.
 1. Click on the agent you want to modify.