Task Agent

Experimental Feature

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:

1. Change agent type from "tool" to "task"
2. Add input_schema defining your input structure
3. Update system_prompt to use {{variable}} syntax
4. Remove tools (Task Agents don't use tools)
5. Update invocation to use /invoke-agent-task endpoint
6. 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"}
            }
        }
    }
}