# Staffdeck API Run Agent

> Run a StaffDeck digital employee through Open API v1, create or continue sessions, submit stateful or stateless runs, poll durable jobs, stream SSE events, continue awaiting-input SOPs, cancel work, and download Harness artifacts. Use whenever another agent must invoke a StaffDeck employee and return auditable results with citations and tool activity.

- Skill: `openbmb/staffdeck-api-run-agent` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add openbmb/staffdeck-api-run-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openbmb/staffdeck-api-run-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: OpenBMB (https://skillmd.com/u/openbmb)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openbmb/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.