Skip to main content

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

FeatureTask AgentTool Agent
Input TypeStructured JSON dataConversational messages
Schema ValidationRequired input_schemaOptional
System PromptTemplate variables requiredStatic or dynamic
Use CaseData processing, structured workflowsConversational AI, tool usage
Invocation Endpoints/invoke-agent-task, /invoke-agent-task-streaming/invoke-agent, /invoke-agent-stream

Configuration Requirements

Essential Parameters

ParameterDescriptionRequiredExample
agent_typeMust be "task"Yes"task"
llm_model_idBedrock model identifierYesamazon.nova-micro-v1:0
system_promptTemplate with {{variables}}Yes"Evaluate claim {{claim_id}} for policy {{policy_number}}"
input_schemaJSON schema for input validationYesSee examples below
inference_configLLM parametersNo{"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"}
}
}
}
}