Skip to main content

qontain (Python SDK)

For agents running under the qontain runtime. Standard library only, Python 3.10+.

  • Broker: calls brokered tools, sends messages on declared wires, and builds egress URLs. Broker refusals raise typed errors.
  • Agent: HTTP server for the agent's ports, with /health built in and a receiver for each wire channel.
from qontain import Agent, Broker, BudgetExceeded, PolicyDenied

broker = Broker.from_env()  # QONTAIN_BROKER, optional QONTAIN_BROKER_TOKEN
agent = Agent("researcher", port=8080)

@agent.route("/research")
def research(body):
    try:
        hits = broker.call_tool("web-search", {"q": body["topic"]})
    except BudgetExceeded:
        return {"error": "tool budget used up"}
    broker.send("findings", {"topic": body["topic"], "hits": hits})
    return {"ok": True}

@agent.channel("reviews")
def on_review(message, source_agent):
    return {"ack": True}

agent.serve()

LLM SDKs need no changes: qontain sets ANTHROPIC_BASE_URL and OPENAI_BASE_URL to the broker. For other APIs use broker.egress_url("api.example.com", "v1/items").

Error Broker status Meaning
BrokerAuthError 401 Missing or wrong QONTAIN_BROKER_TOKEN
PolicyDenied 403 Host, tool or channel not allowed for this agent
ReplayDivergence 409 Strict replay has no recorded response to this request (detail["differed"] says why)
ReplayExhausted 410 No more recorded responses in replay mode
SchemaViolation 422 Message fails the wire's JSON schema (detail has the reason)
BudgetExceeded 429 Token, cost or tool-call budget used up
ToolUnavailable 501 No backend registered for the tool on the host
UpstreamError 502 Tool backend or receiving agent failed
BrokerUnavailable 503 Circuit breaker tripped

All of these subclass BrokerDenied (is_denial is true) and BrokerError, which is also raised as-is for error statuses that did not come from broker policy. BrokerTransportError (status is None) means the broker could not be reached or did not answer within timeout; Broker.from_env() raises BrokerNotConfigured (also a RuntimeError) when QONTAIN_BROKER is unset.

The broker token is sent as X-Qontain-Token, so Authorization stays free for the agent's own API keys. call_tool(name) with no arguments sends JSON null.

A channel receiver runs only for deliveries the broker signed with this agent's QONTAIN_WIRE_KEY (set by qontain; Agent(..., wire_key=...) overrides it) within the last 300 seconds and not seen before; anything else gets 401, so a local process posting to the agent's port cannot pose as another agent. Without a key every delivery is refused. Plain routes are not signed: anything that can reach the port can call them.

Agent routes on the path without its query string, answers request bodies over 8 MiB with 413 and a bad Content-Length with 400. Raise AgentError(status, message) from a handler to reply with that status; any other exception is logged (logger qontain.agent) and the caller gets a 500 with a generic message.

The three SDKs side by side:

Python TypeScript Rust (qontain-sdk)
Request handler @agent.route(path) agent.route(path, fn) AgentBuilder::handler(path, fn)
Wire receiver @agent.channel(name) agent.channel(name, fn) AgentBuilder::channel(name, fn)
Handler failure raise AgentError(status, msg) throw new AgentError(status, msg) return Err(AgentError::new(status, msg))
Bind, then serve agent.server(host, port) await agent.listen(port, host) agent.bind().await? then .serve()
Denial check isinstance(e, BrokerDenied) / e.is_denial e instanceof BrokerDenied / e.isDenial BrokerError::Denied / e.denial()
Transport failure BrokerTransportError BrokerTransportError BrokerError::Transport
No broker configured BrokerNotConfigured BrokerNotConfigured BrokerError::NotConfigured

Python and TypeScript raise one class per denial status; Rust uses BrokerError::Denied { kind: DenialKind, .. }.

Tests: PYTHONPATH=src python -m unittest discover -s tests

Metadata

Release files for qontain 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qontain 0.1.0
File Size Uploaded Provenance Actions
qontain-0.1.0.tar.gz 18.0 kB Without provenance Details for qontain-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qontain 0.1.0
File Interpreter ABI Platform Actions
qontain-0.1.0-py3-none-any.whl Python 3 none any Details for qontain-0.1.0-py3-none-any.whl

Total release size: 32.8 kB

Release files / qontain-0.1.0.tar.gz

Download URL qontain-0.1.0.tar.gz
Size 18.0 kB
Tags Source
SHA-256 checksum
How to use checksums
a68400eaea8f6163119013f4a5bf997b878008ab132146a6ef841d9b92a15d31
BLAKE2b-256 checksum
How to use checksums
2ba698ddeca4c9c58066cf2dc8edcc6d940dc18e28990fb1178077c2c13a7824
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Release files / qontain-0.1.0-py3-none-any.whl

Download URL qontain-0.1.0-py3-none-any.whl
Size 14.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
315ccb459afeeb1d428724a417ef403408cecdbb5a3c86debc6a2ce31b9c2737
BLAKE2b-256 checksum
How to use checksums
f953206c7db44375d08eacf5dc08e2898562de1968f250e61bab2189b194f00a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Security for qontain 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page