SOP Service

When developers want to keep a standard operating procedure in the agent service and start runs of it again and again, they can use the SOP support of the service layer. Procedures are stored as data, every run advances step by step in ordinary sessions, and a frontend can watch it live through the session event streams. The service-layer SOP provides the following capabilities:

Capability	Description
Procedure storage	Procedures are stored as `SOPData` with full CRUD over HTTP, and a frontend can render the editor form from `GET /sop/schema`
Background runs	Starting a run returns immediately while the run advances in the background, each step handed to its session as an ordinary chat turn
Human sign-off	A verifier can be an agent or a person; with a person, the run parks until someone files a verdict
Tool confirmation	A tool confirmation inside a step is answered through `POST /chat` like in any session, and the run carries on once answered
Cascading deletes	Deleting a run also deletes the sessions and workspaces it created, and deleting a procedure deletes all of its runs

The SOP service is experimental, and its interfaces and storage layout may change in later releases. A custom storage backend has to implement the SOP methods of StorageBase; until it does, these endpoints raise NotImplementedError while the rest of the service keeps working.

Define a Procedure

A procedure in the service is described by SOPData. Unlike the SDK, which holds agent objects directly, each step here refers to its executor and verifier by agent ID and session key. SOPData has the following fields:

Field	Type	Description
`name`	`str`	The procedure name
`description`	`str`, defaults to `""`	What the procedure is for
`steps`	`list[SOPStepDataV1]`	The ordered steps, at least one
`workspace_grain`	`"run"` \| `"per_session_key"`, defaults to `"run"`	How many workspaces a run gets
`session_settings`	`dict[str, SessionSettings]`	How the session behind each session key is opened

Each step (SOPStepDataV1) has the following fields:

Field	Type	Description
`subject`	`str`	A short name for the step
`description`	`str`	What the step must achieve
`executor`	`SOPAgentRef`	The executor, made of `agent_id` and `session_key`
`verifier`	`AgentVerifier` \| `HumanVerifier` \| `None`	The verifier. With `None`, the step passes as soon as the executor hands over
`max_attempts`	`int`, defaults to `3`	How many refusals before the whole run fails

Session Keys

session_key decides which session an agent works in. Two references with the same key share one session, and therefore one context; different keys put even the same agent into two sessions that cannot see each other. For example, to let a writer agent carry its context from one step to the next, give both steps’ executors the same key; to have a reviewer judge each time from a blank context, give it a key of its own. A session key belongs to exactly one agent. The session’s model and permission mode are also configured per key in session_settings, and every key in use must be configured there, with these fields:

Field	Type	Description
`chat_model_config`	`dict`	The session’s model configuration, including `type`, `credential_id`, `model`, and `parameters`
`fallback_chat_model_config`	`dict \| None`	The fallback model configuration, used when the primary model fails
`permission_mode`	`str`, defaults to `"default"`	The session’s permission mode

Verifiers

There are two kinds of verifier, told apart by the type field:

Type	Fields	Behavior
`AgentVerifier` (`"agent"`)	`agent`: `SOPAgentRef`; `criteria`: acceptance criteria beyond the step’s description	An agent judges in its own session, so one reviewer can hold different steps to different bars
`HumanVerifier` (`"human"`)	`question`: what the person is asked	The run parks after the executor hands over, until someone files a verdict through the API

Workspaces

A run’s sessions get their workspaces when they are created, and those workspaces belong to that run alone, never shared with another run. workspace_grain takes the following values:

Value	Effect
`run`	The whole run shares one workspace, so steps can pass work along as files by naming their paths in the handover
`per_session_key`	One workspace per session, so no step sees another’s files

The following request creates a two-step procedure: a writer agent produces a draft that a reviewer agent accepts, and the final version is then signed off by a person:

Create a procedure

curl -X POST http://localhost:8000/sop/ \
  -H "X-User-ID: alice" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "write-article",
      "steps": [
        {
          "subject": "Write the draft",
          "description": "Write a first draft of an article introducing vector databases.",
          "executor": {"agent_id": "agent-writer", "session_key": "writer"},
          "verifier": {
            "type": "agent",
            "agent": {"agent_id": "agent-reviewer", "session_key": "reviewer"},
            "criteria": "Covers at least index structures and similarity metrics."
          }
        },
        {
          "subject": "Finalize",
          "description": "Turn the draft into a version ready to publish.",
          "executor": {"agent_id": "agent-writer", "session_key": "writer"},
          "verifier": {"type": "human", "question": "Is the final version ready to publish?"}
        }
      ],
      "session_settings": {
        "writer": {
          "chat_model_config": {
            "type": "dashscope",
            "credential_id": "cred-xxx",
            "model": "qwen3.8-max",
            "parameters": {}
          }
        },
        "reviewer": {
          "chat_model_config": {
            "type": "dashscope",
            "credential_id": "cred-xxx",
            "model": "qwen3.8-max",
            "parameters": {}
          }
        }
      }
    }
  }'

The following procedures are refused with 422 when created or updated, rather than failing once a run starts:

Case	Reason
A step uses a session key missing from `session_settings`	A run could not open a session for it
One session key is used by two different agents	A session belongs to exactly one agent
An invalid model configuration	A run could not open a session with it
Empty `steps`	A run of it could never end

List the Endpoints

All SOP endpoints live under /sop, split into procedures and runs:

