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's resource surface and naming (snake_case methods). All models are generated from the API's Zod contracts. A few surfaces differ slightly — e.g. agents.get returns the AgentView directly, and identity binding lives on the web app rather than the Python client.

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]
agent = sx.agents.get(agent_id)            # AgentView (unwrapped) — agent.id, agent.name, …
 
# 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="deploys")  # deploys | recent
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)         # BuyCreditsResult — checkout.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()

`sx.budgets`, `sx.spending` — Agent FinOps

# Cap one agent's monthly spend and BLOCK runs once it's exhausted.
budget = sx.budgets.create(
    name="Support bot — monthly",
    scope_type="agent",        # "org" | "project" | "agent"
    scope_id=agent_id,
    period_type="monthly",     # daily | weekly | monthly | rolling_30d | custom
    limit_credits=5000,
    enforcement="block",       # off | alert | block
    alert_threshold_pct=80,
)
status = sx.budgets.status(budget.id)   # .spentCredits / .remainingCredits / .usedPct / .state
 
by_agent = sx.spending.summary(group_by="agent", from_="-30d")  # SpendingRow[]
daily = sx.spending.trends(bucket="1d", from_="-30d")
trace = sx.spending.mesh_trace(root_run_id)                     # multi-hop cost

A "block" budget rejects an over-budget run or mesh hop with 402 server-side.

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

Python SDK

On this page