A comprehensive guide to understanding, implementing, and testing DataMap configurations in SignalWire AI Agents from the SWML (SignalWire Markup Language) perspective.
This guide provides comprehensive coverage of DataMap functionality within the SignalWire AI Agents framework, from basic concepts to advanced implementation patterns.
DataMap is a serverless function execution system within SignalWire AI Agents that enables seamless integration with external APIs without the need for custom webhook endpoints. Unlike traditional webhook-based SWAIG functions that require you to host and maintain HTTP endpoints, DataMap functions are executed entirely within the SignalWire infrastructure.
Key Characteristics:
DataMap Execution Flow:
Function Call → Template Expansion → HTTP Request → Response Processing → Output Generation
| Aspect | Traditional Webhooks | DataMap |
|---|---|---|
| Infrastructure | Requires hosted endpoints | Serverless execution |
| Configuration | Code-based handlers | Declarative JSON/YAML |
| HTTP Requests | Manual implementation | Built-in HTTP client |
| Error Handling | Custom error logic | Automatic failure detection |
| Template Expansion | Manual string formatting | Native template system |
| Scalability | Limited by hosting infrastructure | Auto-scaling serverless |
| Maintenance | Server maintenance required | Zero maintenance overhead |
| Development Speed | Slower (code + deploy) | Faster (configuration only) |
Traditional Webhook Example:
def search_knowledge(args, post_data):
# Custom HTTP request logic
response = requests.post("https://api.example.com/search",
json={"query": args["query"]})
# Custom error handling
if response.status_code != 200:
return {"error": "API request failed"}
# Custom response processing
data = response.json()
return {"response": f"Found: {data['results'][0]['text']}"}
DataMap Equivalent:
{
"function": "search_knowledge",
"data_map": {
"webhooks": [{
"url": "https://api.example.com/search",
"method": "POST",
"headers": {"Content-Type": "application/json"},
"params": {"query": "${args.query}"},
"output": {"response": "Found: ${array[0].text}"},
"error_keys": ["error"]
}],
"output": {"response": "Search service unavailable"}
}
}
DataMap integrates seamlessly with SWML (SignalWire Markup Language) through the AI verb's function calling mechanism. When an AI agent needs to call a function, SWML automatically detects whether it's a traditional webhook or DataMap function and routes the execution appropriately.
SWML AI Verb Integration:
<ai>
<prompt>You can search knowledge using the search_knowledge function</prompt>
<SWAIG>
<function name="search_knowledge" data_map="..." />
</SWAIG>
</ai>
Execution Context:
Integration Benefits:
Ideal Use Cases:
DataMap is Perfect For:
Consider Traditional Webhooks When:
Hybrid Approach: Many applications benefit from using both DataMap and traditional webhooks: - DataMap for simple API calls and data retrieval - Traditional webhooks for complex processing and business logic - DataMap for rapid prototyping, webhooks for production optimization
DataMap execution occurs entirely within the SignalWire infrastructure, following a deterministic processing pipeline implemented in the server-side mod_openai.c module. Understanding this flow is crucial for effective DataMap configuration.
Server-Side Architecture:
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ SWML Engine │────│ DataMap │────│ HTTP Client │
│ Function Call │ │ Processor │ │ Request │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
┌──────▼──────┐
│ Template │
│ Expansion │
│ Engine │
└─────────────┘
Processing Modules:
DataMap processing follows a strict sequential order that ensures deterministic execution and proper error handling:
1. Expression Processing (Optional)
{
"expressions": [
{
"pattern": "simple query",
"output": {"response": "This is a simple response for: ${args.query}"}
}
]
}
2. Webhook Sequential Processing
{
"webhooks": [
{"url": "https://primary-api.com/search", "...": "..."},
{"url": "https://fallback-api.com/search", "...": "..."}
]
}
3. Foreach Processing (Per Successful Webhook)
{
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 5,
"append": "Result: ${this.title}\n"
}
}
4. Output Generation
{
"output": {
"response": "Found results: ${formatted_results}",
"action": [{"SWML": {"version": "1.0.0", "...": "..."}}]
}
}
Processing Flow Diagram:
Function Call
│
▼
┌─────────────┐ Yes ┌──────────────┐
│ Expressions │────────────│ Return Early │
│ Match? │ │ Output │
└─────────────┘ └──────────────┘
│ No
▼
┌─────────────┐
│ Webhook 1 │────┐
│ Success? │ │
└─────────────┘ │
│ No │ Yes
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Webhook 2 │ │ Foreach │
│ Success? │ │ Processing │
└─────────────┘ └─────────────┘
│ No │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Fallback │ │ Webhook │
│ Output │ │ Output │
└─────────────┘ └─────────────┘
DataMap maintains a hierarchical context system that provides access to various data sources during template expansion:
Context Hierarchy:
┌────────────────────────────────────────┐
│ args │ ← Function arguments
│ ┌──────────────────────────────────┐ │
│ │ response │ │ ← HTTP response object
│ │ ┌────────────────────────────┐ │ │
│ │ │ this │ │ │ ← Current foreach item
│ │ │ │ │ │
│ │ └────────────────────────────┘ │ │
│ └──────────────────────────────────┘ │
└────────────────────────────────────────┘
Variable Sources:
args.*)Example: ${args.query}, ${args.filters}
HTTP Response Data (response.* or array.*)
Available after successful webhook execution
Global Data (global_data.*)
Conversation context
Foreach Context (this.*)
Context Evolution:
// Initial context
{
"args": {"query": "SignalWire", "count": 3}
}
// After webhook success (object response)
{
"args": {"query": "SignalWire", "count": 3},
"response": {"results": [...], "total": 25}
}
// After webhook success (array response)
{
"args": {"query": "SignalWire", "count": 3},
"array": [{"title": "...", "text": "..."}, ...]
}
// During foreach processing
{
"args": {"query": "SignalWire", "count": 3},
"array": [...],
"this": {"title": "Current Item", "text": "Current content"}
}
DataMap functions execute in a serverless environment with specific characteristics and limitations:
Execution Environment:
Execution Lifecycle:
1. Function Call Received
├── Parse DataMap configuration
├── Validate function arguments
└── Build initial context
2. Template Expansion
├── Expand webhook URLs and headers
├── Expand request body parameters
└── Prepare HTTP request configuration
3. HTTP Request Execution
├── Make HTTP request with timeouts
├── Handle network errors
└── Parse response (JSON/text)
4. Response Processing
├── Validate response structure
├── Check for error conditions
└── Add response to context
5. Foreach Processing (if configured)
├── Extract array data
├── Iterate with template expansion
└── Build concatenated result
6. Output Generation
├── Expand output templates
├── Format final response
└── Return to SWML engine
Performance Characteristics:
Resource Limits:
DataMap configurations follow a specific JSON schema that defines how external APIs are integrated and how responses are processed. Understanding this schema is essential for creating effective DataMap functions.
Complete DataMap Function Structure:
{
"function": "function_name",
"description": "Human-readable function description",
"parameters": {
"type": "object",
"properties": {
"param_name": {
"type": "string|number|boolean|array|object",
"description": "Parameter description",
"required": true,
"enum": ["optional", "enumeration", "values"]
}
},
"required": ["param1", "param2"]
},
"data_map": {
"expressions": [...],
"webhooks": [...],
"output": {...}
}
}
Core Schema Elements:
function: Unique function identifierdescription: Human-readable description for AI understandingparameters: JSON Schema for function arguments validation
DataMap Configuration (data_map)
expressions: Optional pattern-based early return logicwebhooks: Array of HTTP request configurationsoutput: Fallback output when all webhooks failMinimal DataMap Example:
{
"function": "simple_api_call",
"description": "Call external API",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query"}
},
"required": ["query"]
},
"data_map": {
"webhooks": [{
"url": "https://api.example.com/search",
"method": "GET",
"headers": {"Authorization": "Bearer ${global_data.api_token}"},
"params": {"q": "${args.query}"},
"output": {"response": "Result: ${response.data}"}
}]
}
}
Function-level configuration defines the interface between the AI agent and the DataMap execution engine:
Parameter Schema Definition:
{
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query text",
"minLength": 1,
"maxLength": 500
},
"category": {
"type": "string",
"description": "Content category filter",
"enum": ["docs", "api", "tutorials", "blog"],
"default": "docs"
},
"limit": {
"type": "integer",
"description": "Maximum number of results",
"minimum": 1,
"maximum": 20,
"default": 5
},
"filters": {
"type": "array",
"description": "Additional search filters",
"items": {"type": "string"},
"maxItems": 10
}
},
"required": ["query"],
"additionalProperties": false
}
}
Validation Features:
AI Integration Benefits:
{
"description": "Search the knowledge base for documentation and tutorials. Use specific keywords and categories for better results.",
"parameters": {
"properties": {
"query": {
"description": "Specific search terms - be precise for better results"
},
"category": {
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides"
}
}
}
}
DataMap configurations can include nested objects and complex data structures for advanced use cases:
Complex Webhook Configuration:
{
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
Nested Structure Benefits:
Parameter validation ensures data integrity and provides clear error messages when function calls fail validation:
Comprehensive Validation Example:
{
"parameters": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address to validate",
"pattern": "^[\\w\\.-]+@[\\w\\.-]+\\.[a-zA-Z]{2,}$",
"maxLength": 254
},
"user_preferences": {
"type": "object",
"description": "User preference settings",
"properties": {
"language": {
"type": "string",
"enum": ["en", "es", "fr", "de"],
"default": "en"
},
"notifications": {
"type": "object",
"properties": {
"email": {"type": "boolean", "default": true},
"sms": {"type": "boolean", "default": false},
"push": {"type": "boolean", "default": true}
}
}
}
},
"metadata": {
"type": "object",
"description": "Additional metadata",
"additionalProperties": true,
"maxProperties": 20
}
},
"required": ["email"],
"dependencies": {
"user_preferences": {
"properties": {
"email": {"const": true}
}
}
}
}
}
Validation Error Handling: When validation fails, the AI agent receives clear error messages:
{
"error": "Parameter validation failed",
"details": [
{
"parameter": "email",
"message": "Invalid email format",
"received": "invalid-email"
},
{
"parameter": "limit",
"message": "Value must be between 1 and 20",
"received": 50
}
]
}
Best Practices for Parameter Design:
Template expansion is a powerful feature in DataMap that allows you to dynamically construct URLs, headers, and request bodies based on function arguments and context variables. Understanding the syntax and usage is essential for effective DataMap configuration.
Template Syntax:
${expression}
Expression Types:
${args.query}, ${global_data.api_token}${function_name(args)}${if(condition, true_value, false_value)}${array[index].property}${object.property}${length(array)}, ${now()}DataMap supports a variety of variable types and sources that can be accessed during template expansion:
Variable Sources:
args.*)response.* or array.*)global_data.*)this.*)DataMap provides flexible access patterns for array and object data:
Array Access:
${array[index].property}
Object Access:
${object.property}
DataMap provides context-specific variables that can be used in template expansion:
Context-Specific Variables:
${args.query}, ${args.filters}${response.data}, ${array[0].text}${global_data.api_token}, ${global_data.prompt_variables}${this.title}, ${this.text}Simple Template Expansion:
{
"function": "simple_api_call",
"description": "Call external API",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query"}
},
"required": ["query"]
},
"data_map": {
"webhooks": [{
"url": "https://api.example.com/search",
"method": "GET",
"headers": {"Authorization": "Bearer ${global_data.api_token}"},
"params": {"q": "${args.query}"},
"output": {"response": "Result: ${response.data}"}
}]
}
}
Complex Template Expansion:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be configured with multiple webhooks to handle different scenarios and provide fallback mechanisms:
Webhook Configuration:
{
"webhooks": [
{"url": "https://primary-api.com/search", "...": "..."},
{"url": "https://fallback-api.com/search", "...": "..."}
]
}
DataMap functions can use various HTTP methods and headers to customize request configurations:
HTTP Method Examples:
HTTP Header Examples:
DataMap functions can construct request bodies dynamically based on function arguments and context variables:
Request Body Examples:
${args.query}${function_name(args)}${json_object}${formatted_string}DataMap functions can be configured to process multiple webhooks in sequence:
Sequential Webhook Configuration:
{
"webhooks": [
{"url": "https://primary-api.com/search", "...": "..."},
{"url": "https://fallback-api.com/search", "...": "..."}
]
}
DataMap functions can be configured to handle webhook failures and provide fallback mechanisms:
Webhook Failure Configuration:
{
"webhooks": [
{"url": "https://primary-api.com/search", "...": "..."},
{"url": "https://fallback-api.com/search", "...": "..."}
]
}
DataMap functions can return various types of response data:
Response Data Types:
DataMap functions can handle both array and object responses:
Array Response Example:
{
"response": {
"results": [{"title": "...", "text": "..."}, ...]
}
}
Object Response Example:
{
"response": {
"results": {"total": 25, "data": [...]}
}
}
DataMap functions can handle errors and provide clear error messages:
Error Handling Example:
{
"error": "API request failed",
"details": {
"status_code": 400,
"message": "Invalid request parameters"
}
}
DataMap functions can define custom error keys to provide more detailed error information:
Custom Error Keys Example:
{
"error": "API request failed",
"details": {
"status_code": 400,
"message": "Invalid request parameters"
}
}
DataMap functions can be configured to process array data:
Foreach Configuration Example:
{
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 5,
"append": "Result: ${this.title}\n"
}
}
DataMap functions can use various array data sources:
Array Data Sources:
${response.results}${global_data.array}${this.array}DataMap functions can expand template variables within foreach append templates:
Foreach Template Expansion Example:
{
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 5,
"append": "Result: ${this.title}\n"
}
}
DataMap functions can concatenate and format string data:
String Concatenation Example:
{
"response": {
"formatted_results": "Result: ${this.title}\n"
}
}
DataMap functions should be used cautiously when processing large arrays:
Foreach Limitations:
Best Practices:
DataMap functions can return output directly from webhook responses:
Webhook Output Example:
{
"response": {
"formatted_results": "Result: ${this.title}\n"
}
}
DataMap functions can provide a fallback output when all webhooks fail:
Fallback Output Example:
{
"output": {
"response": "Search service unavailable"
}
}
DataMap functions can return both response text and SWML actions:
Response vs Action Output Example:
{
"response": {
"formatted_results": "Result: ${this.title}\n"
},
"action": [{"SWML": {"version": "1.0.0", "...": "..."}}]
}
DataMap functions can generate SWML actions for call control:
SWML Action Generation Example:
{
"action": [{"SWML": {"version": "1.0.0", "...": "..."}}]
}
DataMap functions can be integrated with the skills system:
Skills System Integration Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be created based on skills:
Skill-Based DataMap Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be configured based on skill patterns:
Skill Configuration Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be used across multiple instances:
Multi-Instance Skill Usage Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be used for various API integration scenarios:
API Integration Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be used for knowledge base searches:
Knowledge Base Search Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be used for external service integrations:
External Service Integration Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be used for multi-step processing workflows:
Multi-Step Processing Workflow Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be developed and tested locally:
Local Development Setup Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be configured with environment variables:
Environment Variable Configuration Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be tested using command-line tools:
CLI Testing Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be debugged using various tools:
Debugging Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be configured with multiple webhooks to handle different scenarios and provide fallback mechanisms:
Multiple Webhook Configuration Example:
{
"webhooks": [
{"url": "https://primary-api.com/search", "...": "..."},
{"url": "https://fallback-api.com/search", "...": "..."}
]
}
DataMap functions can use complex template expressions to handle advanced scenarios:
Complex Template Expression Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can dynamically select API endpoints based on function arguments:
Dynamic API Endpoint Selection Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can transform response data based on function arguments:
Response Transformation Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can handle various HTTP error codes:
HTTP Error Handling Example:
{
"error": "API request failed",
"details": {
"status_code": 400,
"message": "Invalid request parameters"
}
}
DataMap functions can handle network timeouts and implement retry logic:
Network Timeout and Retry Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can implement graceful degradation strategies:
Graceful Degradation Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be monitored and observed using various tools:
Monitoring and Observability Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be configured with API keys:
API Key Management Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be configured with secure headers:
Secure Header Configuration Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions should validate and sanitize input data:
Input Validation Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions should consider rate limiting:
Rate Limiting Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can optimize request configurations:
Request Optimization Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can manage response sizes:
Response Size Management Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can implement caching strategies:
Caching Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions should consider execution time:
Execution Time Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can be migrated from traditional webhooks:
Migration Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can support legacy configurations:
Legacy Configuration Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions should be compatible with different versions:
Version Compatibility Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
DataMap functions can implement gradual migration strategies:
Gradual Migration Example:
{
"function": "search_knowledge",
"description": "Search the knowledge base for documentation and tutorials",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Specific search terms - be precise for better results"
},
"category": {
"type": "string",
"description": "Content type: 'docs' for documentation, 'api' for API references, 'tutorials' for guides",
"enum": ["docs", "api", "tutorials"],
"default": "docs"
}
},
"required": ["query"]
},
"data_map": {
"webhooks": [
{
"url": "https://api.primary.com/v2/search",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${global_data.primary_token}",
"X-Client-Version": "2.1",
"X-Request-ID": "${args.request_id}"
},
"params": {
"query": {
"text": "${args.query}",
"filters": {
"category": "${args.category}",
"date_range": {
"start": "${args.start_date}",
"end": "${args.end_date}"
},
"tags": "${args.tags}"
},
"options": {
"highlight": true,
"max_results": "${args.limit}",
"include_metadata": true
}
}
},
"foreach": {
"input_key": "results",
"output_key": "formatted_results",
"max": 10,
"append": "## ${this.title}\n${this.excerpt}\n**Score:** ${this.relevance_score}\n\n"
},
"output": {
"response": "Found ${response.total} results:\n\n${formatted_results}",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"set": {
"last_search_query": "${args.query}",
"last_search_results": "${response.total}",
"search_timestamp": "${response.timestamp}"
}
}
]
}
}
}
]
},
"error_keys": ["error", "message", "detail"]
}
],
"output": {
"response": "I'm sorry, the search service is currently unavailable. Please try again later."
}
}
}
This guide provides comprehensive coverage of DataMap functionality within the SignalWire AI Agents framework, from basic concepts to advanced implementation patterns.