Method and path	Description
`GET /sop/schema`	Return the JSON Schema of `SOPData`, for rendering the editor form
`GET /sop/`	List the current user’s procedures
`POST /sop/`	Create a procedure, returning `sop_id`
`GET /sop/{sop_id}`	Read one procedure
`PATCH /sop/{sop_id}`	Replace the procedure’s contents with a new `data`; existing runs are unaffected
`DELETE /sop/{sop_id}`	Delete the procedure and all of its runs
`POST /sop/{sop_id}/runs`	Start a run, with the body `{"inputs": [Msg, ...]}`
`GET /sop/runs`	List runs, newest first, filterable by `sop_id` and `phase`
`GET /sop/runs/{sop_run_id}`	Read one run and its current state
`DELETE /sop/runs/{sop_run_id}`	Delete one run and the sessions it created
`POST /sop/runs/{sop_run_id}/verdict`	File a verdict on a step waiting for human sign-off

GET /sop/runs?phase=awaiting lists every run waiting on someone, whether for human sign-off or for a tool confirmation.

Run a Procedure

Starting a run first copies the procedure’s current contents into the run record, so editing the procedure later never affects a run already started. It then opens one session per session key, named “procedure name / session key”, and returns the run record immediately while the run advances in the background:

Start a run

curl -X POST http://localhost:8000/sop/sop-xxx/runs \
  -H "X-User-ID: alice" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {"name": "alice", "role": "user", "content": [{"type": "text", "text": "Aim it at beginners."}]}
    ]
  }'

In the returned SOPRunRecord, sessions maps each session key to its session ID, and state is the run state, whose phase tells where the run stands as a whole. Developers can subscribe to those sessions’ event streams at GET /sessions/{session_id}/stream to watch live, and poll GET /sop/runs/{sop_run_id} for progress.

Submit Results

Each step is handed to the agent in its session as an ordinary chat turn. That turn is equipped with one extra submit tool, through which the agent writes its result straight into the run state:

Tool	Given to	Purpose
`SubmitHandover`	The executor	Submits the account handed to the following steps
`SubmitVerdict`	The verifier	Submits whether the work passes, with the reason when it does not; the reason goes to the executor verbatim on the next attempt

If the agent’s reply ends without calling its submit tool, it is reminded to call it. After three reminders with nothing submitted, the reply ends in an error and counts as a refusal. An executor with no handover and a verifier with no verdict both spend the step’s max_attempts.

Only turns dispatched by the run get a submit tool. A developer or user typing directly into a step’s session is just having a conversation: they are neither asked to submit nor able to move the run.

Sign Off as a Person

With a HumanVerifier, the step enters awaiting once the executor hands over, and the run stops. A verdict filed through the following endpoint at any time lets the run carry on in the background:

File a human verdict

curl -X POST http://localhost:8000/sop/runs/run-xxx/verdict \
  -H "X-User-ID: alice" \
  -H "Content-Type: application/json" \
  -d '{
    "step_index": 1,
    "passed": false,
    "message": "The ending lacks references; add them and resubmit."
  }'

The request body has the following fields:

Field	Type	Description
`step_index`	`int`	The index of the step being judged, starting at 0
`passed`	`bool`	Whether the work passes
`message`	`str`, defaults to `""`	Why it was refused, handed to the executor verbatim

The endpoint returns the updated run record as soon as the verdict is recorded. It answers 404 when the run or step does not exist, and 409 when the step is not judged by a person or is not currently waiting to be.

Handle Tool Confirmations

When an agent in a step asks for tool confirmation, the step also enters awaiting. Answering works exactly as in any session: send POST /chat to that session with a UserConfirmResultEvent or ExternalExecutionResultEvent as the body. The resumed turn still carries the submit tool, and once it finishes the run carries on in the background with no further call. If the resumed reply is interrupted, the run stays where it is.

Delete Procedures and Runs

Deletes cascade to the resources a run created:

Endpoint	What is deleted
`DELETE /sop/runs/{sop_run_id}`	The run record and every session it created (including any turn in progress and the session event streams), and its workspaces are closed
`DELETE /sop/{sop_id}`	The procedure record and all of its runs, each cleaned up as in the row above

The run created these sessions, so they serve no purpose once it is gone, and a background tool finishing later could otherwise wake them up again. That is why they are deleted along with it.

Current Limitations

The SOP service currently has the following limitations:

Limitation	Description
No way to stop a run	There is no endpoint yet to stop a run that is advancing; it can only be deleted
No automatic recovery	If the service process crashes or is redeployed, a run that was advancing stays at `running` and does not continue on its own
Cross-node deletes	In a multi-node deployment, deleting a run that is advancing on another node waits until that node’s advance stops

Get Started

Building Blocks

Agent as Service

Others

Define a Procedure

Session Keys

Verifiers

Workspaces

List the Endpoints

Run a Procedure

Submit Results

Sign Off as a Person

Handle Tool Confirmations

Delete Procedures and Runs

Current Limitations

​Define a Procedure

​Session Keys

​Verifiers

​Workspaces

​List the Endpoints

​Run a Procedure

​Submit Results

​Sign Off as a Person

​Handle Tool Confirmations

​Delete Procedures and Runs

​Current Limitations

Define a Procedure

Session Keys

Verifiers

Workspaces

List the Endpoints

Run a Procedure

Submit Results

Sign Off as a Person

Handle Tool Confirmations

Delete Procedures and Runs

Current Limitations