Messaging Tools

The Messaging category provides SQS queue integration and generic HTTP webhook calls. Both support optional state enrichment — automatically merging fields from the agent’s .agent-state.json or conversation_map.json into outgoing payloads.

Table of contents

1. Tools
2. Tool reference
   1. sqs_send_message
   2. sqs_load_state
   3. webhook_send
3. State enrichment
4. Environment variables
   1. SQS
   2. Webhook

---

Tools

Tool	Description
sqs_send_message()	Send a message to an SQS queue
sqs_load_state()	Load agent state from .agent-state.json
webhook_send()	Send an HTTP request to a webhook endpoint

---

Tool reference

sqs_send_message

sqs_send_message(message_body: str, enrich: bool = True) -> str

Sends a JSON message to the configured SQS queue. When enrich=True (default), fields from .agent-state.json are merged into the payload before sending.

Returns: JSON with success (bool), message_id, enriched (bool), state_fields, error

---

sqs_load_state

sqs_load_state(session_id: str) -> str

Reads and returns the agent state file for the given session. Useful for inspecting what fields would be merged during enrichment.

Returns: JSON with found (bool), state (dict), error

---

webhook_send

webhook_send(
    payload: str,
    method: str = "POST",
    webhook_url: str = "",
    enrich: bool = False
) -> str

Sends an HTTP request with a JSON body. method can be POST, PUT, PATCH, or GET. If webhook_url is empty, uses WEBHOOK_URL from the environment. When enrich=True, merges conversation_map.json fields into the payload.

Authentication is via a static header: WEBHOOK_AUTH_HEADER: WEBHOOK_AUTH_TOKEN.

Returns: JSON with success (bool), status_code, response_body, webhook_url, error

---

State enrichment

Both SQS and webhook tools support state enrichment to automatically include session context:

flowchart LR
    TOOL[sqs_send_message<br/>enrich=True]
    STATE[.agent-state.json<br/>conversation_map.json]
    MERGE[Merged payload]
    DEST[SQS / Webhook]

    TOOL -->|read| STATE
    TOOL -->|merge fields| MERGE
    STATE -->|session context| MERGE
    MERGE --> DEST

---

Environment variables

SQS

Variable	Required	Default	Description
SQS_QUEUE_URL	Yes	—	Full SQS queue URL
IS_EVALUATION	No	false	Evaluation mode flag (skips actual send)

Webhook

Variable	Required	Default	Description
WEBHOOK_URL	Yes*	—	Default webhook endpoint URL (*required unless passed per-call)
WEBHOOK_AUTH_HEADER	No	X-Auth-Token	Authentication header name
WEBHOOK_AUTH_TOKEN	No	—	Authentication token value
WEBHOOK_TIMEOUT	No	30	Request timeout in seconds
IS_EVALUATION	No	false	Evaluation mode flag