SOIT Docs
Core

Execute

Run SOIT agents and workflows through reliable governed execution paths.

Execute is the runtime layer for agent turns, workflow runs, tool calls, retrieval, and model calls. SOIT treats every executable request as a traceable runtime event instead of a best-effort side effect.

What Execute provides

  • A unified run ledger for chat turns, agent runs, workflow runs, tool runs, and batch work.
  • Tasks for asynchronous and long-running work.
  • Run steps for each observable unit such as LLM calls, retrieval, tool calls, and workflow nodes.
  • Artifacts for large payloads and files stored outside the database.
  • Cost entries for model, tool, egress, and metered resource usage.
  • Outbox-backed event dispatch for reliable state changes and worker execution.

The governed execution path

Every execution follows the same path regardless of how it starts:

  1. The request resolves identity and scope (tenant, workspace, RBAC).
  2. The domain service asks the kernel runtime to create a run.
  3. Domain state, ledger records, and outbox events commit in one database transaction — no lost or phantom events.
  4. The dispatcher hands events to workers, which perform side effects through governed adapters only.
  5. Results, costs, latency, and errors project back into the ledger and stream to the UI.

Formal execution always resolves the published version of the agent or workflow. Draft behavior is reachable only through explicit preview — a production request never silently consumes unreviewed changes.

Entry points

Work reaches the runtime from more than the console, and every entry point creates the same kind of run:

  • The console and the /api/v1 API, including the soit CLI.
  • The OpenAI-compatible gateway under /v1: each call is a run with mode=gateway and source=gateway.
  • Direct tool calls under /api/v1/tools and MCP clients at /mcp: each call is a run with mode=tool.

The run id comes back with the call (the x-soit-run-id header, or ai.soit/run_id in an MCP result), so application logs can be joined to runtime evidence.

Reliability properties

  • Transactional intent: state change and event publication commit together (see Outbox Events).
  • Append-only history: steps are never rewritten; retries create new steps.
  • Bounded records: runs and steps store summaries; large payloads become artifacts.
  • Failure preservation: a failed run keeps every prior step, artifact, and cost entry, plus the failing step's error evidence.

Design principle

SOIT records first-class execution state before and after work happens. A successful execution path should be inspectable, replayable, and attributable to a workspace, user, version, and capability set. If work crosses a model, retrieval, tool, workflow node, memory, or external boundary, it must leave runtime evidence — this rule is enforced by tests, not just documentation.

Build

Assemble governed agents from typed SOIT capabilities.

Observe

Inspect SOIT runtime behavior through runs, traces, costs, approvals, feedback, and replay evidence.

On this page

What Execute providesThe governed execution pathEntry pointsReliability propertiesDesign principleRelated capabilities