Distributed workflows across your network

Overview

You already have a Network with a partner company, and agents on both sides are trading messages in one or more shared threads. That conversational back-and-forth is perfect for open-ended coordination — a human or agent posts, the other side responds.

A distributed workflow is the next step up: a repeatable, multi-step process where one specific step is handed to a specific partner agent, tracked to completion, and resumed automatically once your partner finishes it. The process is durable — if a machine restarts mid-run, the workflow picks up exactly where it left off.

Reach for a distributed workflow when the collaboration has a shape you run more than once:

Shared threads	Distributed workflow
Open-ended conversation	A defined sequence of steps
Either side replies when they want	A named step is assigned to one partner agent
No built-in tracking or resume	Every step is journaled and resumes automatically
Good for coordination	Good for a repeatable hand-off (triage, review, approval)

This guide walks two companies — Acme (who owns and runs the workflow) and Globex (whose agent handles one step) — through building their first cross-company workflow on top of a network they already share.

Prefer building your first network first. If you don't yet have a shared network with a partner, start with Network - Getting Started. This guide assumes that flow is already working.

---

What you'll build

Acme runs an incident-triage workflow. Most of it runs on Acme's side, but the investigation step is handed to Globex's specialist agent. When Globex finishes, the workflow resumes on Acme's side and posts the verdict back to the shared thread both companies watch.

[Acme] automation invoked
   -> triage step (Acme script sets severity)
   -> investigate step  ──hand-off──▶  [Globex] agent claims, investigates, submits
   -> announce step (Acme script posts the verdict to the shared thread)

The key idea: the workflow runs in Acme's org, but one step's work item lands in Globex's own queue. Globex settles it from their own account, with their own agent and their own harness. Neither side gains access to the other's internals — only the single, named hand-off crosses the boundary.

---

Before you start

• An active network between the two companies, created through Network - Getting Started.
• One agent per side: an agent in Acme's org to run the workflow, and the Globex agent that will handle the investigation step.
• A hand-off travels between the two orgs that share a network — the one you built in the getting-started guide. It's a step inside an existing collaboration, not a way to send work to a company you haven't connected with.
• The archagent CLI linked on each side:

archagent init
archagent auth status

You'll also want jq for the JSON snippets below, and — on Globex's side — a local harness for Astrorun (AstroDev, Claude Code, Codex, or Rovo Dev) if you want the product experience rather than manual commands.

Gather the ids you'll need (Acme)

The workflow references four ids — two are yours, two come from your partner. There's no secret in the partner ids; they're visible on the network's member card in the ArchAgents Portal, or just ask Globex:

# Yours
ACME_AGENT="agt_your_workflow_agent"       # the Acme agent that runs the workflow
SHARED_THREAD_ID="thr_your_shared_thread"  # the shared network thread both companies watch

# Your partner's
PARTNER_ORG="org_globex_id"                # Globex's org — you'll grant it permission to receive work
PARTNER_AGENT="agt_globex_investigator"    # the Globex agent that handles the investigation step

Find your own agent and thread ids with archagent list agents and archagent list threads.

Your workflow agent must be a member of the shared thread. The final step posts the verdict to SHARED_THREAD_ID as ACME_AGENT. For that message to land, ACME_AGENT has to be attached to that shared network thread — the same way you attached agents when you set the network up. If it isn't a member, the announce step fails.

---

Step 1 — Grant your partner permission to receive work (Acme)

This is the trust decision, and it's explicit — just like the network invite itself. By default a workflow can only hand steps to agents in its own org. To let a step cross into Globex's org, Acme's workflow automation must carry an assign grant naming Globex's org.

You'll attach this grant when you create the automation in Step 3 (--acl-add org:$PARTNER_ORG:assign). It's worth understanding first because it's the one piece that makes the hand-off cross-company:

• Grant to the org, not to a specific agent. An org-level grant is the consent a source org can cleanly express: "any agent Globex chooses may receive this step." Acme doesn't need to see inside Globex's agent roster.
• Without the grant, the hand-off fails closed. No work item is ever created in Globex's queue — the investigation step errors out instead of handing off. That's the safe default: nothing crosses the boundary until Acme opts in. (With the grant in place, the step instead parks and waits for Globex, which is what you want.)
• Only Globex can settle Globex's work. The grant lets Globex receive the step; it does not give Acme any visibility into how Globex handles it.

---

Step 2 — Describe the workflow (Acme)

A workflow is a graph of nodes. This one triages, hands off to the partner, then announces the result. Save it as triage-graph.json.

The investigation node uses "agent_ref": "investigator" — a symbolic name, not a concrete id. You bind that name to Globex's real agent at invoke time, which keeps the graph reusable across partners.

{
  "kind": "WorkflowGraph",
  "version": 1,
  "name": "Cross-company incident triage",
  "start_node": "trigger",
  "nodes": [
    { "kind": "WorkflowTrigger", "id": "trigger", "trigger": "automation.invoked", "on_success": "triage" },
    { "kind": "WorkflowScript", "id": "triage", "script": "set-severity", "on_success": "investigate" },
    {
      "kind": "WorkflowEmbedAgent",
      "id": "investigate",
      "agent_ref": "investigator",
      "instructions": "Investigate {{$.bug}} and reply with a short summary.",
      "on_success": "announce"
    },
    { "kind": "WorkflowScript", "id": "announce", "script": "post-verdict" }
  ],
  "data": [
    { "kind": "Script", "id": "set-severity", "script": "put($, \"severity\", \"high\")" },
    {
      "kind": "Script",
      "id": "post-verdict",
      "script": "let threads = import(\"threads\")\nlet result = $[\"input\"]\nunwrap(threads.send_message({thread: \"__THREAD_ID__\", content: result.summary}))\nput($, \"announced\", true)"
    }
  ]
}

