Savine Documentation

Python SDK Reference ​

The official Python client library for the Savine API. Contains typed models, automatic retries, and convenience methods for polling/streaming asynchronous tasks.

Installation ​

bash
pip install savine-sdk

Requires Python 3.8+

Initialisation ​

The client looks for the SAVINE_API_KEY environment variable by default.

python
import os
from savine import Savine

# Auto-detects SAVINE_API_KEY from env
client = Savine()

# Explicit initialisation
client = Savine(api_key=os.environ.get("MY_SAVINE_KEY"))

Async Client ​

For high-concurrency environments like FastAPI or background workers:

python
from savine import AsyncSavine
import asyncio

async def run():
    client = AsyncSavine()
    response = await client.agents.list()

Agents ​

client.agents.list() ​

Returns a list of Agent objects.

python
agents = client.agents.list(limit=20)
for agent in agents:
    print(agent.name, agent.status)

client.agents.get(agent_id: str) ​

Retrieves a specific agent.

client.agents.deploy(config: dict | str) ​

Deploys a new agent or updates an existing one (creates a new version). Can accept a Python dictionary or a filepath to your agent.json.

python
agent = client.agents.deploy("config/researcher.agent.json")

Tasks ​

client.tasks.submit(agent_id: str, input: str) ​

Submits a task asynchronously. Returns a Task object mapping in a QUEUED state.

python
task = client.tasks.submit("researcher-v2", "Search for LLM benchmark news.")

client.tasks.wait(task_id: str, timeout: int = 300) ​

Blocking function that polls the API until the task is COMPLETED or FAILED. Returns the final TaskResult object strings.

python
result = client.tasks.wait(task.id)
print(result.output)

client.tasks.stream(task_id: str) ​

Returns a Python generator yielding ExecutionStep objects live via Server-Sent Events.

python
for step in client.tasks.stream(task.id):
    if step.type == "THINK":
        print(f"Thinking for {step.duration_ms}ms")
    elif step.type == "TOOL_CALL":
        print(f"Executing {step.content.tool_name}...")

Systems ​

client.systems.deploy(manifest: dict | str) ​

Deploys a multi-agent system based on system.json.

client.systems.run(slug: str, input: str) ​

Submits input against the entry node of a system graph. Returns a SystemRun object.

Complete Example ​

A fully working script deploying an agent, firing 5 parallel tasks, and calculating costs.

python
import asyncio
from savine import AsyncSavine

async def main():
    client = AsyncSavine()
    
    agent = await client.agents.deploy("agent.json")
    print(f"Deployed {agent.name}")

    topics = ["AGI timelines", "Solid state batteries", "Nuclear fusion", "Mars colony", "Quantum computing"]
    
    # Fire tasks in parallel
    tasks = await asyncio.gather(*[
        client.tasks.submit(agent.id, f"Summarize {topic}") for topic in topics
    ])

    # Wait for completion
    results = await asyncio.gather(*[
        client.tasks.wait(t.id) for t in tasks
    ])

    total_cost = sum(res.metrics.cost_usd for res in results)
    
    for topic, res in zip(topics, results):
        print(f"✅ {topic}: {len(res.output)} chars")
    
    print(f"\nTotal Run Cost: ${total_cost:.4f}")

asyncio.run(main())