Skip to main content

Recursion Python SDK

Typed, synchronous and asynchronous request/response access to the Recursion API. The client and Pydantic models are generated from Recursion's committed public OpenAPI contract snapshots. Session-event and gestalt streaming are excluded.

The distribution is labelbox-recursion-sdk, and the Python import is recursion_sdk. This implementation starts at version 0.1.0; earlier releases contain the retired SDK and its different import/API. Build a wheel from this checkout to try the implementation before its first release. Versions remain below 1.0 while the public API evolves.

import os

from recursion_sdk import Recursion

with Recursion(api_key=os.environ["RECURSION_API_KEY"]) as recursion:
    result = recursion.managed_agents.list_sessions()
    print(result.data, result.response.headers.get("etag"))

AsyncRecursion exposes the same methods as coroutines and supports async with. The production base URL is https://api.recursion.labelbox.com. Set organization_id or tenant_id on the constructor when the API key requires those selectors. Operation-level selectors may repeat those values; they cannot change the constructor's scope.

The agent, agent-version, vault, credential, memory-list, agent-template, environment, setup-run, environment-template, sandbox-provider, and session discovery/overview read methods use /managed-agents/v2 by default. For example, managed_agents.list_agents(limit=50, cursor=...) returns the v2 page with items, nextCursor, and total; managed_agents.list_environments(limit=50, cursor=...) returns items and nextCursor; and managed_agents.list_sessions(limit=50, cursor=...) returns items, nextCursor, and a nullable total. The explicit *_v2 names remain available; use *_v1 to call the deprecated legacy endpoints and receive their legacy shapes. Those calls emit DeprecationWarning and their docstrings point to the v2 replacement. Skill and skill-group methods also use v2 by default, including the camelCase request and response models; their explicit *_v1 methods retain the deprecated legacy contracts. Other Managed Agents methods use the version declared by the public contract.

Methods return ApiResponse with typed data and the original HTTPX response, including status and headers. A declared bodyless 304 has data=None. Declared API errors raise RecursionAPIError; malformed or undeclared responses raise RecursionContractError. HTTPX transport failures retain their HTTPX exception types. Request and response values are validated against the canonical schemas, including constraints beyond Pydantic's model annotations.

JSON methods accept generated models from recursion_sdk.models, with snake_case attributes and canonical JSON field aliases. Omitted model fields stay omitted; explicitly supplied None becomes JSON null where the contract permits it. Multipart methods accept Upload values, and binary download methods return bytes. The client has no automatic retries or pagination; callers retain control of mutation replay and iteration.

Refresh active outcomes during an upgrade

The single-session and bulk upgrade methods accept replaceActiveOutcome: true in their JSON body. It reapplies the target version's default rubric to an active outcome, including a caller-defined outcome or a session already running that version:

import os
from uuid import UUID

from recursion_sdk import Recursion, models

with Recursion(api_key=os.environ["RECURSION_API_KEY"]) as recursion:
    recursion.managed_agents.replace_session_agent_version(
        session_id=UUID("e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53"),
        body=models.ReplaceSessionAgentVersionRequest.model_validate({
            "agentVersionId": "5a0c8e37-1f94-4b2d-a6c3-7e9d2b4f8a15",
            "replaceActiveOutcome": True,
        }),
    )
    recursion.managed_agents.start_agent_session_upgrade(
        agent_id=UUID("7b1e4c2a-9d35-4f86-a0c7-5e2d8b3f6a14"),
        idempotency_key="refresh-active-outcomes-1",
        body=models.StartAgentSessionUpgradeRequest.model_validate({
            "replaceActiveOutcome": True,
        }),
    )

While a bulk upgrade is running, a different replaceActiveOutcome policy returns 409 conflict; the running upgrade keeps the policy it accepted.

AsyncRecursion exposes the same calls with await. The bulk body is optional; leave it out for the usual version-only request. Without the option, inherited default outcomes follow the version and caller-defined outcomes stay. Explicit replacement requires a nonempty default rubric, preserves the objective and pass limit, and retains the prior outcome and grading history as interrupted. An evaluation in progress finishes before replacement; terminal outcomes stay unchanged. A successful upgrade response acknowledges the request. Verify the active criteria with managed_agents.list_session_outcomes after the session's next model operation.

Development

All Python tooling uses uv. Run these commands from the repository root through the worktree's devbox:

./devbox exec -- yarn check recursion:python-sdk

The package's uv wrapper reuses uv on PATH or installs a checksum-verified, pinned copy under the worktree's .local/ directory on a Linux devbox. Other hosts can use an existing uv installation. Nothing is installed globally.

The check command generates, checks formatting, runs strict typing and behavioral tests, verifies deterministic generation, builds wheel/sdist artifacts, and checks an isolated installation of the wheel with hashed runtime dependencies from uv.lock. Generated files under src/recursion_sdk/_generated/ are ignored; change the public contract or generator inputs and rerun the check. It runs tools/check.py through uv with the materialized preview contract.

