staffdeck-api-run-agent

# Run a StaffDeck agent ## Prepare 1. Require `STAFFDECK_BASE_URL`, `STAFFDECK_API_KEY`, and an accessible `agent_id`. 2. Read [references/run-api.md](references/run-api.md) for routes and payloads. 3. Generate a unique, stable `Idempotency-Key` for each logical session or run. Reuse it only to retry the identical request. ## Choose session mode - Use a persistent session when the task may require user clarification, a pending SOP, or follow-up turns. - Use stateless mode only for an isolated request that must not affect later conversations. - Reuse the same `session_id` for every continuation of an `awaiting_input` run. ## Execute 1. For a persistent conversation, create or recover a session with `POST /agents/{agent_id}/sessions`. Supply a stable `external_session_id` from the caller's system. 2. For an interactive answer, prefer `POST /agents/{agent_id}/runs:stream` and consume SSE in the same request. Retain the `X-Run-ID` response header. 3. For detached execution, use `POST /agents/{agent_id}/runs`, then consume `GET /runs/{run_id}/events` or poll `GET /runs/{run_id}` with bounded backoff. 4. Stop polling at `succeeded`, `failed`, `cancelled`, or `awaiting_input`. 5. Call `/result` only after `succeeded`. 6. Preserve `reply`, `citations`, `tool_calls`, `task_results`, `session_state`, and `artifacts` in the result passed to the caller. ## Continue or cancel - On `awaiting_input`, report the requested information and submit the user's answer as a new run in the same session. - On `ACTION_BUDGET_EXHAUSTED`, preserve the session and continue only when authorized; do not silently loop forever. - Cancel with `POST /runs/{run_id}:cancel` when the caller requests cancellation or the result is no longer needed. - Use `Last-Event-ID` when reconnecting SSE. - Append `run.output.delta` content in order. Replace the accumulated text when `run.output.replace` is emitted, and stop display streaming at `run.output.completed`. ## Evidence and privacy Treat public Trace as an auditable execution summary, not raw COT. Keep citation metadata attached to the claims it supports. Do not expose masked credentials, sensitive model inputs, or unrelated session data.