Start a Run

Invoke a deployed Agent through a canonical event with a stable session and JSON input.

Before you begin

Deploy an Agent and ensure its Resource bindings resolve for the authenticated tenant, customer, or principal. Choose a stable session identifier that represents the conversation, workflow, or customer-owned durable history. Prepare JSON input that the Agent understands.

Steps

1. Open Runs and choose Start Run.
2. Select the deployed Agent.
3. Enter the stable session identifier.
4. Provide canonical JSON event data.
5. Choose Queue for durable asynchronous acceptance or Live when streaming authority is available.
6. Submit the event and wait for the accepted Run identity.
7. Open the Run detail page.

Constal authorizes the same resolved execution snapshot it persists. A queued event may wait behind an existing top-level Run in the session, but its acceptance identity remains explicit.

The canonical dispatcher API performs the same operation:

curl https://platform.constal.ai/v1/events \
  -H "Authorization: Bearer $CONSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "v":1,
    "id":"support-message-42",
    "type":"message",
    "target":"crn:constal:production:acme:default:agent/support",
    "session":"customer-1042",
    "data":{"message":"Where is my order?"},
    "deliver":"queue"
  }'

Alternatively, POST .../agents/:agent/sessions/:session/events accepts { "eventId": "...", "body": ..., "deliver": "queue" }. Add ?stream=true only when the client is prepared to consume the native stream. Agent SDK code does not start an administrative Run; its ctx.spawn() creates a registered subtask inside an already accepted Run.

Verify

Confirm the result contains a Run id and that the detail page shows the chosen Agent, session, status, budget, and journal. Copy the full Run address when using the API; the serial Run id alone is not sufficient context.

Next steps

Continue with Operate Runs, Stream a Run, or configure authenticated ingress through Channels.