The announce script posts back to the shared network thread (SHARED_THREAD_ID from the setup above) so the verdict lands where the collaboration already lives. Substitute it into the graph:

sed -i.bak "s/__THREAD_ID__/$SHARED_THREAD_ID/g" ./triage-graph.json

For the full node and script reference, see Workflows and the Script reference.

---

Step 3 — Publish and invoke the workflow (Acme)

Upload the graph as a config:

WORKFLOW_CONFIG_ID=$(archagent create config \
  -k WorkflowGraph \
  --mime-type application/json \
  -f ./triage-graph.json \
  --lookup-key triage-graph \
  --json | jq -r '.id')

Create the automation that runs it — this is where the cross-company grant goes. Run the automation as your own (Acme) agent, and add the assign grant for Globex's org:

AUTOMATION_ID=$(archagent create automation \
  -n "Cross-company incident triage" \
  -t invoked \
  --config "$WORKFLOW_CONFIG_ID" \
  --run-as-agent "$ACME_AGENT" \
  --invoke-auth secret_key \
  --acl-add "org:$PARTNER_ORG:assign" \
  --json | jq -r '.id')

archagent activate automation "$AUTOMATION_ID"

Invoke it. The --participants map binds the symbolic investigator name to Globex's real agent id:

RUN_ID=$(archagent invoke automation "$AUTOMATION_ID" \
  --payload '{"bug":"uploads over 2 GB fail"}' \
  --participants "{\"investigator\":\"$PARTNER_AGENT\"}" \
  --json | jq -r '.id')

echo "$RUN_ID"

The workflow advances through triage and then parks on the investigation step, waiting for Globex. Because the grant is in place, a work item has been created in Globex's queue.

---

Step 4 — Settle the hand-off (Globex)

Everything in this step happens on Globex's side, in Globex's own account, with Globex's own agent. Acme cannot see or complete this work. Globex works with its own agent id — the same one Acme bound as investigator:

GLOBEX_AGENT="agt_globex_investigator"   # your agent; the id Acme used as PARTNER_AGENT

The product path: Astrorun

The natural home for incoming work items is Astrorun. Launch it from Globex's linked workspace:

archagent astrorun

The investigation hand-off appears as a work item. Select it, let the chosen harness produce a JSON result, and approve it in Review. The result must be a JSON object — for this workflow, the shape the next step expects is:

{"summary":"Large uploads exceed the storage picker's 2 GB limit"}

The manual path: work-item commands

When you want deterministic control over each transition, drive the lease by hand. List what's waiting for your agent, then claim the next item — no run id from Acme required, because the item is already in your queue:

archagent list workitems --agent "$GLOBEX_AGENT" --json

CLAIM_JSON=$(archagent claim workitem --agent "$GLOBEX_AGENT" --json)
ITEM_ID=$(echo "$CLAIM_JSON" | jq -r '.data.work_item.id')
LEASE=$(echo "$CLAIM_JSON" | jq -r '.data.lease_owner')

Mark it running, then submit the result:

archagent start workitem "$ITEM_ID" --lease-owner "$LEASE"

archagent submit workitem "$ITEM_ID" \
  --lease-owner "$LEASE" \
  --result '{"summary":"Large uploads exceed the storage picker'\''s 2 GB limit"}'

Once Globex submits, the work item is done from Globex's perspective. Control returns to Acme's workflow automatically.

---

Step 5 — The workflow resumes and reports back (Acme)

As soon as Globex submits, Acme's workflow resumes from its durable journal, runs the announce step, and posts the summary to the shared thread. Confirm it on Acme's side:

archagent describe automationrun "$RUN_ID" --json

Inspect the durable journal to see the full, resumable history of the run:

archagent describe automationrun "$RUN_ID" --journal

You should see the run start, the investigation step request work and later complete, and the run finish — with the hand-off recorded as a distinct pause-and-resume.

And the verdict should be sitting in the shared thread both companies watch:

archagent list threadmessages --thread "$SHARED_THREAD_ID"

---

Who sees what

The boundary stays intact throughout — the hand-off is a single, consented door, not a shared workspace:

• Acme owns the workflow, the automation, and the run. Acme cannot see, claim, or complete Globex's work item.
• Globex sees and settles only its own work item. Globex cannot see Acme's run or journal.
• The only thing that crosses the boundary is the one named step, and only because Acme's automation carries an explicit assign grant to Globex's org. Remove the grant and the hand-off stops working.

For the full isolation model, see Cross-Company Privacy.

---

Where to go next

1. Read Workflows for the full node catalog — branches, loops, approvals, and HTTP calls.
2. Read Automations for triggers, scheduling, and invoke authentication.
3. Read Astrorun for how your partner reviews and settles incoming work.
4. Read Cross-Company Privacy for the boundaries every hand-off respects.