# 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](https://github.com/swytchcodehq/runtime-py)

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](/quickstarts/getting-started/cli-only/).

---

## Installation

Install the runtime using pip.

```bash
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](/cli/overview/) for installation and runtime setup.

---

## Your First Tool

Import the runtime and execute any trusted tool.

```python
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.

```python
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.

```python
from swytchcode_runtime import exec

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

print(output)
```

---

## Error Handling

Execution failures raise a `SwytchcodeError`.

```python
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](/guides/managed-authentication/)

---

### Run this example

Use the full Anthropic agent example from the [Anthropic Quickstart](/quickstarts/anthropic-sdk/) 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:

```bash
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](https://docs.swytchcode.com/runtime-sdk/javascript/) - Compare the same runtime model in JavaScript and TypeScript.
- [CLI overview](https://docs.swytchcode.com/cli/overview/) - Understand the command-line runtime and how it integrates with SDK usage.
- [Managed Authentication](https://docs.swytchcode.com/guides/managed-authentication/) - Learn how provider credentials are resolved securely.
- [Execution Pipeline](https://docs.swytchcode.com/guides/execution-pipeline/) - See the full lifecycle of tool execution.