Headers in Visual Builder

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

Configuring Headers

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 "Headers schema" section.
3. Enter the schema in JSON Schema format.
4. Click on the "Save" button.

Here is an example of a valid headers schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string"
    }
  },
  "required": [
    "user_id"
  ],
  "additionalProperties": {}
}

You can generate custom schemas using this JSON Schema generator.

Sending Custom Headers

1. On your agent page, click on the Try it button in the top right corner.
2. Click on the "Custom headers" button in the top right corner.
3. Enter the custom headers in JSON format.
4. Click on the "Apply" button.

Header Validation

When you enter custom headers in the playground, they are validated in real-time against the configured headers schema. If the headers are invalid or missing required fields, the chat input is disabled and an error message is displayed. You must fix validation errors before you can send messages.

Using Headers in Your Agent Prompts

1. Go to the Agents tab in the left sidebar. Then click on the agent you want to configure.
2. Either add a new agent or edit an existing agent by clicking on the agent you want to edit.
3. On the right pane scroll down to the "Prompt" section.
4. Use the double curly braces {{}} to reference the headers variables.

Here is an example of a valid prompt:

You are a helpful assistant for {{headers.user_id}}!.

Forwarding Headers to MCP Servers

You can forward header values to MCP servers using {{headers.*}} templates. These templates are resolved at runtime from the incoming request headers before each tool call.

1. Define the header in your agent's headers schema (use lowercase keys)
2. Register the MCP server — leave the Credential field blank if auth comes entirely from forwarded headers
3. Connect the MCP server to a Sub Agent, then click on the connection. In the Headers field, reference the schema properties:

{
  "Authorization": "Bearer {{headers.auth_token}}",
  "X-Tenant-Id": "{{headers.tenant_id}}"
}

See MCP Servers — Dynamic credential pass-through for more on authentication.