AWS SQS
Connect your agents to Amazon SQS for reliable message processing. Poll queues to trigger agents (inbound) or publish agent results to queues (outbound).
Inbound (Consumer)
Poll messages from SQS queues and trigger agent runs. Each message is processed by all linked agents, and successfully processed messages are automatically deleted from the queue.
How Inbound Works
Inbound SQS connectors poll messages from your queue using long polling for efficiency. When messages arrive, they're parsed and dispatched to all linked agents. After successful processing, messages are deleted from the queue. Failed runs leave messages for retry.
Configuration
- Queue URL: Full SQS queue URL (e.g.,
https://sqs.us-east-1.amazonaws.com/123456789/my-queue) - Region: AWS region where the queue is located
- Max Messages: 1-10 messages per poll (default: 10)
- Wait Time: Long polling wait time, 0-20 seconds (default: 20)
- Visibility Timeout: Time to process before message reappears (default: 300s)
IAM Permissions
Your IAM user needs these permissions on the queue:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sqs:ReceiveMessage",
"sqs:DeleteMessage",
"sqs:GetQueueAttributes"
],
"Resource": "arn:aws:sqs:us-east-1:123456789:my-queue"
}
]
}Message Payload
Your message body is parsed as JSON and enriched with SQS metadata:
{
"order_id": "12345",
"customer_email": "john@example.com",
"items": ["widget-a", "widget-b"],
"total": 234.56,
"_sqs": {
"message_id": "abc123-def456-ghi789",
"receipt_handle": "AQEBw...",
"queue_url": "https://sqs.us-east-1.amazonaws.com/123456789/orders",
"approximate_receive_count": 1,
"sent_timestamp": 1705312800000
}
}The _sqs metadata includes message ID, receipt handle, queue URL, receive count, and timestamp.
Message Lifecycle
- Success: Message deleted from queue after all agents complete successfully
- Failure: Message returns to queue after visibility timeout for retry
- Dead Letter: Configure DLQ in AWS for messages that fail repeatedly
Long Polling
Uses long polling (default 20s) for cost efficiency. Reduces empty responses and API calls. Set wait time to 0 for immediate responses (higher cost).
Outbound (Producer)
Send agent results to SQS queues when runs complete. Results are automatically published to your configured queue with full run metadata.
How Outbound Works
Outbound SQS connectors send messages to your queue when linked agents complete runs. Results include the agent output, run metadata, and token usage. Perfect for chaining workflows or triggering downstream processing.
Configuration
- Queue URL: Full SQS queue URL to publish results
- Region: AWS region where the queue is located
- Message Group ID: (FIFO queues only) Group messages for ordering
IAM Permissions
Your IAM user needs these permissions:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sqs:SendMessage",
"sqs:GetQueueAttributes"
],
"Resource": "arn:aws:sqs:us-east-1:123456789:my-results-queue"
}
]
}Output Payload
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "order-processor",
"status": "completed",
"output": "Order processed successfully. Total: $234.56",
"error": null,
"started_at": "2024-01-15T10:30:00Z",
"ended_at": "2024-01-15T10:30:05Z",
"token_usage": {
"prompt_tokens": 150,
"candidates_tokens": 50,
"total_tokens": 200
}
}Includes run_id, agent_name, status, output, error, timestamps, and token_usage.
FIFO Queue Support
For FIFO queues (*.fifo), configure a Message Group ID to maintain ordering. Messages with the same group ID are delivered in order. The message deduplication ID is automatically set to the run ID.