writing-agent-relay-workflows
Writing Agent Relay Workflows
Overview
The relay broker-sdk workflow system orchestrates multiple AI agents (Claude, Codex, Gemini, Aider, Goose) through typed DAG-based workflows. Workflows can be written in TypeScript (preferred), Python, or YAML.
Language preference: TypeScript > Python > YAML. Use TypeScript unless the project is Python-only or a simple config-driven workflow suits YAML.
Pattern selection: Do not default to dag blindly. If the job needs a different swarm/workflow type, consult the choosing-swarm-patterns skill when available and select the pattern that best matches the coordination problem.
Package: import from @relayflows/core. @agent-relay/sdk/workflows was removed and @relayflows/core replaces it (see cloud/scripts/smoke-sandbox-image.mjs, which asserts @relayflows/core is present in the sandbox image). @agent-relay/sdk exports ., ./messaging, ./delivery, ./actions, ./session, and ./capabilities — there is no ./workflows subpath, so the old specifier cannot resolve. If you find a workflow importing it, or a hand-written ambient declare module '@agent-relay/sdk/workflows' stub standing in for the missing types, both are stale: repoint them at @relayflows/core and delete the stub. The same package works locally and inside the cloud workflow runner, so ctx.workflow.run(...)-dispatched workflows use it too.
Runners — verified 2026-08-31 against agent-relay 11.8.7 / @relayflows/cli 1.1.0:
| Goal | Command | Note |
|---|---|---|
| Run locally | relayflows run <file> |
From @relayflows/cli. There is no agent-relay run subcommand. |
| Validate without running | relayflows run --dry-run <file> |
--dry-run exists only here |
| Run in cloud | agent-relay cloud run <file> --file-type ts |
Has no --dry-run |