Python SDK

Install and use the silvanexum package — a typed, pydantic-based client for Python 3.9+.

silvanexum is the official Python client. It targets Python ≥ 3.9, returns fully typed pydantic v2 models, and mirrors the TypeScript SDK method-for-method. All models are generated from the API's Zod contracts.

The client is synchronous today (built on httpx). An async client is on the roadmap.

Install

pip install silvanexum
# uv add silvanexum · poetry add silvanexum

Construct the client

from silvanexum import Silvanexum
 
sx = Silvanexum(
    api_key="sx_live_...",                  # default: env SILVANEXUM_API_KEY
    base_url="https://api.silvanexum.com",  # default: env SILVANEXUM_BASE_URL or prod
    timeout=60.0,                            # per-request timeout (seconds)
    max_retries=2,                           # retries 429 / 5xx / connection errors
)

It's also a context manager, which closes the underlying HTTP connection pool:

with Silvanexum() as sx:        # reads SILVANEXUM_API_KEY from the env
    agents = sx.agents.list()

Errors

Every failure raises a subclass of SilvanexumError carrying status, code, body, and request_id.

from silvanexum import (
    SilvanexumError,
    AuthenticationError,       # 401
    PermissionError,           # 403 — key missing a scope
    ValidationError,           # 400 / 422
    NotFoundError,             # 404
    InsufficientCreditsError,  # 402
    RateLimitError,            # 429 (already retried with backoff)
    InternalServerError,       # 5xx
)
 
try:
    sx.runs.create(agent_id=agent_id, prompt="...")
except InsufficientCreditsError:
    ...  # top up credits, then retry
except SilvanexumError as err:
    print(err.status, err.code, err.request_id, err.message)

`sx.agents`

agents = sx.agents.list()                  # List[AgentView]
resp = sx.agents.get(agent_id)             # {"agent": ..., "myRating": ...}
 
# create()/update() forward kwargs verbatim as JSON — use the API's camelCase
# field names for nested config and list fields.
created = sx.agents.create(
    name="Support Triage",
    description="Triages inbound tickets.",
    config={"provider": "anthropic", "model": "claude-opus-4-8", "systemPrompt": "You triage support tickets."},
    connectorIds=[],
)
 
sx.agents.publish(created.id)
sx.agents.fork(other_agent_id)
sx.agents.rate(agent_id, 5)
sx.agents.lineage(agent_id)
sx.agents.delete(created.id)

`sx.agents.versions` — signed M01 versions

v = sx.agents.versions.publish(agent_id, semver="1.0.0", changelog="First release")
sx.agents.versions.promote(agent_id, "1.0.0")
result = sx.agents.versions.verify(agent_id, "1.0.0")   # {"valid": True, ...}
sx.agents.versions.list(agent_id)

`sx.runs`

run = sx.runs.create(agent_id=agent_id, prompt="...")   # captured + signed
again = sx.runs.rerun(execution_id=run.id)
full = sx.runs.get(run.id)
for step in full.trace:
    print(step.kind, step.name, step.status)
 
sx.runs.set_visibility(run.id, "public")
print(sx.runs.share_url(run.id))   # https://silvanexum.com/runs/...

`sx.templates` (M11)

Template endpoints are part of the M11 P0 spec and may be planned (not yet live) on your deployment — see the API reference.

templates = sx.templates.list(vertical="support", sort="runs")
detail = sx.templates.get(templates[0].id)
agent = sx.templates.deploy(detail.id, params={"tone": "concise"}, idempotency_key="...")

`sx.connectors`

c = sx.connectors.create(provider_config_key="github", display_name="GitHub")
session = sx.connectors.session(c.id)          # hand sessionToken to Nango Connect
connected = sx.connectors.confirm(c.id, connection_id)
sx.agents.update(agent_id, connectorIds=[connected.id])

`sx.marketplace`, `sx.wallet`, `sx.suites`, `sx.keys`, `sx.models`, `sx.team`

results = sx.marketplace.search(q="legal", sort="proof")
purchase = sx.marketplace.purchase(results[0].id, idempotency_key="...")
 
wallet = sx.wallet.get()
checkout = sx.wallet.buy_credits(1000)         # {"checkoutUrl": ...}
 
run = sx.suites.run(suite_id)                  # run.status is the pass/fail gate
ok = sx.keys.validate("openai", "sk-...")
models = sx.models.live("anthropic")
members = sx.team.list_members()

Models are importable for type hints: from silvanexum import models → models.AgentView, models.ExecutionView, etc.

On this page