Share a workspace

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, use two saved agent presets authorized for the project:

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.

See workspace and Git behavior, read files through the API, and run lifecycle.