Task Agent

What is a Task Agent?

A Task Agent is a specialized type of agent designed for structured input processing and prompt templating. Unlike Tool Agents that process conversational messages, Task Agents accept structured inputs that are validated against a JSON schema and used to render template variables in the system prompt.

Task Agents are perfect for scenarios where you need:

• Consistent input validation - Ensure all required fields are provided
• Template-based prompts - Dynamic prompts based on structured data
• Structured workflows - Predefined input formats for specific use cases
• Data processing tasks - Transform structured inputs into LLM responses

Key Features

• Input Schema Validation: All inputs are validated against a predefined JSON schema
• Template Variable Rendering: System prompts use {{variable}} syntax for dynamic content
• Structured Processing: Accepts structured data instead of conversational messages
• Error Handling: Comprehensive validation with clear error message

Task Agent vs Tool Agent

Feature	Task Agent	Tool Agent
Input Type	Structured JSON data	Conversational messages
Schema Validation	Required inputSchema	Optional
System Prompt	Template variables required	Static or dynamic
Use Case	Data processing, structured workflows	Conversational AI, tool usage
Invocation Endpoints	/invoke-task, /invoke-task-stream	/invoke, /invoke-stream

Configuration Requirements

Essential Parameters

Parameter	Description	Required	Example
agentType	Must be "task"	Yes	"task"
llmModelId	Bedrock model identifier	Yes	anthropic.claude-haiku-4-5-20251001-v1:0
systemPrompt	Template with {{variables}}	Yes	"Evaluate claim {{claim_id}} for policy {{policy_number}}"
inputSchema	JSON schema for input validation	Yes	See examples below
inferenceConfig	LLM parameters	No	{"maxTokens": 4000}
guardrails	List of guardrails names	No	["HAIP-Profanity", "HAIP-Insults-High"]

Input Schema Requirements

The inputSchema must be a valid JSON schema with:

• type: "object" (required)
• properties object defining available fields
• Property names must exactly match template variables in systemPrompt

System Prompt Requirements

The systemPrompt must contain template variables using {{variable}} syntax:

• Variables must be enclosed in double curly braces: {{variable_name}}
• Variable names must exactly match properties in inputSchema
• All schema properties must be used in the template
• No extra variables allowed in the template

Configuration Examples

Basic Task Agent

{
    "name": "document-classifier",
    "displayName": "Document Classifier",
    "description": "Classifies documents based on content and metadata",
    "agentType": "task",
    "config": {
        "llmModelId": "amazon.nova-micro-v1:0",
        "systemPrompt": "Classify the document titled '{{title}}' with content: {{content}}. Provide a category and confidence score.",
        "inputSchema": {
            "type": "object",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "Document title"
                },
                "content": {
                    "type": "string",
                    "description": "Document content to classify"
                }
            },
            "required": ["title", "content"]
        },
        "tools": [
            {
                "toolType": "structured_output",
                "name": "structured_output",
                "description": "Extracts classification results from the document",
                "outputSchema": {
                    "type": "object",
                    "properties": {
                        "category": { "type": "string", "description": "Predicted category of the document" },
                        "confidence": { "type": "number", "description": "Confidence score (0-1)" }
                    },
                    "required": ["category", "confidence"]
                }
            }
        ],
        "inferenceConfig": {
            "maxTokens": 1000,
            "temperature": 0.1
        },
        "guardrails": ["HAIP-Profanity", "HAIP-Insults-High"]
    }
}

Insurance Claim Evaluator

