# Context Fetchers (/visual-builder/context-fetchers)

Learn how to use context fetchers to fetch data from external sources and make it available to your agents



## 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 {{user.name}} and you work for {{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

1. Go to the Agents tab in the left sidebar. Then click on the agent you want to configure.
2. On the right pane scroll down to the "Context Variables" section.
3. Add your context variables in JSON format.
4. Click on the "Save" button.

## Defining Context Variables

The keys that you define in the Context Variables JSON object are used to reference fetched data in your agent prompts.
Each key in the JSON should map to a fetch definition with the following properties:

* **`id`** (required): Unique identifier for the fetch definition
* **`name`** (optional): Human-readable name for the fetch definition
* **`trigger`** (required): When to execute the fetch:
  * `"initialization"`: Fetch only once when a conversation is started with the agent
  * `"invocation"`: Fetch every time a request is made to the agent
* **`fetchConfig`** (required): HTTP request configuration:
  * **`url`** (required): The API endpoint URL (supports template variables)
  * **`method`** (optional): HTTP method - `GET`, `POST`, `PUT`, `DELETE`, or `PATCH` (defaults to `GET`)
  * **`headers`** (optional): Object with string key-value pairs for HTTP headers
  * **`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

Here is an example of a valid Context Variables JSON object:

```json
{
  "timeInfo": {
    "id": "time-info",
    "name": "Time Information",
    "trigger": "invocation",
    "fetchConfig": {
      "url": "https://world-time-api3.p.rapidapi.com/timezone/US/Pacific",
      "method": "GET",
      "headers": {
        "x-rapidapi-key": "590c52974dmsh0da44377420ef4bp1c64ebjsnf8d55149e28d"
      }
    },
    "defaultValue": "Unable to fetch time information",
    "responseSchema": {
      "type": "object",
      "$schema": "http://json-schema.org/draft-07/schema#",
      "required": [
        "datetime"
      ],
      "properties": {
        "datetime": {
          "type": "string"
        },
        "timezone": {
          "type": "string"
        }
      }
    }
  }
}
```

### 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.
2. In the "Prompt" section, you can embed fetched data in the prompt using the key defined in the "Context Variables" section. Reference them using double curly braces `{{}}`.

Here is an example of an agent prompt using the context variable defined above:

```
You are a helpful assistant, the time in the US Pacific timezone is {{timeInfo.datetime}}.
```