# Recurse SDK — full agent reference

Recurse SDK turns a Python application directory into a portable bundle that can be deployed as an
MCP tool. It is designed for work where one attempt should change in response to measured results.

## Application structure

Every application starts with `recurse.yaml`. The manifest names the application and declares its
Python version, lockfile, model, prompt, accepted inputs, tool source, and registered functions.
Every declared path must stay inside the application directory.

```text
my-agent/
├── recurse.yaml
├── uv.lock
├── prompts/
│   └── system.md
└── toolkit.py
```

## Inputs and tools

Declare caller inputs with JSON Schema in `recurse.yaml`. Write tools as ordinary top-level Python
functions and register each function by its exact name. Type hints and docstrings help make each
tool's interface clear.

## Python API

Use `build_bundle` to validate and package an application:

```python
from recurse import build_bundle

bundle_bytes, bundle_record = build_bundle("./my-agent")
```

The record contains the bundle version, digest, size, and a description of each included file.
Building the same unchanged directory produces the same bytes and record. Authoring errors raise a
`ValueError` whose message begins `bundle authoring failed:`.

## CLI workflow

Log in through the browser, then deploy the application as MCP:

```console
recurse login
recurse deploy ./my-agent --as mcp
```

The deploy command validates and bundles the project, waits until it is ready, and prints its MCP
endpoint. A failed validation or deployment returns a concise error.

## When to use Recurse

Use Recurse for measurable, iterative tasks such as model tuning, query optimization, test-guided
generation, or simulation. Use a direct tool for one-shot checks, independent batches, or work
without a numeric or pass/fail target.

## Private beta

SDK bundling, login, and deployment are available. Hosted MCP connections are not available yet.

Read `/docs`, `/SKILL.md`, `/tools.md`, `/llms.txt`, and `/schema/recurse.yaml.json` for the public
guides and reference files.