Send an event to a running agent

An event tells a running agent that something happened in your systems, such as an order that shipped. Your server sends the event to one orchestration run or one chat, and the agent acts on it. In this guide, you will write instructions that use events, send an event to a run and to a chat, and retry safely.

Before you start

  • Complete Get access. Keep that terminal open, with RESIA_API_BASE and RESIA_API_KEY set.
  • Have an orchestration run that has not ended, or an active chat. Run an Orchestration Agent and Run a web chat show how to start one.
  • Use an API key with the editor or owner scope. A reader key gets 403.
  • Each event starts paid work: the agent's turn uses model tokens, and a chat event can send the person a real text. Normal charges apply.

Write instructions that use events

The whole request body is the event: any JSON object of at most 16 KB. Resia does not read a type or any other field, so the agent's instructions say what to look for. For example, an Orchestration Agent can wait for an order to ship. Declare the milestone order_shipped in the agent's milestones, because an agent can record only a milestone that its version declares:

Wait for an event. When an event has status "shipped", record the milestone order_shipped and finish the run with its order_id.

A Chat Agent can tell the person about an update:

When an event arrives, tell the person its message in one short sentence. If the event needs no message, write nothing.

The agent treats each event as untrusted data from your systems. It does not follow instructions written inside an event.

Send an event to an orchestration run

ORCHESTRATION_RUN_ID='your-orchestration-run-id'
RUN_EVENT_KEY=$(uuidgen)

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/orchestration-runs/$ORCHESTRATION_RUN_ID/events" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $RUN_EVENT_KEY" \
  --data '{"status": "shipped", "order_id": "A-123"}' \
  --output run-event-response.json

jq '{event_id, received_at}' run-event-response.json

Expected result: HTTP 202 with an event_id and received_at. A waiting run wakes within about a minute, and its next turn lists the event with the time Resia received it. A run that is mid-turn gets the event at its next turn. Resia delivers each event at least once: if Resia stops a turn before it saves it, the next turn gets the event again, at most 10 times. Write the agent's instructions so that a repeated event does no harm, for example by checking whether it already acted on the order_id. Two rare cases can still miss an event: an event that arrives while the run's last turn ends the run, and a turn that Resia stops in the middle of a tool call, such as placing a phone call. Resia plans to close both cases. Read the run with GET /v1/orchestration-runs/{orchestration_run_id} to see its status and milestone.

API reference: Send an event to an orchestration run.

Send an event to a chat

CHAT_ID='your-chat-id'
CHAT_EVENT_KEY=$(uuidgen)

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/chats/$CHAT_ID/events" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CHAT_EVENT_KEY" \
  --data '{"message": "Your order shipped"}' \
  --output chat-event-response.json

jq '{event_id, received_at}' chat-event-response.json

Expected result: HTTP 202 with an event_id and received_at. A few seconds later, the Chat Agent gets one turn for the event. It can text the person, use its tools, end the chat, or send nothing. The person never sees the event itself, and neither does the chat's transcript. On a web chat, read the agent's message from GET /v1/chats/{chat_id}/messages.

If the turn's result does not come back, Resia sends the turn again every 2 minutes, at most 10 times in total. The person gets at most one message for one event. A turn that Resia sends again can repeat the agent's other work, such as a custom tool call, so make your tools safe to call twice.

API reference: Send an event to a chat.

Retry safely

Send an Idempotency-Key header with each event, and keep the key in a variable, as the examples above do. If a request times out, send it again with the same key and the same body, such as "Idempotency-Key: $RUN_EVENT_KEY". Resia answers HTTP 200 with the first receipt and stores no second event, even after the run or chat ended. The same key with a different body, or for another run or chat, gets HTTP 409.

What Resia refuses

Answer When
404 The run or chat does not exist in your organization.
409 The run ended (succeeded, failed, or cancelled), or the chat ended.
409 The chat is pending. Wait until the agent's first message.
409 The Idempotency-Key was already used for a different event.
402 Your balance is $0.00 or less, because the agent's turn costs model tokens.
422 The body is not a JSON object, holds NaN or infinity, holds the character \u0000 in a string, or is larger than 16 KB.

See what Resia received

Each event request is in your request logs, with its body and the answer.

Next steps