Multi-agent applications need more than independent reasoning. They need a reliable way to hand durable artifacts from one specialist to the next.
This sample creates five Telnyx Agent SDK actors: writer, analyst, reviewer, summarizer, and publisher. They share one CloudFS workspace and produce a chain of Markdown and JSON files.
Architecture
CloudFS /shared/runs/<runId>/
├── report.md
├── analysis.json
├── review.md
├── summary.md
└── manifest.json
FleetRegistry
├── agents table
└── files table
CloudFS is mounted with JuiceFS as a POSIX filesystem. The actors use node:fs/promises, not a special storage API. This lets the local demo use /tmp/agentfs while a deployed environment uses the real mount path.
Why combine files and SQL?
CloudFS stores the artifacts themselves. Embedded SQL stores searchable operational metadata: actor role, current status, last artifact, file size, operation type, and timestamp. GET /fleet combines that information into a fleet-wide view.
Every actor also uses AgentSocketServer to broadcast its state. Connected dashboards receive reading, writing, done, and error transitions in real time.
Safe shared writes
The workspace helper validates every relative path and prevents it from escaping the shared directory. It writes content to a temporary file and atomically renames it into place, preventing readers from seeing a partial artifact.
Run the guided 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
Set CLOUDFS_MOUNT_PATH=/tmp/agentfs for local development and open http://localhost:8787. Select Run agent fleet to watch all five stages, generated artifacts, SQL history, and previews update through the handoff.
For an isolated paced run:
curl -X POST http://localhost:8787/demo \
-H 'Content-Type: application/json' \
-d '{"runId":"recording-take-01","paceMs":1100}'
Use cases
This pattern works well for content production, document processing, research pipelines, and software delivery. Each agent owns one responsibility, while the shared workspace makes its output durable and inspectable.
Source: https://github.com/team-telnyx/telnyx-code-examples/tree/main/agent-fleet-shared-workspace
Top comments (0)