17 · The Python API reference

Everything in this guide is reached from one Python package, stalwart-agents. Its full reference, every public name with its signature, its arguments, what it returns and raises, and an example, is generated from the package's own docstrings and served at api.stalwart.it/sdk/reference. This chapter lists every public name of the four modules a customer imports, each linking to its entry there, so the guide and the reference cannot describe two different packages.

$ pip install stalwart-agents                # everything: the agents, the client, the gateway, the runtime
$ pip install "stalwart-agents[anthropic]"   # with a model provider: anthropic, openai, google, mistral or ollama

Python 3.10 to 3.14. The package's own documentation, page by page, is at api.stalwart.it/sdk, in English and Portuguese.

stalwart_agents: the agent

The Bot Builder's surface: an agent, its tools, the file it is read from, and the errors it raises. It names no agent framework, anywhere (Part I).

Name	Kind	What it is
TOOL_WORDS	value	The words a tool may carry, as @tool(...) and agent.yaml both spell them.
Agent	class	An agent: its tools, its rules, its model, and the agents it hands off to.
AgentFile	class	What agent.yaml declares: the agents, their tools, the stores and the rulebook.
AgentFileError	class	agent.yaml says something this release cannot read, at a line of the file.
HunterUnavailable	class	The checker could not be run, so nothing was checked -- never a clean result.
LicenceRequired	class	Nothing in this package answers without an activated licence: the message says how to get one.
ModelKeyMissing	class	The model's provider needs a key the environment does not hold: variable names it.
ModelUnavailable	class	The model named cannot be used here: the message says what to install or change.
NotVerified	class	The agent has a way through its checks: findings names each, with its rule and tool.
Reply	class	What the agent said, and anything that waits for the person.
RulebookNotHeld	class	The agent declares a rulebook the tool check does not hold, and it could not be registered.
RunTooLong	class	A run took more steps than its limit: limit and steps say how many.
StalwartError	class	Something stopped a command; the message says what to change.
StateConflict	class	Two steps of a run wrote to the same part of its state at once: steps names them.
StorageError	class	The store the runs are kept in could not be read or written: store names it.
ThumbRefused	class	A thumb that would record a false case, refused: the message says what to thumb instead.
Tool	class	A tool as the file declares it: its words, its schema, the line that declared it, and what runs it.
ToolUnavailable	class	An agent lists a tool with nothing to run it: declare its source (python, mcp, openapi).
VerifyResult	class	What verify found: the lints, the findings, the scan's summary and whether the gate held.
Waiting	class	A call that waits for a person: what it is, why, and the decisions it takes.
__version__	value	The package's version: 1.0.
export	function	Writes the graph agent.yaml builds, as the verifier reads it, to @p out: stalwart verify --export-only.
load	function	Read @p path, an agent.yaml.
render	function	The report stalwart verify prints.
tool	function	Declares a plain function a tool, with the words of agent.yaml.
verify	function	Check the agent @p path declares: the code checks here, then the bug hunter on the service.

stalwart_agents.client: the client

The Stalwart API from Python: plans and tool checks on your own machine, and the verification products as jobs (Part II and Part V).

