Project files and dependencies

Your coding agent prepares a complete project for each Recurse agent. You may want to review the contents to see which dependencies the project uses, and go through a security checklist before serverless execution to make sure the project directory includes no secrets or sensitive information.

Recurse builds a Python source distribution from that project. The package must contain the manifest, prompt, tools, exact dependency lockfile, and every additional file the tools require at runtime. If a necessary file is not in the package, the serverless run cannot use it.

Review the project layout

A small Recurse agent can start with this layout:

my-agent/
├── agent.yaml
├── prompt.md
├── tools.py
├── pyproject.toml
└── uv.lock

Prompt and tool filenames can differ. Their manifest paths must point to files inside the project directory. The current runtime declaration is runtime.python: "3.14" and the mandatory lockfile is uv.lock.

Keep dependencies reproducible

Your coding agent declares runtime dependencies in pyproject.toml and updates uv.lock after a dependency changes. If the tools import recurse, the project needs recurse-sdk as a dependency.

The underlying command is:

uv lock

Packages that exist in a local environment do not become part of the Recurse agent's package.

Review what travels with the Recurse agent

The build backend selects the source archive's contents. Your coding agent can use a hatchling configuration like this for the five-file layout above:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.sdist]
include = ["agent.yaml", "prompt.md", "tools.py", "uv.lock"]

[tool.hatch.build.targets.wheel]
include = ["agent.yaml", "prompt.md", "tools.py"]

The coding agent must add local modules, templates, datasets, and other runtime assets when the tools require them. A file that exists in the development checkout but is absent from the source archive will not be available during serverless execution.

Before authorizing a run or deployment, review the package file list. Confirm that it excludes:

• Credentials, tokens, and local environment files.
• Large datasets.
• Build outputs and caches that the runtime does not require.
• Irrelevant files, or leftovers from previous iterations that are no longer relevant to the project.
• Files whose licenses or data-handling rules do not permit uploading.

Use Use secrets for credential values. Do not place them in the project, manifest, prompt, lockfile, or source archive.

Keep paths portable

Manifest paths are relative to the Recurse agent's project directory. They should not use absolute paths, .., backslashes, or machine-specific locations. Code should resolve any assets relative to the module or workspace rather than the working directory of the CLI.

Before serverless execution, your coding agent should perform a clean build and test the package. Testing only from the development checkout may not catch missing dependencies or files before a billable run.

Debugging packaging issues

When debugging packaging issues, ask your coding agent to verify:

1. The source archive's file list.
2. The package and lockfile checks.
3. A clean-environment import or local tool test.
4. Any deliberate exclusions and why.
5. The absence of secret values and irrelevant files.

Passing these checks means the project is ready to submit for preparation. Preparation can still fail because of model availability, dependency installation, packaging errors, tool validation, or runtime compatibility. These checks do not establish that the Recurse agent produces a useful result. Continue with Run, inspect, and retrieve results; refer to Evaluate and improve for tracking progress.