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-3-haiku-20240307-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",
    "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",
    "description": "Evaluates insurance claims for approval or denial",
    "agentType": "task",
    "config": {
        "llmModelId": "anthropic.claude-3-haiku-20240307-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",
    "description": "Analyzes sales data and provides insights",
    "agentType": "task",
    "config": {
        "llmModelId": "anthropic.claude-3-5-sonnet-20241022-v2: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",
    "description": "Processes structured data",
    "agentType": "task",
    "notes": "Initial version",
    "config": {
        "llmModelId": "anthropic.claude-3-haiku-20240307-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.

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

• Single message flow: Each invocation is independent (no conversation history)
• Schema constraints: Input schema must be type "object" with properties

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",
    "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-3-haiku-20240307-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 orchestrator
POST /v1/agents/{orchestrator_id}/versions/latest/invoke-agent

{
    "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. 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):

{
    "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"}
            }
        }
    }
}

Future Enhancements

Planned improvements for Task Agents:

• Streaming support: Stream responses for long-running tasks
• 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