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 {{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)
• 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:

{
  "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"
        }
      }
    }
  }
}

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}}.