# Share a workspace between agents

Two agents can use the same persisted files by taking turns in one workspace. They can use different harnesses, models, and named connections. Each new session keeps its own conversation.

This works the same way on Macrofold Cloud and self-hosted deployments.

## Hand work from one agent to another

Use the same `workspace_id` and wait for the first run to finish execution **and persistence** before submitting the second. Reusing a `project_id` selects that project's main workspace; an explicit workspace ID makes the handoff unambiguous.

After [setting up the Python SDK](https://staging.macrofold.ai/docs/raw/sdk/python.md), use two saved agent presets authorized for the project:

```python
from macrofold import Macrofold

macrofold = Macrofold()
workspace_id = "YOUR_WORKSPACE_ID"

research = macrofold.runs.create(
    workspace_id=workspace_id,
    agent_id="YOUR_RESEARCH_AGENT_ID",
    prompt="Write findings.md with your research findings.",
)
macrofold.runs.wait(research.run_id)

review = macrofold.runs.create(
    workspace_id=workspace_id,
    agent_id="YOUR_REVIEW_AGENT_ID",
    prompt="Read findings.md and write review.md with your assessment.",
)
result = macrofold.runs.wait(review.run_id)
print(result.output_text)
macrofold.close()
```

For self-hosting or local use, set the client's base URL as described in the SDK guide. Each preset supplies its own harness, model, billing configuration, and authorized connections. Each run consumes its own budget. The second agent receives persisted files, not the first agent's private conversation or credentials.

If persistence fails, `wait` raises an error. Recover the workspace before handing it off. Optional Git synchronization is independent of `wait`; another agent on the same workspace can read the saved checkpoint without waiting for a GitHub push.

## If the workspace is busy

A new run from another session or agent returns **409 `workspace_busy`** while the workspace has pending work. Wait for that work to finish, or select another workspace. The API does not automatically queue a new agent behind another agent in the same folder.

Queued follow-up messages within an existing session are a separate feature; they continue that session's fixed configuration. They are not a way to switch its agent preset.

## Work in parallel

Create independent workspaces from a shared checkpoint or authorized Git ref. Each agent gets its own writable files and can run concurrently within the organization's limits. Review and merge their Git branches explicitly. Shared ancestry does not automatically synchronize later edits or resolve conflicts.

| Need | Use |
| --- | --- |
| Agent B reads files saved by agent A | Same workspace, sequential runs |
| Continue an agent's conversation | Same session with compatible configuration |
| Agents edit at the same time | Separate workspaces, then review and merge |
| Read progress before the run saves | Run events; file reads show the last published revision |

See [workspace and Git behavior](https://staging.macrofold.ai/docs/raw/workspaces.md), [read files through the API](https://staging.macrofold.ai/docs/raw/workspaces/read-files.md), and [run lifecycle](https://staging.macrofold.ai/docs/raw/runs.md).