Transforming Responses

Structure API responses for AI agent understanding

Why Transform Responses?

• Token efficiency: Summarizes to the few facts the model needs next, conserving context window and reducing distraction.
• Better tool use loops: Framing outputs as intentions (“Inventory insufficient; check warehouse B”) helps the LLM choose the right next tool call.
• Schema abstraction: Hides brittle field names and shapes, so prompts don’t break when an endpoint version changes.
• Consistent tone & policy: Centralized phrasing enforces brand, compliance language, and safety policies across all tool outputs.
• Disambiguation of codes & enums: status=3 → Payment declined because the card expired, which the model can reason about directly.

How Response Formatting Works

1. API Response Receipt

   Raw HTTP response received from your API endpoint

2. Template Processing

   Handlebars template processes the context to generate formatted output

3. Response Delivered to AI Agent

   Structured response delivered to AI agent for natural language understanding

Formatting Configuration System

Core Configuration Options

Main Template

{{! Primary template for formatting entire response }}
**User Profile Retrieved**

Name: {{response.data.body.full_name}}
Email: {{response.data.body.email}}
Status: {{response.data.body.account_status}}

{{#if response.data.body.preferences}}
**Preferences:**
{{#each response.data.body.preferences}}
- {{@key}}: {{this}}
{{/each}}
{{/if}}

Collection Template

{{! Template for individual items in collections }}
**Product:** {{name}}
Price: ${{price}}
Stock: {{inventory_count}} units
{{#if on_sale}}
🏷️ Sale Price: ${{sale_price}}
{{/if}}

Template Variables and Context

Available Variables

The formatting system provides a rich context for template processing:

Response Data

{{! Response object structure }}
{{response.data.body}}           <!-- Main response data -->
{{response.data.headers}}        <!-- Response headers -->
{{response.data.status}}         <!-- HTTP status code -->

{{! JSON stringify entire response }}
{{json response}}

{{! Access nested properties }}
{{response.data.body.user.name}}
{{response.data.body.results.0.title}}

Request Context

{{! Request information (when enabled) }}
{{request.data.parameters}}      <!-- All request parameters -->
{{request.data.payload}}         <!-- Request body data -->

{{! Specific parameter types }}
{{request.data.parameters.query}}   <!-- Query parameters -->
{{request.data.parameters.path}}    <!-- Path parameters -->
{{request.data.parameters.header}}  <!-- Header parameters -->

{{! JSON stringify request data }}
{{json request.data.parameters}}

Error Context

{{! Error template variables }}
{{message}}                      <!-- Error message -->
{{response.data.body.error}}     <!-- API error details -->
{{response.data.status}}         <!-- HTTP status code -->

{{! Check for specific error types }}
{{#if (eq response.data.status 404)}}
Resource not found
{{/if}}

Loop Variables

{{! Collection iteration }}
{{#each response.data.body}}
  {{@index}}     <!-- Current index (0-based) -->
  {{@key}}       <!-- Current key (for objects) -->
  {{this}}       <!-- Current item value -->
  {{@first}}     <!-- True for first item -->
  {{@last}}      <!-- True for last item -->
{{/each}}

Built-in Handlebars Helpers

json - JSON Stringification

Converts objects to JSON strings for structured output.

{{json response.data.body}}
{{json request.data.parameters}}

<!-- Formatted JSON with indentation -->
```json
{{json response.data.body}}

</Accordion>

<Accordion title="Comparison Helpers">
Logical comparison operations for conditional rendering.

```handlebars
{{! Equality checks }}
{{#if (eq status "active")}}User is active{{/if}}
{{#if (ne role "admin")}}Limited access{{/if}}

{{! Numeric comparisons }}
{{#if (gt price 100)}}Premium product{{/if}}
{{#if (lt stock 5)}}Low inventory warning{{/if}}

concat - String Concatenation

Combine multiple strings or values.

{{concat "User: " user.name " (" user.role ")"}}
{{concat "API Response from " request.data.parameters.path}}

base64 - Base64 Encoding

Encode strings to Base64 format.

{{base64 "sensitive data"}}
{{base64 response.data.body.token}}

AI-Generated Templates

Automatic Template Generation

AgentPass includes intelligent template generation powered by AI:

1. Analyze API Response

   AI examines the API response structure and data types

2. Understand Context

   AI considers the tool’s purpose and expected use cases

3. Generate Template

   AI creates an optimized Handlebars template for the response

4. Optimize for Agents

   Template is structured for optimal AI agent comprehension