Python SDK

The runorca distribution is the Python client for the Agent Engine registry API. It provides synchronous and asynchronous clients for agents, sessions, environments, files, skills, vaults, memory stores, triggers, guardrails, model prices, and deployment-specific Cloud extensions. The public source repository and PyPI package are at version 0.3.0. Python 3.10 or later is required.

Install

pip install runorca==0.3.0

The distribution name is runorca; import the client from orca. If you installed an earlier Git version as orca-sdk, uninstall that distribution before installing runorca because both provide the orca import package. The orca-sdk name on PyPI belongs to a different project.

Configure the client

Set ORCA_BASE_URL to your registry's host root, without /v1. For the default Orca() constructor, set ORCA_API_KEY to a Bearer token accepted by your deployment. If you use a Workspace API key, use the x-api-key example below. See Get your registry endpoint for the endpoint and self-hosted authentication for key setup.

export ORCA_BASE_URL="https://<registry-host>"
export ORCA_API_KEY="<bearer-token>"

from orca import Orca

client = Orca()

Orca() reads those environment variables. You can also pass api_key and base_url explicitly. The client sends api_key as Authorization: Bearer; a callable api_key can supply a fresh token for each request. Set api_key=None to omit the Authorization header when another header or proxy handles authentication. Both Orca and AsyncOrca accept timeout, max_retries, and default_headers options.

For a Workspace API key, pass it in x-api-key and disable the Bearer header. This configuration was verified against a Kubernetes registry with a provider-backed session:

import os
from orca import Orca

client = Orca(
    base_url=os.environ["ORCA_BASE_URL"],
    api_key=None,
    default_headers={"x-api-key": os.environ["ORCA_API_KEY"]},
)

Create an agent and run a session

The synchronous client returns typed resources. Create an environment and agent before starting a session:

environment = client.environments.create(name="quickstart-env")
agent = client.agents.create(name="quickstart-agent", model="claude-sonnet-4-6")

session = client.sessions.create(agent=agent.id, environment_id=environment.id)
client.sessions.events.send(
    session.id,
    events=[{"type": "user.message", "content": [{"type": "text", "text": "Hello"}]}],
)

for event in client.sessions.events.stream(session.id):
    print(event.type)
    if event.type == "session.status_idle":
        break

For asynchronous code, use AsyncOrca. Its methods have the same arguments:

import asyncio
from orca import AsyncOrca

async def main() -> None:
    client = AsyncOrca()
    async for agent in client.agents.list():
        print(agent.id)

asyncio.run(main())

Pagination and extensions

List methods return pages that iterate across page boundaries. Use .data and .next_page when you need one page at a time:

for agent in client.agents.list():
    print(agent.id)

page = client.agents.list(limit=20)
print(page.data, page.next_page)

The client.guardrails and client.model_prices namespaces use the policy and pricing API groups. Hosted integrations live under client.cloud.*. The SDK checks API discovery before using an extension and raises ExtensionNotAvailableError when the deployment does not advertise it. See the SDK's API surface for the available methods and return types.

What's next