{
    "name": "insurance-claim-evaluator",
    "displayName": "Insurance Claim Evaluator",
    "description": "Evaluates insurance claims for approval or denial",
    "agentType": "task",
    "config": {
        "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
        "systemPrompt": "Evaluate insurance claim {{claim_id}} for policy {{policy_number}}. Claim description: {{claim_description}}. Provide approval recommendation with reasoning.",
        "inputSchema": {
            "type": "object",
            "properties": {
                "claim_id": {
                    "type": "string",
                    "description": "Unique claim identifier"
                },
                "policy_number": {
                    "type": "string",
                    "description": "Insurance policy number"
                },
                "claim_description": {
                    "type": "string",
                    "description": "Detailed description of the claim"
                }
            },
            "required": ["claim_id", "policy_number", "claim_description"]
        },
        "tools": [
            {
                "toolType": "structured_output",
                "name": "structured_output",
                "description": "Extracts the approval recommendation and reasoning for the insurance claim",
                "outputSchema": {
                    "type": "object",
                    "properties": {
                        "approved": { "type": "boolean", "description": "Whether the claim is approved (true) or denied (false)" },
                        "reasoning": { "type": "string", "description": "Explanation for the approval or denial decision" }
                    },
                    "required": ["approved", "reasoning"]
                }
            }
        ],
        "inferenceConfig": {
            "maxTokens": 2000,
            "temperature": 0.0
        },
        "guardrails": ["HAIP-Profanity", "HAIP-Insults-High"]
    }
}

Data Analysis Task

{
    "name": "sales-data-analyzer",
    "displayName": "Sales Data Analyzer",
    "description": "Analyzes sales data and provides insights",
    "agentType": "task",
    "config": {
        "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
        "systemPrompt": "Analyze sales data for {{period}} with revenue of ${{revenue}} and {{customer_count}} customers. Identify trends and provide recommendations.",
        "inputSchema": {
            "type": "object",
            "properties": {
                "period": {
                    "type": "string",
                    "description": "Time period for analysis (e.g., 'Q1 2024')"
                },
                "revenue": {
                    "type": "number",
                    "description": "Total revenue for the period"
                },
                "customer_count": {
                    "type": "integer",
                    "description": "Number of customers"
                }
            },
            "required": ["period", "revenue", "customer_count"]
        },
        "tools": [
            {
                "toolType": "structured_output",
                "name": "structured_output",
                "description": "Extracts key insights and recommendations from the sales data analysis",
                "outputSchema": {
                    "type": "object",
                    "properties": {
                        "trends": {
                            "type": "string",
                            "description": "Summary of identified sales trends"
                        },
                        "recommendations": {
                            "type": "string",
                            "description": "Actionable recommendations based on the analysis"
                        },
                        "insight_score": {
                            "type": "number",
                            "description": "Confidence score (0-1) for the insights provided"
                        }
                    },
                    "required": ["trends", "recommendations", "insight_score"]
                }
            }
        ],
        "inferenceConfig": {
            "maxTokens": 3000,
            "temperature": 0.01
        },        
        "guardrails": ["HAIP-Profanity", "HAIP-Insults-High"]
    }
}

Using Task Agents

Creating a Task Agent

Create a Task Agent using the standard agent creation endpoint:

POST /v1/agents

Example Request:

{
    "name": "my-task-agent",
    "displayName": "My Task Agent",
    "description": "Processes structured data",
    "agentType": "task",
    "notes": "Initial version",
    "config": {
        "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
        "systemPrompt": "Process data for {{field1}} and {{field2}}",
        "inputSchema": {
            "type": "object",
            "properties": {
                "field1": {"type": "string"},
                "field2": {"type": "string"}
            },
            "required": ["field1", "field2"]
        }
    }
}

Invoking a Task Agent

Task Agents have dedicated endpoints separate from regular conversational agents:

Standard Invocation

POST /v1/agents/{agent_id}/versions/{version_id}/invoke-task

Example Request:

{
    "inputs": {
        "title": "Financial Report Q3",
        "content": "Revenue increased by 15% compared to last quarter..."
    }
}

Example Response:

{
    "output": [
        {
            "role": "assistant",
            "type": "message",
            "content": [
                {
                    "type": "output_text",
                    "text": "Based on the document titled 'Financial Report Q3', I can classify this as a Financial/Quarterly Report with high confidence (95%). The content indicates positive growth trends..."
                }
            ]
        }
    ]
}

Streaming Invocation

For real-time streaming responses:

POST /v1/agents/{agent_id}/versions/{version_id}/invoke-task-stream

Example Request:

