This commit is contained in:
molecule-ai[bot]
GitHub
parent
fcd3a6eaf0
commit
6b25669807
@ -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)
|
||||
121
docs/marketing/devrel/demos/agents-md-autogen-demo.md
Normal file
121
docs/marketing/devrel/demos/agents-md-autogen-demo.md
Normal file
@ -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)
|
||||
119
docs/marketing/devrel/demos/cloudflare-artifacts-demo.md
Normal file
119
docs/marketing/devrel/demos/cloudflare-artifacts-demo.md
Normal file
@ -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:<TOKEN>@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:<TOKEN>@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:<TOKEN>@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`
|
||||
Loading…
Reference in New Issue
Block a user