Skip to main content
POST
/
api
/
agents
/
{agent_uid}
/
sandbox-run
Sandbox run
curl --request POST \
  --url https://api.example.com/api/agents/{agent_uid}/sandbox-run \
  --header 'Content-Type: application/json' \
  --data '
{
  "trigger_type": "<string>",
  "entity_uid": "<string>"
}
'
Starts a sandbox agent run. The sandbox uses the same Temporal workflow, system prompt, and LLM reasoning as a real run, but intercepts side-effecting tools. No emails are sent, no tasks are created, no webhooks fire. Use sandbox runs to validate agent behavior before activating.

​
Path parameters

​
agent_uid
string
required
UUID of the agent to test.

​
Request body

​
trigger_type
string
required
Trigger type to simulate. One of: invoice, email_received, cron.
​
entity_uid
string
UUID of the entity to hydrate the trigger payload from. Use the Sandbox entity search endpoint to find valid entity UIDs.When omitted, the backend auto-selects the most recent entity matching the agent’s trigger configuration.Ignored for cron triggers.

​
Example: invoice trigger with entity

{
  "trigger_type": "invoice",
  "entity_uid": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90"
}

​
Example: email trigger with entity

{
  "trigger_type": "email_received",
  "entity_uid": "f1e2d3c4-b5a6-9788-7069-504132241506"
}

​
Example: auto-select (entity omitted)

When entity_uid is not provided, the backend selects the most recent entity that matches the agent’s trigger filters (e.g. invoice status, collection method, customer). 
{
  "trigger_type": "invoice"
}

​
Example: cron trigger

{
  "trigger_type": "cron"
}

​
Response

Returns 202 (accepted): 
{
  "status": "success",
  "status_code": 202,
  "message": "Sandbox agent run started",
  "data": {
    "run_uid": "run-uuid-here",
    "sandbox": true
  }
}
Poll Get activity with the returned run_uid to track progress and see results.

​
Tool classification model

During a sandbox run, each tool call is classified into one of three modes:
ModeBehaviorTools
SafeExecutes normally — no side effectsread_entity, classify_entity, list_slack_channels, list_slack_users, prepare_email
GuardedIntercepted — returns a would_* previewsend_email, reply_to_email, send_slack_message, create_task, update_entity, trigger_webhook, save_draft
BlockedRefused — any unregistered toolReturns an error message requiring the tool to be classified

​
Guarded tool response shapes

When a guarded tool is called in sandbox mode, the result includes "sandbox": true and a would_* key describing what would have happened.

​
send_email

{
  "sandbox": true,
  "would_send": {
    "uid": "generated-uuid",
    "status": "sent",
    "to": ["billing@acme.com"],
    "subject": "Follow-up: Invoice INV-2026-0042",
    "body_preview": "Dear Acme Corp billing team, this is a follow-up...",
    "draft_uid": null,
    "reply_to_message_uid": null,
    "context_type": "invoice",
    "context_id": "inv-uuid-here"
  }
}

​
reply_to_email

{
  "sandbox": true,
  "would_reply": {
    "uid": "generated-uuid",
    "status": "sent",
    "reply_to_message_uid": "msg-uuid-here",
    "subject": "RE: Invoice inquiry",
    "body_preview": "Thank you for your inquiry regarding...",
    "tool_uid": "tool-uuid"
  }
}

​
send_slack_message

{
  "sandbox": true,
  "would_send_slack": {
    "message_ts": "sandbox-a1b2c3d4e5f6",
    "channel": "C0123456789",
    "text_preview": "Invoice INV-2026-0042 from Acme Corp is 15 days overdue...",
    "thread_ts": null
  }
}

​
create_task

{
  "sandbox": true,
  "would_create_task": {
    "uid": "generated-uuid",
    "title": "Review overdue invoice from Acme Corp",
    "description_preview": "Invoice INV-2026-0042 is 15 days past due...",
    "due_date": "2026-04-01",
    "priority": "high",
    "status": "todo",
    "context_entities": [
      { "entity_type": "invoice", "entity_uid": "inv-uuid-here" }
    ],
    "instructions_preview": null,
    "tool_uid": "tool-uuid"
  }
}

​
update_entity

{
  "sandbox": true,
  "would_update": {
    "entity_type": "invoice",
    "uid": "inv-uuid-here",
    "updates": {
      "status": "in_review"
    }
  }
}

​
trigger_webhook

{
  "sandbox": true,
  "would_trigger_webhook": {
    "url": "https://hooks.example.com/notify",
    "method": "POST",
    "headers": { "Content-Type": "application/json" },
    "body_preview": "{\"event\": \"invoice_overdue\", \"invoice_uid\": \"inv-uuid\"}"
  }
}

​
save_draft

{
  "sandbox": true,
  "would_save_draft": {
    "uid": "generated-uuid",
    "status": "draft",
    "subject": "Follow-up: Invoice INV-2026-0042",
    "to": ["billing@acme.com"],
    "body_preview": "Dear Acme Corp billing team...",
    "context_type": "invoice",
    "context_id": "inv-uuid-here"
  }
}

​
Errors

StatusReason
404Agent not found
409Agent is already running
422Invalid trigger type or payload