everruns-sdk 0.2.0

Python SDK for Everruns API

Everruns SDK for Python

Python SDK for the Everruns API.

Installation

pip install everruns-sdk

Quick Start

import asyncio
from everruns_sdk import Everruns

async def main():
    # Uses EVERRUNS_API_KEY and optional EVERRUNS_ORG_ID environment variables
    client = Everruns()
    
    # Create an agent
    agent = await client.agents.create(
        name="Assistant",
        system_prompt="You are a helpful assistant.",
    )
    
    # Create a session
    session = await client.sessions.create(agent_id=agent.id)
    
    # Send a message
    await client.messages.create(session.id, "Hello!")
    
    # Stream events
    async for event in client.events.stream(session.id):
        if event.type == "output.message.completed":
            print(event.data)
            break
    
    await client.close()

asyncio.run(main())

Agent Harness

Each agent owns a harness. Set it on create/update with harness_name (preferred) or harness_id (mutually exclusive); omit both to default to the org's generic harness. A session created from the agent runs on the agent's harness.

# Create an agent on a specific harness
agent = await client.agents.create(
    name="researcher",
    system_prompt="You do deep research.",
    harness_name="deep-research",
)

# Agent-first session: no harness needed — it runs on the agent's harness
session = await client.sessions.create(agent_name="researcher")

Harnesses & Models

Discover and manage harnesses, and browse available models to choose a default_model_id.

# Browse harnesses, then create one
harnesses = await client.harnesses.list()          # or .search("research")
harness = await client.harnesses.get(harnesses[0].id)
custom = await client.harnesses.create(
    name="my-harness",
    system_prompt="Base instructions for every session.",
)
examples = await client.harnesses.list_examples()

# List models to pick a default for an agent
models = await client.models.list()

Initial Files

from everruns_sdk import Everruns, InitialFile

client = Everruns()

session = await client.sessions.create(
    agent_id="agent_...",
    initial_files=[
        InitialFile(
            path="/workspace/README.md",
            content="# Demo Project\n",
            encoding="text",
            is_readonly=True,
        ),
        InitialFile(
            path="/workspace/src/app.py",
            content='print("hello")\n',
            encoding="text",
        ),
    ],
)

Runnable example: examples/initial_files.py

Authentication

The SDK uses personal access token authentication. Set EVERRUNS_API_KEY or pass the token explicitly. For personal access tokens with access to multiple organizations, set EVERRUNS_ORG_ID or pass org_id explicitly:

# From environment
client = Everruns()

Or with an explicit token and organization:

client = Everruns(api_key="evr_pat_...", org_id="org_...")

Agent Versions

version = await client.agents.create_version(
    "agent_...",
    change_kind="manual",
    summary="Baseline",
)

versions = await client.agents.list_versions("agent_...")
diff = await client.agents.diff_versions("agent_...", "agentver_1", version.id)
fork = await client.agents.fork_version(
    "agent_...",
    version.id,
    name="forked-agent",
)
rollback = await client.agents.rollback_version(
    "agent_...",
    version.id,
    save_version=True,
)

Workspaces

Workspaces hold files shared across sessions.

workspace = await client.workspaces.create(name="team-docs")

await client.workspace_files.create(
    workspace.id,
    "/notes/welcome.md",
    "# Welcome\n",
    encoding="text",
)
file = await client.workspace_files.read(workspace.id, "/notes/welcome.md")
files = await client.workspace_files.list(workspace.id, recursive=True)

Runnable example: examples/workspaces.py

Memories

Memories are long-term, searchable knowledge stores for agents.

memory = await client.memories.create(name="product-knowledge")

await client.memories.create_file(
    memory.id,
    "/facts/product.md",
    "# Product\n",
    encoding="text",
)
results = await client.memories.grep_files(memory.id, "product")
await client.memories.sync(memory.id)

Runnable example: examples/memories.py

License

MIT