Build a Multi-Agent AI Workflow with a Shared CloudFS Workspace

Multi-agent applications become difficult when each agent can reason independently but cannot reliably share work. Passing every artifact through prompts or a message broker adds serialization, payload limits, and another coordination layer.

This TypeScript sample takes a simpler approach: five Telnyx Agent SDK actors use one shared CloudFS filesystem as their workspace. Each actor reads the previous artifact, writes the next one with standard POSIX file APIs, records the operation in embedded SQL, and broadcasts its state over WebSockets.

What does the workflow build?

The demo runs this handoff:

writer -> report.md
analyst -> analysis.json
reviewer -> review.md
summarizer -> summary.md
publisher -> manifest.json

Every run receives its own runs/<runId>/ directory, so repeated demos do not overwrite earlier artifacts. The dashboard displays all five actors, their current states, generated files, artifact previews, and the fleet-wide SQL activity log.

Why use a shared filesystem for agents?

A filesystem is a useful coordination primitive when agents produce reports, datasets, code, images, or other artifacts that already have a natural file representation. Each process mounts the same CloudFS filesystem and uses node:fs/promises; there is no proprietary file-access API in the application.

CloudFS is mounted with JuiceFS and provides the shared POSIX path. In local development, the same application can use a writable local directory. Production changes the mount path, not the workflow code.

How are partial files prevented?

Writers create a temporary file and atomically rename it into place. Readers therefore see either the old complete file or the new complete file, rather than a partially written artifact. Path validation also prevents absolute paths and .. traversal from escaping the configured workspace.

How does the fleet track activity?

The FleetRegistry actor stores two embedded SQL tables:

• agents records actor ID, role, status, last artifact, and update time.
• files records path, size, modification time, actor ID, operation, and timestamp.

This separates the artifacts from their operational metadata. CloudFS holds the work; SQL answers questions such as which agent wrote a file, which agent read it, and what the fleet is doing now.

Where do WebSockets fit?

Each FleetAgent uses AgentSocketServer. State transitions such as reading, writing, done, and error are broadcast to connected clients. The web dashboard can therefore show the handoff while it happens rather than polling every actor.

Run the demo

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/agent-fleet-shared-workspace
npm install
cp .env.example .env
npm start

For a local demonstration, set CLOUDFS_MOUNT_PATH=/tmp/agentfs, then open http://localhost:8787 and select Run agent fleet. For CloudFS, follow the setup guide and point the same variable at the JuiceFS mount.

You can also start a paced run directly:

curl -X POST http://localhost:8787/demo \
  -H 'Content-Type: application/json' \
  -d '{"runId":"recording-take-01","paceMs":1100}'

Where is this pattern useful?

The same architecture works for content production, document-processing pipelines, and software-delivery workflows. Specialized agents can own distinct steps while CloudFS preserves the shared artifacts, SQL provides an audit trail, and WebSockets make progress observable.

Explore the complete sample: https://github.com/team-telnyx/telnyx-code-examples/tree/main/agent-fleet-shared-workspace

Watch the demo: https://www.youtube.com/watch?v=ZvEgg_CA_aM