Python dependencies and generated outputs belong to this independent package. Root Yarn installation, postinstall, JavaScript code generation, and ordinary application checks do not install or run Python tooling. Dedicated CI runs when this package or the canonical Recursion public contract changes.

Generation and ownership

datamodel-code-generator compiles schemas into Pydantic v2 models. A small operation emitter produces typed methods and bundles the unmodified canonical contract. One shared HTTPX transport owns wire behavior and uses JSON Schema validation at its boundaries. No endpoint or request/response model is maintained by hand, and generation requires no JVM or hosted service.

Generation binds the exact preview audience served by production: the public contract source recursion-public-openapi.preview.generated.json without its x-recursion-stability markers. yarn ci check recursion:python-sdk and release qualification materialize those bytes and pass their path in RECURSION_PYTHON_SDK_CONTRACT_PATH; the generator requires it and rejects a marked source.

Build after generation, then add the wheel to your application's uv project:

uv build --project packages/recursion-python-sdk
uv add --project /absolute/path/to/your-python-project /absolute/path/to/labelbox_recursion_sdk-0.0.0-py3-none-any.whl

Published releases reuse the existing labelbox-recursion-sdk PyPI project. The source version 0.0.0 identifies local preview builds; the release process stamps the requested version into release artifacts. The TypeScript SDK release process is independent.

Release

Releases are proposed on Tuesdays and Thursdays and announced in #recursion-info while they wait for approval: publishing runs in the recursion-sdk-pypi environment, which requires an approval from the recursion team, and the run refuses to publish if it has none. Approving and yanking a bad release: client package releases.

The Python release workflow builds and qualifies an explicit version. Its default run only uploads artifacts:

gh workflow run release-python-sdk.yml --ref main -f version=0.1.0

The SDK code comes from the workflow's commit. By default, its API contract does too. When main contains API changes that have not reached production, set PYTHON_SDK_CONTRACT_SOURCE_SHA to a deployed commit's full SHA and select its contract explicitly:

gh workflow run release-python-sdk.yml --ref main -f version=0.1.0 -f contract-source-sha="$PYTHON_SDK_CONTRACT_SOURCE_SHA" -f publish=true

The contract source must be a full commit SHA in the workflow commit's ancestry. The release extracts that commit's production contract without modifying any tracked snapshot. Generation, behavioral tests, and strict production verification all consume those exact bytes. Newer API changes on main can therefore coexist with a release for the deployed API. The artifact manifest records the SDK source commit, contract source commit, snapshot path, and hash.

For a local build without publishing, use an ignored artifact directory from a clean checkout:

yarn release python-sdk:prepare --version 0.1.0 --artifact-dir "$PWD/.agent/python-sdk-release"

The local command also accepts --contract-source-sha <full-commit-sha> and --verify-production true for the same source selection and production check without uploading anything.

The release command rejects published/older versions, temporarily stamps the package and lockfile, runs the full qualification, and restores the source metadata. The immutable candidate contains the wheel, source distribution, checksums, and its source commit.

Passing -f publish=true to the workflow additionally verifies the source contract in production and publishes those exact archives with uv publish through PyPI trusted publishing. Its publisher identity is repository Labelbox/recursion-platform, workflow release-python-sdk.yml, environment recursion-sdk-pypi, project labelbox-recursion-sdk. The final job verifies PyPI's archive hashes before recording python-sdk-v<version> at the source commit. Publication and Git tagging have separate credentials; release runs never commit version changes to the branch.

Metadata

Release files for labelbox-recursion-sdk 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for labelbox-recursion-sdk 0.1.1
File Size Uploaded Provenance Actions
labelbox_recursion_sdk-0.1.1.tar.gz 558.4 kB Without provenance Details for labelbox_recursion_sdk-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for labelbox-recursion-sdk 0.1.1
File Interpreter ABI Platform Actions
labelbox_recursion_sdk-0.1.1-py3-none-any.whl Python 3 none any Details for labelbox_recursion_sdk-0.1.1-py3-none-any.whl

Total release size: 1.1 MB

Release files / labelbox_recursion_sdk-0.1.1.tar.gz

Download URL labelbox_recursion_sdk-0.1.1.tar.gz
Size 558.4 kB
Tags Source
SHA-256 checksum
How to use checksums
a6667316f908f1b16b7d1bfa6fc22f7f8e41c02c030d9877f75ac190b68fde52
BLAKE2b-256 checksum
How to use checksums
821190724a6d8bf332ac1fa0d1f13b0f78515850baffe59c5a4851199aa02afa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.14 {"installer":{"name":"uv","version":"0.12.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / labelbox_recursion_sdk-0.1.1-py3-none-any.whl

Download URL labelbox_recursion_sdk-0.1.1-py3-none-any.whl
Size 536.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4d8db2066466f21cb6bd177db5df40b886db36aed0d9b766819a503543d89c39
BLAKE2b-256 checksum
How to use checksums
abb281cd37df68d70616442f4130f47f3f05a1c9481b9452a599c787f6aefa35
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.14 {"installer":{"name":"uv","version":"0.12.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for labelbox-recursion-sdk 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page