{
    "inputs": {
        "title": "Financial Report Q3",
        "content": "Revenue increased by 15% compared to last quarter..."
    }
}

Streaming Response: Returns Server-Sent Events (SSE) with incremental response chunks for real-time processing.

Including Messages

In addition to structured inputs, Task Agents can accept an optional messages array like Tool Agents. This is useful when you need to provide rich content alongside your template variables — for example, additional text context or file uploads via file_analysis.

The messages field follows the same format as Tool Agent messages and is included alongside the rendered system prompt.

Additional Text Context

{
    "inputs": {
        "claim_id": "CLM-2024-001",
        "policy_number": "POL-12345"
    },
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Additional context: The claimant reported the incident on January 15th. Police report #PR-9876 is attached to the case file."
                }
            ]
        }
    ]
}

File Upload with Code Execution

Task Agents with an analytics tool can accept file_analysis objects in messages to process uploaded files. This combines structured inputs with file-based data analysis.

Agent Configuration:

{
    "name": "sales-data-analyzer",
    "displayName": "Sales Data Analyzer",
    "description": "Analyzes uploaded sales data with configurable visualization",
    "agentType": "task",
    "config": {
        "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
        "systemPrompt": "Analyze the uploaded data file. Create a {{visualization_type}} chart showing the key trends. Include summary statistics.",
        "inputSchema": {
            "type": "object",
            "properties": {
                "visualization_type": {
                    "type": "string",
                    "description": "Type of chart to generate (e.g., bar, line, pie)"
                }
            },
            "required": ["visualization_type"]
        },
        "tools": [
            {
                "toolType": "analytics"
            }
        ],
        "inferenceConfig": {
            "maxTokens": 4000,
            "temperature": 0.1
        }
    }
}

Invocation with File Upload:

{
    "inputs": {
        "visualization_type": "bar"
    },
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "file_analysis",
                    "fileId": "12345678-1234-1234-1234-1234567890ab",
                    "fileName": "quarterly_sales.csv",
                    "mediaType": "text/csv"
                }
            ]
        }
    ]
}

Validation and Error Handling

Input Validation Errors

Task Agents perform comprehensive validation:

{
    "detail": "Task agent input validation failed: 'title' is a required property"
}

Template Variable Mismatches

If template variables don't match schema properties:

{
    "detail": "Template variables do not match input schema properties: Template variables {'claim_id'} not found in input schema; Input schema properties {'policy_id'} not used in template"
}

Agent Type Restrictions

Only Task agent types can use the task endpoint:

{
    "detail": "Task invocation is only supported for TASK agent types. Create a TASK agent with inputSchema and template variables in systemPrompt."
}

Best Practices

Schema Design

• Keep schemas focused: Design schemas for specific use cases
• Use clear property names: Make field names self-explanatory
• Include descriptions: Add helpful descriptions for each property
• Mark required fields: Only mark truly essential fields as required
• Use appropriate data types: Choose the right JSON schema types

Template Variables

• Match exactly: Template variable names must exactly match schema properties
• Use descriptive names: Choose meaningful variable names
• No extra variables: Don't include template variables not in the schema
• Use all properties: All schema properties should be used in the template

System Prompts

• Be specific: Provide clear instructions for the LLM
• Include context: Give enough context around the template variables
• Define output format: Specify the expected response format
• Add constraints: Include any business rules or constraints

Error Handling

• Validate inputs client-side: Pre-validate inputs when possible
• Handle validation errors: Provide clear error messages to users
• Test edge cases: Test with missing, invalid, and boundary values
• Use appropriate defaults: Provide sensible defaults in the schema

Limitations

• Schema constraints: Input schema must be type "object" with properties

Single-Turn Agent

Task agents are single-turn, structured input agents. The X-Session-ID header is ignored for Task agent invocations — session-based memory is not supported since each invocation is inherently one-shot. For multi-turn conversation support, use Tool or RAG agents instead.

Using Task Agents as Tools

Multi-Agent Orchestration

Task Agents can be used as tools within Tool Agents, enabling sophisticated multi-agent orchestration workflows.

Overview

