Recurse docs / 18
Hosted Recurse agents
Recurse runs custom agents that use Python tools to explore alternatives, measure results, and refine their approach. You equip your favorite coding agent with the Recurse skill and focus on defining your project. Your coding agent proposes agentic methodologies, tools and verifiers; Recurse packages and executes them in a serverless harness.
You can execute a Recurse agent for one-time use with recurse run, or deploy as an MCP tool for ongoing use. Deployment is useful when you have a workflow that needs to invoke the same agent with new inputs.
When Recurse is useful
Recurse works best for tasks with multiple possible approaches and where a feedback signal can guide successive attempts. Examples include tuning a ML model, searching a design space, and generating artifacts against measurable requirements.
A useful task has:
- An objective that distinguishes better candidates from worse ones.
- Choices the agent can make, such as geometry, model parameters, or construction methods.
- Verifiers that return measurements or diagnostics about each candidate.
- Conditions for stopping and preserving a result.
The best achievable result does not need to be known in advance. The agent needs a way to compare candidates and determine whether they satisfy the task's constraints.
For example, consider reducing the mass of a mounting bracket. The inputs include the original geometry, material, and load cases. The agent can vary geometric features, then call simulation and geometry tools to measure stress, displacement, mass, and manufacturing constraints. A lighter candidate is eligible only if it also satisfies the given constraints; measurements from a constraint-violating candidate can guide the next design change. In this example, your coding agent will supply/evolve the CAD operations, simulators, and verifiers as it builds progressively better "furniture design" agents. Quality of results will improve as these tools improve.
For a direct calculation or a task with a known sequence of steps, a Python function or the coding agent's existing tools may be sufficient. Recurse is most useful when the work benefits from iterative refinement.
Coding agents and Recurse agents
| Component | Responsibility |
|---|---|
| You | Define the desirable outcome, supply domain requirements, and set time or spending allowances. |
| Coding agent | Write and revise the Recurse agent's prompt, Python tools, verifiers, and manifest; inspect results from trial runs. |
| Recurse agent | Use the given tools to make decisions and produce the deliverable during one execution. |
| Recurse harness | Execute tool calls, retain return values, resolve dependencies, and present tool results/errors to the Recurse agent. |
The coding agent improves the Recurse agent across development runs. The Recurse agent explores candidates within a run using the inputs it receives. You can also author and operate the Recurse agent directly in Python without a coding agent.
Start with Installation and access, then follow the Runnable examples to run an existing example.