Name	Kind	What it is
STREAM_DEGRADED	value	The event the iterator yields once when it falls back to polling.
ApiError	class	An error the service answered with.
Artifact	class	One artefact of a job, fetched through the client that read the job.
ArtifactRef	class	An earlier job's artefact, passed as an input by its id.
AsyncArtifact	class	One artefact of a job, fetched through the async client that read the job.
AsyncClient	class	The Stalwart API, over HTTP, with plans and tool checks answered on your own host.
AsyncEventStream	class	The async iterator await client.stream(job_id) returns.
AsyncJob	class	A submitted job, for wait=False: read it, wait for it, stream it, or cancel it.
AsyncSession	class	A conversation over an AsyncClient.
AuthenticationError	class	401: no key, or a key that does not verify.
BatchResult	class	verify_batch: one record per row, and counters derived from the records.
CassetteMiss	class	A request the cassette does not hold.
CassetteStale	class	A cassette recorded under a catalogue or vocabulary digest that has since moved.
CertificateCheck	class	What the checker established: verified, not_self_contained or failed, and why.
Client	class	The Stalwart API, over HTTP, with plans and tool checks answered on your own host.
ComputePrompt	class	The prompt the runtime built for a calculation: the text a model is given, and its parts.
ConcurrencyLimitError	class	429: every concurrent slot is taken.
ConfigurationError	class	No key, a bad base URL, or a runtime asked for that is not there.
ConfirmationToken	class	What a confirm answer hands back, for the call once a person approved it.
CounterexampleResult	class	enumerate_counterexamples: proposals with no expect or gate, verdicts only.
DeriveExpectationsResult	class	derive_expectations: the derived table.
DerivePinsResult	class	derive_pins: the obligations and their pin sets; the caveat is in caveats.
DigestMismatch	class	A download whose bytes do not hash to the digest the service named.
EnumeratePropertiesResult	class	enumerate_properties: candidate rows with no id, expect or gate; the caveat is in caveats.
Event	class	One frame: its type, its place in the job's sequence, when, and its body.
EventStream	class	The sync iterator client.stream(job_id) returns.
Finding	class	One hunt or graph finding: its rule, severity, location, witness, fix, replay state and OWASP entries.
ForestResult	class	verify_forest: one record per property.
GuardrailResult	class	verify_guardrail and generate_and_verify.
History	class	The checks a session has made: entries of names and digests, and the token covering them.
HuntResult	class	hunt and verify_graph: findings, the coverage statement and the assumptions the scan used.
IdempotencyKeyReusedError	class	409: an idempotency key spent on a different request.
InputTooLargeError	class	413: an input past its cap.
InvalidRequestError	class	400: a request of the wrong shape.
Job	class	A submitted job, for wait=False: read it, wait for it, stream it, or cancel it.
JobFailedError	class	A job that ended failed: no payload.
NotEntitledError	class	403: the key lacks a grant.
NotFoundError	class	404: no such object for this tenant.
OwaspEntry	class	One OWASP entry a finding realises: its list, its edition-qualified id, title and link.
PersonalDataError	class	A request bound for Stalwart's servers holds personal data, so nothing was sent.
PersonalDataFinding	class	One match: its kind (a key of KINDS) and where it is.
PlanItem	class	One step of a plan: a tool, ask, compute, decline or unread step, and the rule that made it.
QlsError	class	Every error the SDK raises.
QuotaExceededError	class	429 on a monthly meter: waiting will not help until it resets.
RateLimitError	class	429: a per-minute or per-stream limit.
RefusedError	class	409 refused: a combination of choices that cannot answer the question asked.
ReplayResult	class	replay_certificate, run by the service: replay is replayed, failed or out_of_scope.
Result	class	Every job's answer: the verdict, its caveats, its artefacts and the binary's own object.
Selection	class	The reader's answer to one instruction: the call, or the question to ask instead.
SelectorUnavailableError	class	Nothing here can answer a plan or a tool check: no licensed local runtime, and no router_url.
ServiceError	class	5xx, after the retries.
Session	class	A conversation over a Client.
StreamError	class	A stream that could not be resumed, by streaming or by polling.
ToolCheck	class	One tool call's answer: allow, confirm or refuse.
TurnPlan	class	A turn read into steps, with the session's next context.
__version__	value	The package's version: 1.0.
async_session_from_json	function	A session to_json wrote, restored over an async client.
check_certificate	function	Runs here, offline: checks a certificate on this machine with the vendored reference checker.
session_from_json	function	A session to_json wrote, restored over @p client.

stalwart_agents.langchain: for teams already on LangGraph

The router, the guarded tool node and the rest as LangChain middleware and LangGraph parts (chapter 27).

Name	Kind	What it is
Call	class	One call a stub recorded: the tool, its arguments, its place in the run, and whether a rollback made it as an undo.
Guard	class	Routing, the tool check and sagas for plain Python.
RespondingChatModel	class	Answers every call with what its function returns for the conversation so far.
ScriptedChatModel	class	Returns its script's messages in order, whatever it is asked.
StalwartFeedbackCallback	class	Remembers each run's turn and tool, and posts a thumb on it.
StalwartRouterMiddleware	class	Routes the latest user turn before the model is called.
StalwartToolGuardMiddleware	class	Checks every tool call before it runs, whoever chose it.
StubTools	class	The catalogue's tools as stubs, with the calls they recorded and the text planted in them.
__version__	value	The package's version: 1.0.
arguments_for	function	Arguments for a call to @p tool: each declared property, filled by its declared kind.
current_idempotency_key	function	The idempotency key of the write being made, inside a tool a guarded call runs; None outside one.
fixture_value	function	The smallest value of a JSON schema's type: what a stub returns for it.
register_catalogue	function	Registers @p tools as the tenant's catalogue: a new version, linted (POST /v1/catalogues).
tool_call	function	A model turn that calls one tool.
tool_definitions	function	The tools as LangChain tool definitions: name, description, argument schema and metadata.

stalwart_agents.gateway: the MCP gateway

The gateway that checks every tool call on its way to an MCP server (chapter 37).

Name	Kind	What it is
CONFIRMATION_UNAVAILABLE	value	The answer a confirmation gets where nobody can be asked.
Audit	class	Append-only decisions, one JSON object a line; in memory, and in a file where one is named.
Gateway	class	The enforcement point.
GatewayApp	class	The ASGI application in front of a Gateway.
GatewaySession	class	One MCP session: the agent it is for, the check's history, the labels it carries, the undo stack.
HttpUpstream	class	An MCP server over streamable HTTP, at @p url.
__version__	value	The package's version: 1.0.
gating_decision_id	function	The gating record's identity, computed byte for byte as the runtime's audit record computes it.