Skip to main content
connic

AWS SQS

connic polls your queue, runs the linked agents on each message and deletes it once every run completes. A failed message comes back after the visibility timeout.

Modes
Inbound, Outbound
Set up in
Dashboard or connectors/*.yaml
Documentation
AWS SQS docs
Publisher
By connic

Delete a message only after the work is done

connic long polls your queue, runs every linked agent on each message and deletes it once all of those runs have completed.

Max Messages
1 to 10 messages per poll, 10 by default.
Wait Time
Long polling for 0 to 20 seconds, 20 by default. Shorter waits answer faster and make more API calls.
Visibility Timeout
6 to 43,200 seconds, 300 by default. After a failed run, the message reappears once this time has passed.
  1. Receive

    connic long polls the queue and takes up to Max Messages per poll.

    wait_time_seconds: 20
  2. Run

    Every linked agent gets a run. While runs are in flight, connic keeps extending the message's visibility timeout.

  3. Delete

    When every run has completed, connic deletes the message from the queue.

    Deleted
  4. Retry

    If a run fails, the message stays. It becomes visible again after the visibility timeout and starts new runs, and the queue's redrive policy moves repeat failures to your dead-letter queue.

    Visible again

Read the body and the queue metadata

The message body becomes the agent's input, and connic adds what SQS knows about the message under _sqs.

JSON and text
A JSON object arrives with its fields as sent. Any other body arrives under message.
Receive count
approximate_receive_count tells the agent how often the message was received, so it can handle a retry differently.
Files in the message
A JSON object can carry a files array with each file's name, MIME type and base64 data, up to 10 files and 10 MiB in total.
send-message.sh
aws sqs send-message \
  --queue-url <queue-url> \
  --message-body '{"document_id": "doc_5521", "type": "invoice"}'
context["payload"]
{
  "document_id": "doc_5521",
  "type": "invoice",
  "_sqs": {
    "message_id": "5fea7756-0ea4-451a-a703-a558b933e274",
    "receipt_handle": "AQEBwJnKyrHigUMZj6rYigCg...",
    "queue_url": "https://sqs.us-east-1.amazonaws.com/123456789/intake",
    "approximate_receive_count": 1,
    "sent_timestamp": 1791881998000
  }
}

Keep the queue next to your agents

Declare it as a YAML file in connectors/. Region and IAM keys live in a Connection, so the file holds only the queue and its polling settings. A connector declared in code starts polling when its deployment goes live.

Scoped IAM keys
Inbound needs sqs:ReceiveMessage, sqs:DeleteMessage and sqs:ChangeMessageVisibility on the queue. Outbound needs sqs:SendMessage on the target queue.
Private endpoints
Route the connector through a bridge when the queue endpoint is only reachable inside your network.
connectors/document-intake.yaml
type: sqs
mode: inbound
name: Document intake
connection: aws-intake
config:
  queue_url: ${INTAKE_QUEUE_URL}
  max_messages: 5
  visibility_timeout: 900
agents:
  - document-extractor
create: connectors/document-intake.yaml (sqs)

Send results to another queue

An outbound connector sends each completed run to a queue, or lets the agent send its own message during the run.

Run results
Automatic delivery sends run_id, agent_name, status, output, error, timestamps and token_usage as the message body.
FIFO queues
Set a Message Group ID to keep results in order within the group. Automatic deliveries use the run ID as the deduplication ID.
Agent-sent messages
Linked as an agent tool or called from middleware, the connector sends the payload it's given as the message body. Queue and credentials stay hidden from the model.
connectors/extracted-documents.yaml
type: sqs
mode: outbound
name: Extracted documents
connection: aws-intake
config:
  queue_url: ${RESULTS_QUEUE_URL}
  message_group_id: documents  # FIFO queues only
agents:
  - name: document-extractor
    outbound:
      usage: automatic
      source: [document-intake]
message body
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "document-extractor",
  "status": "completed",
  "output": "Invoice INV-2041, Example GmbH, EUR 1,240.00.",
  "error": null,
  "started_at": "2026-10-13T09:00:01Z",
  "ended_at": "2026-10-13T09:00:12Z",
  "token_usage": {
    "input_tokens": 3184,
    "output_tokens": 142,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 3326
  }
}

Where SQS fits

Pick a setup to see what lands on the queue, what the agent receives and where the result goes.

Your upload service queues each document, and the extracted fields go to a results queue when the run completes.

Upload service
SQS consumer
document-extractor
Record on the results queue
context["payload"]
{
  "document_id": "doc_5521",
  "type": "invoice",
  "_sqs": {
    "message_id": "5fea7756-0ea4-451a-a703-a558b933e274",
    "receipt_handle": "AQEBwJnKyrHigUMZj6rYigCg...",
    "queue_url": "https://sqs.us-east-1.amazonaws.com/123456789/intake",
    "approximate_receive_count": 1,
    "sent_timestamp": 1791881998000
  }
}
message body
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "document-extractor",
  "status": "completed",
  "output": "Invoice INV-2041, Example GmbH, EUR 1,240.00.",
  "error": null,
  "started_at": "2026-10-13T09:00:01Z",
  "ended_at": "2026-10-13T09:00:12Z",
  "token_usage": {
    "input_tokens": 3184,
    "output_tokens": 142,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 3326
  }
}

The agent picks a warehouse and carrier for each order and queues the fulfillment job itself.

Shop backend
SQS consumer
order-router
Job on the fulfillment queue
context["payload"]
{
  "order_id": "ord_8812",
  "items": 3,
  "ship_to": "DE-10115",
  "_sqs": {
    "message_id": "0c7a2f91-5b1e-4d0a-9e47-2d8f3c6b1a50",
    "receipt_handle": "AQEBwJnKyrHigUMZj6rYigCg...",
    "queue_url": "https://sqs.us-east-1.amazonaws.com/123456789/intake",
    "approximate_receive_count": 1,
    "sent_timestamp": 1791881998000
  }
}
connector-payload.json
{
  "payload": {
    "order_id": "ord_8812",
    "warehouse": "north",
    "carrier": "standard"
  }
}

Each signup lands on the queue, and the agent writes a welcome email that fits the person's role.

Signup service
SQS consumer
onboarding-writer
Welcome email
context["payload"]
{
  "email": "jana@example.com",
  "company": "Example GmbH",
  "role": "Head of Operations",
  "_sqs": {
    "message_id": "9d41e6b8-27c3-4f5a-b0d2-6a1e8f7c3b94",
    "receipt_handle": "AQEBwJnKyrHigUMZj6rYigCg...",
    "queue_url": "https://sqs.us-east-1.amazonaws.com/123456789/intake",
    "approximate_receive_count": 1,
    "sent_timestamp": 1791881998000
  }
}
output.json
{
  "to": "jana@example.com",
  "subject": "Welcome to Example Cloud, Jana",
  "body": "Hi Jana, here's how to set up your first workflow."
}

The agent matches each payment to an open invoice and books it through its tools. A payment that keeps failing ends up in your dead-letter queue.

Billing system
SQS consumer
payment-matcher
Entry in your ledger
context["payload"]
{
  "payment_id": "pay_7730",
  "amount": 1240.0,
  "reference": "INV 2041 Example",
  "_sqs": {
    "message_id": "3b8e1d27-6f4c-4a95-8c02-e7d5a9f1b468",
    "receipt_handle": "AQEBwJnKyrHigUMZj6rYigCg...",
    "queue_url": "https://sqs.us-east-1.amazonaws.com/123456789/intake",
    "approximate_receive_count": 3,
    "sent_timestamp": 1791881998000
  }
}

AWS SQS FAQ

Add an AWS SQS connector in Inbound mode, pick a Connection with the region and IAM keys, enter the queue URL and link the agent. Connectors created in the dashboard start paused, so click Resume when you're ready. connic then long polls the queue, runs every linked agent on each message and deletes it after all runs complete. To compare SQS with other triggers, read about common connector patterns.

The message isn't deleted. It becomes visible again after the visibility timeout and starts new runs. Set a redrive policy on the queue in AWS, and messages that keep failing move to your dead-letter queue.

An inbound connector needs sqs:ReceiveMessage, sqs:DeleteMessage and sqs:ChangeMessageVisibility on the queue. An outbound connector needs sqs:SendMessage on the target queue.

Yes, standard and FIFO queues both work. For an outbound FIFO queue, set a Message Group ID to keep results in order within the group. Automatic deliveries use the run ID as the message deduplication ID.