Python SDK

The Swytchcode Python SDK provides a simple way to execute trusted tools directly from your Python applications.

Open source: runtime-py on GitHub

Rather than building HTTP requests, managing authentication, or implementing retry logic yourself, you call a single function and let the Swytchcode CLI handle execution.

The Python runtime is intentionally lightweight - it acts as a thin wrapper around the Swytchcode CLI while providing a Python-native developer experience.

---

Before you begin

Before using the Runtime SDK, make sure you have:

• Installed the Swytchcode CLI
• Authenticated your Swytchcode account (swy login)
• Initialized a Swytchcode project (swy init)
• Fetched at least one integration bundle (swy get <project>)
• Enabled the tools you want your application to execute (swy add <canonical_id>)

The runtime shells out to the same CLI, so it only executes tools that are already enabled in your project’s tooling.json - it doesn’t discover or install integrations for you. If you haven’t completed those steps yet, start with the CLI Quickstart.

---

Installation

Install the runtime using pip.

pip install swytchcode-runtime

The Swytchcode CLI must also be installed on your machine.

The runtime automatically locates the CLI binary in most environments, with optional overrides available if needed. See the CLI overview for installation and runtime setup.

---

Your First Tool

Import the runtime and execute any trusted tool.

from swytchcode_runtime import exec

result = exec(
    "github.issue.create",
    {
        "body": {
            "title": "Update documentation",
            "body": "The JavaScript SDK guide needs an update."
        },
        "params": {
            "owner": "swytchcodehq",
            "repo": "docs"
        }
    }
)

print(result)

By default, the runtime returns parsed JSON.

Under the hood, this executes the equivalent Swytchcode CLI command and returns the response directly to your application.

---

Request Structure

Requests follow a consistent structure.

exec(
    "github.issue.create",
    {
        "body": {
            ...
        },
        "params": {
            ...
        },
        "headers": {
            ...
        }
    }
)

Common fields include:

Field	Description
body	HTTP request body
params	Path or query parameters
headers	Additional request headers
Authorization	Optional authorization header

Additional top-level fields are passed as query parameters.

---

Raw Output

If you need the raw response instead of parsed JSON, enable raw mode.

from swytchcode_runtime import exec

output = exec(
    "api.report.export",
    {
        "id": "123"
    },
    raw=True
)

print(output)

---

Error Handling

Execution failures raise a SwytchcodeError.

from swytchcode_runtime import (
    exec,
    SwytchcodeError
)

try:
    result = exec(
        "github.issue.create",
        {
            "body": {
                "title": "Bug report"
            }
        }
    )

except SwytchcodeError as error:
    print(error.message)

Errors include structured information such as:

• Authentication failures
• Policy violations
• Validation errors
• Provider responses
• Suggested actions

This makes it easy to build reliable applications without parsing CLI output yourself.

---

Authentication

The Python runtime does not implement its own authentication layer.

Instead, it relies on the Swytchcode CLI, which automatically resolves credentials before execution.

This means your application benefits from:

• Account authentication
• Managed provider credentials
• Environment variable support
• Automatic credential resolution

No additional authentication code is required in your Python application. Learn more in the Managed Authentication

---

Run this example

Use the full Anthropic agent example from the Anthropic Quickstart to exercise the runtime end-to-end. The quickstart includes one-time setup (swy init, swy get github, swy add method github.user.starred.update, swy auth connect github) plus the complete Python example that loops on tool_use calls.

Save the example as main.py, make sure your .env contains ANTHROPIC_API_KEY, then run it:

python main.py

---

Automatic Runtime Features

Every tool execution automatically includes:

• Input validation
• Policy evaluation
• Authentication
• Retry handling
• Timeout management
• Idempotency
• Response normalization

These behaviors are configured by your Swytchcode project and require no additional code.

---

Agent Framework Support

The Python runtime also provides integrations for popular AI frameworks.

Supported providers include:

• OpenAI Agents SDK
• Anthropic SDK
• Vercel AI SDK
• LangGraph
• CrewAI

Each provider exposes Swytchcode tools in the format expected by the framework, allowing your agents to execute trusted tools with minimal setup.

---

Best Practices

• Install and authenticate the Swytchcode CLI before using the runtime.
• Keep provider credentials outside your application code.
• Execute trusted tools instead of making raw HTTP requests.
• Let the runtime manage retries, authentication, and execution behavior.
• Test new integrations in sandbox mode before using them in production.

---

Next Steps

JavaScript SDK

Compare the same runtime model in JavaScript and TypeScript.

CLI overview

Understand the command-line runtime and how it integrates with SDK usage.

Managed Authentication

Learn how provider credentials are resolved securely.

Execution Pipeline

See the full lifecycle of tool execution.