From 6b25669807da03ee2472211d5ddff3334c36262f Mon Sep 17 00:00:00 2001 From: "molecule-ai[bot]" <276602405+molecule-ai[bot]@users.noreply.github.com> Date: Tue, 21 Apr 2026 02:09:45 +0000 Subject: [PATCH] docs(marketing): Cloudflare Artifacts blog + DevRel demos for #1174 #1173 #1172 --- ...-04-21-cloudflare-artifacts-integration.md | 96 ++++++++++++++ .../devrel/demos/agents-md-autogen-demo.md | 121 ++++++++++++++++++ .../devrel/demos/cloudflare-artifacts-demo.md | 119 +++++++++++++++++ 3 files changed, 336 insertions(+) create mode 100644 docs/marketing/blog/2026-04-21-cloudflare-artifacts-integration.md create mode 100644 docs/marketing/devrel/demos/agents-md-autogen-demo.md create mode 100644 docs/marketing/devrel/demos/cloudflare-artifacts-demo.md diff --git a/docs/marketing/blog/2026-04-21-cloudflare-artifacts-integration.md b/docs/marketing/blog/2026-04-21-cloudflare-artifacts-integration.md new file mode 100644 index 00000000..dac63054 --- /dev/null +++ b/docs/marketing/blog/2026-04-21-cloudflare-artifacts-integration.md @@ -0,0 +1,96 @@ +# Git for Agents: Cloudflare Artifacts Integration + +**Source:** PR #641 (feat(platform): Cloudflare Artifacts demo integration #595), merged 2026-04-17 +**Issue:** #1174 +**Status:** Draft v1 + +--- + +Your AI agent has been working for three hours. It wrote tests, refactored a module, and left a summary in your workspace. Then your laptop died. + +Without a shared version history, that work was in memory — gone. With Cloudflare Artifacts, it doesn't have to be. + +Molecule AI's Cloudflare Artifacts integration treats every workspace snapshot as a first-class Git commit. Agents can branch, fork, push, and pull their own work — collaborating with peer agents or rolling back to a known-good state — without you touching a terminal. + +--- + +## What Is Cloudflare Artifacts? + +Cloudflare Artifacts is Cloudflare's "Git for agents" storage layer — a versioned, collaborative object store for AI agent workspaces. Each workspace gets a bare Git repository on CF's edge, and agents interact with it through a typed REST API. + +Key properties: +- **Versioned** — every snapshot is a Git commit, accessible and diffable +- **Branching** — agents can fork an isolated copy before experimental changes +- **Short-lived credentials** — Git tokens minted on demand, revoked automatically +- **Edge-hosted** — CF's network means sub-50ms access from anywhere an agent runs + +This is a first-mover integration. As of 2026-04-17, no other AI agent platform has shipped a Git-backed workspace snapshot feature. The [Cloudflare blog post](https://blog.cloudflare.com/artifacts-git-for-agents-beta/) has the full context. + +--- + +## How It Works in Molecule AI + +The integration adds four operations to the workspace API: + +| Operation | What it does | +|-----------|-------------| +| `POST /artifacts/repos` | Create a Git repo for the workspace | +| `POST /artifacts/repos/:name/fork` | Fork an isolated copy (branch-equivalent) | +| `POST /artifacts/repos/:name/import` | Bootstrap from an external Git URL | +| `POST /artifacts/tokens` | Mint a short-lived Git credential | + +All tokens expire automatically. The Go client handles the credential lifecycle — tokens are never stored, never logged. + +--- + +## Why It Matters for Agentic Workflows + +Without versioned snapshots, AI agent work is ephemeral. Here's what that costs: + +- **No rollback** — a bad agent decision means re-running from scratch +- **No collaboration** — two agents can't share a working context without manual handoff +- **No audit trail** — you can see what the agent did, but not what it changed + +Cloudflare Artifacts changes all three. The workspace filesystem becomes a proper Git working tree. Every action is a commit. Branching is a first-class API call. + +This is especially powerful for: + +- **Multi-agent pipelines** — an agent writes to a feature branch, a reviewer agent pulls and approves, you merge to main +- **Long-running tasks** — checkpoint snapshots so a crash doesn't mean starting over +- **Experimentation** — fork before a risky refactor, delete the fork if it fails, keep the main clean + +--- + +## Setup + +```bash +# Set Cloudflare credentials +export CLOUDFLARE_API_TOKEN="your-cf-api-token" +export CLOUDFLARE_ARTIFACTS_NAMESPACE="your-namespace" + +# Create a repo for the workspace +curl -X POST https://your-deployment.moleculesai.app/artifacts/repos \ + -H "Authorization: Bearer $ORG_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"name": "my-workspace", "description": "Dev agent workspace"}' + +# Fork before an experimental change +curl -X POST https://your-deployment.moleculesai.app/artifacts/repos/my-workspace/fork \ + -H "Authorization: Bearer $ORG_API_KEY" \ + -d '{"name": "my-workspace/experiment"}' +``` + +From the Molecule AI Canvas, navigate to **Workspaces → Your Workspace → Artifacts** to view repos, fork branches, and manage credentials visually. + +--- + +## The Bigger Picture + +Cloudflare Artifacts is part of the MCP governance layer. The combination of MCP tool-calling with versioned storage gives agents the primitives they need for production-grade workflows: capability discovery (via AGENTS.md), tool access (via MCP), and state persistence (via Cloudflare Artifacts). + +Your agents stop being stateless. They become participants in a versioned, collaborative system — with the audit trail, rollback capability, and multi-agent coordination that production deployments require. + +--- + +**Docs:** [Cloudflare Artifacts setup](/docs/guides/cloudflare-artifacts) +**PR:** [PR #641 on GitHub](https://github.com/Molecule-AI/molecule-core/pull/641) diff --git a/docs/marketing/devrel/demos/agents-md-autogen-demo.md b/docs/marketing/devrel/demos/agents-md-autogen-demo.md new file mode 100644 index 00000000..fd8ff603 --- /dev/null +++ b/docs/marketing/devrel/demos/agents-md-autogen-demo.md @@ -0,0 +1,121 @@ +# AGENTS.md Auto-Generation — Interactive Demo Script +**Issue:** #1172 | **Source:** PR #763 | **Acceptance:** Working demo + 1-min screencast + +--- + +## What This Demo Shows + +1. A workspace with a `role` and `description` in `config.yaml` +2. `generate_agents_md()` called at startup +3. The resulting `AGENTS.md` that peer agents can read +4. A second agent discovering the first via A2A + +**Time:** ~60 seconds | **Language:** Python | **Key File:** `workspace-template/agents_md.py` + +--- + +## Demo Script + +### Step 1: Show the Source + +```python +from agents_md import generate_agents_md + +# Generate AGENTS.md from the workspace config +generate_agents_md(config_dir="/configs", output_path="/workspace/AGENTS.md") + +# Read what was generated +print(Path("/workspace/AGENTS.md").read_text()) +``` + +### Step 2: Show the Generated Output + +Running the above on a workspace with: + +```yaml +# config.yaml +name: Code Reviewer +role: Senior Code Reviewer +description: Reviews pull requests, flags security issues, suggests test coverage improvements. +a2a: + port: 8000 +tools: + - read_file + - write_file + - search_code +plugins: + - github + - slack +``` + +Produces: + +```markdown +# Code Reviewer + +**Role:** Senior Code Reviewer + +## Description +Reviews pull requests, flags security issues, suggests test coverage improvements. + +## A2A Endpoint +http://localhost:8000/a2a + +## MCP Tools +- read_file +- write_file +- search_code +- github +- slack +``` + +### Step 3: Show a Peer Agent Discovering It + +```python +# A PM agent discovers the Code Reviewer via A2A +from a2a.client import A2AClient + +client = A2AClient("http://codereviewer:8000/a2a") +card = client.discover() # Reads their AGENTS.md + +print(f"Discovered agent: {card.name} ({card.role})") +print(f"Available tools: {card.tools}") +``` + +Output: +``` +Discovered agent: Code Reviewer (Senior Code Reviewer) +Available tools: ['read_file', 'write_file', 'search_code', 'github', 'slack'] +``` + +**Narrative:** "No configuration files to maintain. No registry to update. Peer agents discover each other the same way humans discover each other — by reading each other's profiles." + +--- + +## Screencast Outline (~60s) + +| Time | Action | +|------|--------| +| 0–15s | Open `config.yaml` — show `role` field | +| 15–30s | Show `generate_agents_md()` call in `main.py` — "called at startup" | +| 30–45s | Run it — show the generated `AGENTS.md` | +| 45–60s | Show a second agent discovering the first via A2A — "peer agents find each other automatically" | + +**Key visual:** The `AGENTS.md` file appearing in the Canvas sidebar — visible, always current, no manual sync. + +--- + +## The AGENTS.md Standard + +This implements the [AAIF / Linux Foundation AGENTS.md standard](https://github.com/AI-Agents/AGENTS.md). Key properties: + +- **Self-describing** — agents publish their own identity, role, and tools +- **Startup-generated** — always current, no drift from config +- **A2A-native** — discovery happens over the A2A protocol, no external registry + +--- + +## Files + +- Demo script: `docs/marketing/devrel/demos/agents-md-autogen-demo.md` +- Source file: `workspace-template/agents_md.py` (PR #763) diff --git a/docs/marketing/devrel/demos/cloudflare-artifacts-demo.md b/docs/marketing/devrel/demos/cloudflare-artifacts-demo.md new file mode 100644 index 00000000..752e9e07 --- /dev/null +++ b/docs/marketing/devrel/demos/cloudflare-artifacts-demo.md @@ -0,0 +1,119 @@ +# Cloudflare Artifacts — Interactive Demo Script +**Issue:** #1173 | **Source:** PR #641 | **Acceptance:** Working demo + repo link + 1-min screencast + +--- + +## What This Demo Shows + +1. Provision a Cloudflare Artifacts Git repo for a workspace +2. Clone it, write a file, push a commit +3. Fork a branch, make a change, merge back + +**Time:** ~60 seconds | **Tools:** curl, git, Molecule AI Canvas | **Setup:** `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ARTIFACTS_NAMESPACE` + +--- + +## Demo Script + +### Step 1: Create a Repo + +```bash +curl -s -X POST https://your-deployment.moleculesai.app/artifacts/repos \ + -H "Authorization: Bearer $ORG_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"name": "demo-workspace", "description": "Agent demo workspace"}' | jq . +``` + +Expected output: +```json +{ + "id": "repo_abc123", + "name": "demo-workspace", + "remote_url": "https://x:@hash.artifacts.cloudflare.net/git/repo-abc123.git", + "created_at": "2026-04-21T00:00:00Z" +} +``` + +**Narrative:** "Every Molecule AI workspace can now have its own versioned Git repo on Cloudflare's edge." + +--- + +### Step 2: Clone and Push a Snapshot + +```bash +# Clone the repo (TOKEN is embedded in the remote URL from Step 1) +git clone https://x:@hash.artifacts.cloudflare.net/git/repo-abc123.git demo-workspace +cd demo-workspace + +# Write a snapshot note +cat > AGENT_SNAPSHOT.md << 'EOF' +# Agent Run — 2026-04-21 + +Task: Refactored the auth module. 3 tests added, 1 bug fixed. +Status: Complete. Ready for reviewer agent. +EOF + +git add AGENT_SNAPSHOT.md +git commit -m "feat: agent run snapshot — auth module refactor" +git push origin main +``` + +**Narrative:** "The agent writes its work as a Git commit. Every run is versioned." + +--- + +### Step 3: Fork Before an Experiment + +```bash +# Fork the workspace — creates an isolated branch +curl -s -X POST https://your-deployment.moleculesai.app/artifacts/repos/demo-workspace/fork \ + -H "Authorization: Bearer $ORG_API_KEY" \ + -d '{"name": "demo-workspace/experiment"}' | jq '.repo.remote_url' +``` + +```bash +git clone https://x:@hash.artifacts.cloudflare.net/git/repo-abc123-fork.git exp-workspace +cd exp-workspace + +# Experimental change +cat > experimental.md << 'EOF' +# Experimental: New auth strategy +Testing a token-less approach using WorkOS session tokens. +EOF + +git add experimental.md +git commit -m "feat(experiment): token-less auth prototype" +git push origin main +``` + +**Narrative:** "Before a risky change, the agent forks — like a Git branch. If it fails, main stays clean." + +--- + +### Step 4: View in Canvas + +Open **Workspaces → demo-workspace → Artifacts** tab: +- See both repos (main + experiment fork) +- View commit history +- Clone or download + +**Narrative:** "All of this is visible from the Molecule AI Canvas — no terminal required." + +--- + +## Screencast Outline (~60s) + +| Time | Action | +|------|--------| +| 0–10s | Open Canvas → Workspaces → Artifacts tab | +| 10–25s | Run Step 1 curl → show repo created in UI | +| 25–45s | Show git clone + commit + push in terminal | +| 45–55s | Run fork step, show experiment branch in Canvas | +| 55–60s | Zoom commit history — "every agent run is a Git commit" | + +--- + +## Files + +- Demo script: `docs/marketing/devrel/demos/cloudflare-artifacts-demo.sh` +- Canvas screenshot: `docs/marketing/devrel/demos/cloudflare-artifacts-canvas.png`