SQS
Connect your agents to Amazon SQS for reliable message processing. Poll queues to trigger agents (inbound) or publish agent results to queues (outbound).
On this page
Setup Instructions
Create an SQS queue
In the AWS Console, create a standard or FIFO queue (or use an existing one).
Create an IAM user
Grant sqs:ReceiveMessage, sqs:DeleteMessage, and sqs:ChangeMessageVisibility permissions on the queue.
Create the connector
Open your agent, click Add inbound connector, then Create New Connector and select AWS SQS.
Configure and create
Choose Inbound mode, enter Queue URL, Region, and AWS credentials. Click Create and Connic starts polling the queue.
How Inbound Works
Inbound SQS connectors poll messages from your queue using long polling. 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.
- 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: 6-43,200 seconds before an unfinished message reappears (default: 300)
IAM Permissions
Your IAM user needs these permissions on the queue:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sqs:ReceiveMessage",
"sqs:DeleteMessage",
"sqs:ChangeMessageVisibility"
],
"Resource": "arn:aws:sqs:us-east-1:123456789:my-queue"
}
]
}Message Payload
JSON object bodies are enriched with SQS metadata. Other bodies are placed in a message field:
{
"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) to reduce empty responses and API calls. Set wait time to 0 for immediate responses (higher cost).
Setup Instructions
Create or identify the target SQS queue
Ensure it exists in the AWS Console.
Create an IAM user
Grant sqs:SendMessage permission on the queue.
Create the connector
Open your agent, click Add outbound connector, then Create New Connector and select AWS SQS.
Configure and create
Choose Outbound mode, enter Queue URL, Region, and AWS credentials. Click Create and results from linked agents will be sent to the queue.
How Outbound Works
Automatic outbound connectors send completed-run envelopes and can be limited to selected inputs. Agent-tool and middleware outbound connectors send only when called. Both patterns are useful for chaining workflows or triggering downstream processing.
- 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",
"Resource": "arn:aws:sqs:us-east-1:123456789:my-results-queue"
}
]
}Automatic 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": {
"input_tokens": 150,
"output_tokens": 50,
"thinking_tokens": 0,
"cached_input_tokens": 0,
"total_tokens": 200
}
}Includes run_id, agent_name, status, output, error, timestamps, and token_usage.
Agent-tool and Middleware Outbound Connectors
An agent-tool outbound connector exposes an editable tool name, defaulting to send_to_<connector_name>. Call a middleware outbound connector by its configured name through send_connector. Both use this connector-owned payload schema:
{
"payload": {
"order_id": "12345",
"status": "approved"
}
}payload becomes the SQS message body. Connic applies the configured queue, credentials, FIFO group, serialization, retries, and Bridge routing without exposing those settings to the model.
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. Automatic deliveries use the run ID as their message deduplication ID.