Task Agent
Task Agents are currently experimental and subject to change. Features, APIs, and behaviors may evolve in future releases.
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 messages
- LLM Integration: Uses the same runtime endpoints as Tool Agents
Task Agent vs Tool Agent
Feature | Task Agent | Tool Agent |
---|---|---|
Input Type | Structured JSON data | Conversational messages |
Schema Validation | Required input_schema | Optional |
System Prompt | Template variables required | Static or dynamic |
Use Case | Data processing, structured workflows | Conversational AI, tool usage |
Invocation Endpoints | /invoke-agent-task , /invoke-agent-task-streaming | /invoke-agent , /invoke-agent-stream |
Configuration Requirements
Essential Parameters
Parameter | Description | Required | Example |
---|---|---|---|
agent_type | Must be "task" | Yes | "task" |
llm_model_id | Bedrock model identifier | Yes | amazon.nova-micro-v1:0 |
system_prompt | Template with {{variables}} | Yes | "Evaluate claim {{claim_id}} for policy {{policy_number}}" |
input_schema | JSON schema for input validation | Yes | See examples below |
inference_config | LLM parameters | No | {"max_tokens": 4000} |
Input Schema Requirements
The input_schema
must be a valid JSON schema with:
type: "object"
(required)properties
object defining available fields- Property names must exactly match template variables in
system_prompt
System Prompt Requirements
The system_prompt
must contain template variables using {{variable}}
syntax:
- Variables must be enclosed in double curly braces:
{{variable_name}}
- Variable names must exactly match properties in
input_schema
- All schema properties must be used in the template
- No extra variables allowed in the template
Configuration Examples
Basic Task Agent
{
"name": "Document Classifier",
"description": "Classifies documents based on content and metadata",
"agent_type": "task",
"config": {
"llm_model_id": "amazon.nova-micro-v1:0",
"system_prompt": "Classify the document titled '{{title}}' with content: {{content}}. Provide a category and confidence score.",
"input_schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Document title"
},
"content": {
"type": "string",
"description": "Document content to classify"
}
},
"required": ["title", "content"]
},
"tools": [
{
"tool_type": "structured_output",
"name": "structured_output",
"description": "Extracts classification results from the document",
"output_schema": {
"type": "object",
"properties": {
"category": { "type": "string", "description": "Predicted category of the document" },
"confidence": { "type": "number", "description": "Confidence score (0-1)" }
},
"required": ["category", "confidence"]
}
}
],
"inference_config": {
"max_tokens": 1000,
"temperature": 0.1
}
}
}
Insurance Claim Evaluator
{
"name": "Insurance Claim Evaluator",
"description": "Evaluates insurance claims for approval or denial",
"agent_type": "task",
"config": {
"llm_model_id": "amazon.nova-micro-v1:0",
"system_prompt": "Evaluate insurance claim {{claim_id}} for policy {{policy_number}}. Claim description: {{claim_description}}. Provide approval recommendation with reasoning.",
"input_schema": {
"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": [
{
"tool_type": "structured_output",
"name": "structured_output",
"description": "Extracts the approval recommendation and reasoning for the insurance claim",
"output_schema": {
"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"]
}
}
],
"inference_config": {
"max_tokens": 2000,
"temperature": 0.0
}
}
}
Data Analysis Task
{
"name": "Sales Data Analyzer",
"description": "Analyzes sales data and provides insights",
"agent_type": "task",
"config": {
"llm_model_id": "anthropic.claude-3-5-sonnet-20241022-v2:0",
"system_prompt": "Analyze sales data for {{period}} with revenue of ${{revenue}} and {{customer_count}} customers. Identify trends and provide recommendations.",
"input_schema": {
"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": [
{
"tool_type": "structured_output",
"name": "structured_output",
"description": "Extracts key insights and recommendations from the sales data analysis",
"output_schema": {
"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"]
}
}
],
"inference_config": {
"max_tokens": 3000,
"temperature": 0.01
}
}
}
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",
"description": "Processes structured data",
"agent_type": "task",
"notes": "Initial version",
"config": {
"llm_model_id": "amazon.nova-micro-v1:0",
"system_prompt": "Process data for {{field1}} and {{field2}}",
"input_schema": {
"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:
{
"response": {
"choices": [
{
"message": {
"role": "assistant",
"content": "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.
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 input_schema and template variables in system_prompt."
}
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
- Single message flow: Each invocation is independent (no conversation history)
- Schema constraints: Input schema must be type "object" with properties
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
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:
- Change agent type from
"tool"
to"task"
- Add input_schema defining your input structure
- Update system_prompt to use
{{variable}}
syntax - Remove tools (Task Agents don't use tools)
- Update invocation to use
/invoke-agent-task
endpoint - Change input format from messages to structured inputs
Before (Tool Agent):
{
"agent_type": "tool",
"config": {
"system_prompt": "You are a helpful assistant.",
"tools": [...]
}
}
After (Task Agent):
{
"agent_type": "task",
"config": {
"system_prompt": "Process {{input_field}} and provide analysis.",
"input_schema": {
"type": "object",
"properties": {
"input_field": {"type": "string"}
}
}
}
}