SQS
Amazon SQS verbindet Agenten mit zuverlässigen Nachrichten-Queues. Inbound-Verbindungen fragen Queues ab und starten Agenten; Outbound-Verbindungen veröffentlichen deren Ergebnisse in Queues.
Auf dieser Seite
Einrichtung
SQS Queue erstellen
Erstelle in der AWS Console eine Standard- oder FIFO-Queue oder verwende eine vorhandene.
IAM-Nutzer erstellen
Erteile für die Queue die Berechtigungen sqs:ReceiveMessage, sqs:DeleteMessage und sqs:ChangeMessageVisibility.
Verbindung erstellen
Öffne den Agenten, klicke auf Add inbound connector, dann auf Create New Connector und wähle AWS SQS.
Konfigurieren und erstellen
Wähle den Mode Inbound und gib Queue URL, Region sowie AWS-Zugangsdaten ein. Klicke auf Create; Connic beginnt anschließend, die Queue abzufragen.
So funktioniert Inbound
Inbound-SQS-Verbindungen fragen Nachrichten aus der Queue per Long Polling ab. Treffen Nachrichten ein, werden sie geparst und an alle verknüpften Agenten weitergeleitet. Nach erfolgreicher Verarbeitung werden sie aus der Queue gelöscht. Bei fehlgeschlagenen Runs bleiben die Nachrichten für einen erneuten Versuch erhalten.
- Queue URL: Vollständige URL der SQS Queue (z. B.
https://sqs.us-east-1.amazonaws.com/123456789/my-queue) - Region: AWS-Region der Queue
- Max Messages: 1 bis 10 Nachrichten pro Abfrage (Standard: 10)
- Wait Time: Wartezeit für Long Polling, 0 bis 20 Sekunden (Standard: 20)
- Visibility Timeout: 6 bis 43.200 Sekunden, bevor eine nicht abgeschlossene Nachricht erneut erscheint (Standard: 300)
IAM-Berechtigungen
Der IAM-Nutzer benötigt diese Berechtigungen für die 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"
}
]
}Nachrichten-Payload
JSON-Objekte im Body werden um SQS-Metadaten ergänzt. Andere Body-Inhalte werden in ein message-Feld geschrieben:
{
"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
}
}Die _sqs-Metadaten enthalten Message-ID, Receipt Handle, Queue URL, Anzahl der Empfangsversuche und Zeitstempel.
Lebenszyklus einer Nachricht
- Erfolg: Die Nachricht wird aus der Queue gelöscht, nachdem alle Agenten erfolgreich abgeschlossen haben
- Fehler: Nach Ablauf des Visibility Timeouts kehrt die Nachricht für einen erneuten Versuch in die Queue zurück
- Dead Letter: Konfiguriere in AWS eine DLQ für wiederholt fehlgeschlagene Nachrichten
Long Polling
Verwendet Long Polling (Standard: 20 s), um leere Antworten und API-Aufrufe zu reduzieren. Setze Wait Time für sofortige Antworten auf 0; dadurch entstehen höhere Kosten.
Einrichtung
Ziel-SQS-Queue erstellen oder auswählen
Stelle sicher, dass sie in der AWS Console vorhanden ist.
IAM-Nutzer erstellen
Erteile für die Queue die Berechtigung sqs:SendMessage.
Verbindung erstellen
Öffne den Agenten, klicke auf Add outbound connector, dann Create New Connector und wähle AWS SQS.
Konfigurieren und erstellen
Wähle den Mode Outbound und gib Queue URL, Region sowie AWS-Zugangsdaten ein. Klicke auf Create; Ergebnisse verknüpfter Agenten werden anschließend an die Queue gesendet.
So funktioniert Outbound
Automatische Outbound-Verbindungen senden Wrapper abgeschlossener Runs und können auf ausgewählte Inputs begrenzt werden. Agent-Tool- und Middleware-Outbound-Verbindungen senden nur bei einem Aufruf. Beide Muster eignen sich, um Workflows zu verketten oder nachgelagerte Verarbeitung zu starten.
- Queue URL: Vollständige URL der SQS Queue, in der Ergebnisse veröffentlicht werden
- Region: AWS-Region der Queue
- Message Group ID: (Nur FIFO-Queues) Nachrichten zur geordneten Verarbeitung gruppieren
IAM-Berechtigungen
Der IAM-Nutzer benötigt diese Berechtigungen:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sqs:SendMessage",
"Resource": "arn:aws:sqs:us-east-1:123456789:my-results-queue"
}
]
}Automatische 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
}
}Enthält run_id, agent_name, status, output, error, Zeitstempel und token_usage.
Agent-Tool- und Middleware-Outbound-Verbindungen
Eine Agent-Tool-Outbound-Verbindung stellt einen bearbeitbaren Tool-Namen bereit, standardmäßig send_to_<connector_name>. Rufe eine Middleware-Outbound-Verbindung über send_connector mit ihrem konfigurierten Namen auf. Beide verwenden dieses von der Verbindung definierte Payload-Schema:
{
"payload": {
"order_id": "12345",
"status": "approved"
}
}payload wird zum Body der SQS-Nachricht. Connic verwendet die konfigurierte Queue, Zugangsdaten, FIFO Group, Serialisierung, Wiederholungsstrategie und das Bridge-Routing, ohne dem Modell diese Einstellungen offenzulegen.
Unterstützung für FIFO-Queues
Konfiguriere für FIFO-Queues (*.fifo) eine Message Group ID, um die Reihenfolge beizubehalten. Nachrichten mit derselben Group ID werden geordnet zugestellt. Automatische Zustellungen verwenden die Run-ID als Message Deduplication ID.