Task Agents can be referenced as tools within Tool Agents using the task_agent tool type. This enables powerful multi-agent orchestration where a coordinator agent can dynamically discover and invoke specialized Task Agents based on user requirements.

Configuration

To use a Task Agent as a tool, reference it in a Tool/Task Agent's tool section configuration:

{
    "name": "multi-agent-orchestrator",
    "displayName": "Multi-Agent Orchestrator",
    "description": "Coordinates multiple specialized agents",
    "agentType": "tool",
    "config": {
        "tools": [
            {
                "toolType": "task_agent",
                "agentId": "uuid-of-document-classifier-task-agent",
                "agentVersion": "latest"
            },
            {
                "toolType": "task_agent", 
                "agentId": "uuid-of-data-analyzer-task-agent",
                "agentVersion": "latest"
            }
        ],
        "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
        "systemPrompt": "You are an orchestrator with access to specialized task agents. Use the available tools to help users with document classification and data analysis tasks.",
        "inferenceConfig": {"maxTokens": 1000, "temperature": 0.1}
    }
}

Multi-Agent Workflow Example

# User request to the orchestrator agent
POST /v1/agents/{agent_id}/versions/latest/invoke

{
    "messages": [
        {
            "role": "user", 
            "content": "I have a financial document with Q4 sales data showing $2.5M revenue. Please classify the document and analyze the sales performance."
        }
    ]
}

Use Cases

Business Process Automation

• Document Processing: Classify, extract, or summarize documents
• Data Validation: Validate business data against rules
• Report Generation: Generate reports from structured data
• Decision Support: Provide recommendations based on data

Multi-Agent Orchestration

• Complex Workflows: Chain multiple specialized agents for comprehensive processing
• Dynamic Routing: Route requests to appropriate agents based on content analysis
• Parallel Processing: Execute multiple Task Agents simultaneously for different aspects of a problem
• Composite Intelligence: Combine domain-specific expertise from multiple agents

Data Analysis

• Structured Analysis: Analyze datasets with consistent formats
• Performance Metrics: Evaluate KPIs and metrics
• Trend Analysis: Identify patterns in structured data
• Comparative Analysis: Compare different data points

Content Processing

• Content Classification: Categorize content based on criteria
• Quality Assessment: Evaluate content quality
• Content Generation: Generate content from templates
• Content Transformation: Convert between formats

Migration from Tool Agents

To convert a Tool Agent to a Task Agent:

1. Change agent type from "tool" to "task"
2. Add inputSchema defining your input structure
3. Update systemPrompt to use {{variable}} syntax
4. Update tools (Task Agents support tools like structured_output for structured responses)
5. Update invocation to use /invoke-task endpoint
6. Change input format from messages to structured inputs

Before (Tool Agent):

{
    "agentType": "tool",
    "config": {
        "systemPrompt": "You are a helpful assistant.",
        "tools": [...]
    }
}

After (Task Agent):

{
    "agentType": "task",
    "config": {
        "systemPrompt": "Process {{input_field}} and provide analysis.",
        "inputSchema": {
            "type": "object",
            "properties": {
                "input_field": {"type": "string"}
            }
        }
    }
}

Error Responses

When a request fails, the API returns a JSON error response in the following format:

{
    "status": 400,
    "error": "HTTPException",
    "message": "Description of what went wrong"
}

Common Errors

Status	Error	Description
400	Bad Request	Invalid agent configuration (e.g., inputSchema not type "object", template variable mismatch with schema properties), missing required input fields, or invoking a non-Task agent on the /invoke-task endpoint.
401	Unauthorized	Missing or expired access token. Re-authenticate to obtain a new token.
403	Forbidden	Insufficient permissions for the requested operation. Verify your IAM user group permissions.
404	Not Found	Agent ID or version does not exist. Use GET /v1/agents to verify available agents.

Future Enhancements

Planned improvements for Task Agents:

• Batch processing: Process multiple inputs in a single request
• Output validation: Validate LLM responses against output schemas
• Conditional logic: Support for conditional template rendering
• Enhanced error messages: More detailed validation feedback