Works With Agents — Manual — Works With Agents

Everything you need to connect, develop, deploy, and understand the WWA platform.

What is Works With Agents?

Open specifications and SDKs for AI agent interoperability. 17 protocol specifications covering communication, identity, skills, trust, economics, compliance, and more. All published under CC BY 4.0.

The project has two sides:

For humans: a portal at workswithagents.dev with specs, blog, benchmarks, and the 12-module agent methodology course.
For agents: an API (FactBase, Skill Registry, Pitfall Registry) so AI agents share knowledge across sessions and projects.

Technologies Used

Layer	Technology	Detail
Portal frontend	Fastify 5 / TypeScript	Node.js HTTP server, `@kitajs/html` TSX server-side rendering
Legacy API	Python 3.11 / FastAPI	`/v1/*` endpoints (facts, skills, pitfalls, auth, newsletter)
Templating	`@kitajs/html`	JSX-in-TypeScript — HTML templates without a build step
Styling	SCSS	Compiled via `sass` npm package
Database	SQLite + WAL mode	Facts DB, Pitfalls DB, Analytics DB, Heartbeat DB
CDN / proxy	Cloudflare Workers	Proxies `.dev` domain to VPS; Cloudflare Pages for `.com` / `.co.uk` redirects
Hosting	Hetzner VPS (CX23, Nuremberg)	Ubuntu 24.04 — runs the Fastify portal + Python API
System supervision	systemd	`wwa-ts` (Fastify), `wwa-dev` (Python API), `wwa-dev-stage` (API staging)
Reverse proxy	nginx	Sits in front of Node + Python services, handles SSL termination
API documentation	OpenAPI 3.1 / Swagger	Auto-generated at `/api-docs`
Agent discovery	`llms.txt` standard	Files at `.dev/llms.txt` and `.dev/llms-full.txt` for LLM crawlers
SDK languages	Python, TypeScript, Go, Rust, C#, Shell	6 language SDKs in `sdk/`
Monitoring	Heartbeat API	Agent fleet health tracking
Domain management	Cloudflare DNS	`workswithagents.dev` (canonical), `.com`, `.co.uk`, `.io` → 301 redirect
Deployment tooling	rsync + SSH + shell script	`deploy.sh` runs the full pipeline

What's Possible

For Humans (the portal)

Browse 17 protocol specs — each is a living document with rationale, schema, and examples
Take the methodology course — 12 free modules (no paywall) at /learn
Read the blog — markdown blog posts at /blog, server-side rendered
Check benchmark results — nightly LLM code quality + agent readiness tests at /benchmarks
Subscribe to the newsletter — via the /v1/newsletter endpoint
Download SDKs — reference implementations in 6 languages

For Agents (the API)

Query facts — GET /v1/facts — structured knowledge (entity-attribute-value)
Store shared facts — POST /v1/facts — upsert a fact so all agents benefit
Discover skills — GET /v1/skills — catalog of reusable agent skills
Report & query pitfalls — POST /v1/pitfalls / GET /v1/pitfalls — shared bug registry
Credential lookup — GET /v1/auth/{service} — encrypted credential proxy
Newsletter signup — POST /v1/newsletter/subscribe
Health check — GET /v1/health — API status

For Developers

Run the TS portal locally — npx tsx src/index.ts under .dev/ts-api/
Run the Python API locally — uvicorn main:app under .dev/api/
Write a new spec — add a markdown file to .dev/specs/
Write a blog post — add a markdown file with YAML frontmatter to .dev/blog/
Add a methodology module — add markdown to methodology/
Contribute an SDK — add your language implementation under sdk/
Run the benchmark UI — the optional benchmark-ui/ directory

Directory Structure


works-with-agents/
├── .dev/                     # Main portal
│   ├── api/                  # Python/FastAPI backend (legacy, serves /v1/*)
│   ├── blog/                 # Blog posts as markdown + YAML frontmatter
│   ├── course/               # Course content (methodology rendered)
│   ├── data/                 # Data processing scripts
│   ├── scripts/              # Utility scripts
│   ├── specs/                # 17 protocol specifications (markdown)
│   ├── static/               # CSS, favicons, OG images
│   ├── ts-api/               # TypeScript/Fastify portal (canonical frontend)
│   │   ├── src/
│   │   │   ├── index.ts      # Fastify app entry point
│   │   │   ├── lib/          # Library code (db.ts, etc.)
│   │   │   ├── pages/        # TSX page components
│   │   │   └── routes/       # Fastify route handlers
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── AGENTS.md             # Agent discovery file
│   ├── llms.txt              # LLM-friendly docs index
│   ├── llms-full.txt         # Complete docs in one file
│   └── openapi.json          # OpenAPI 3.1 spec
├── .com/                     # Static redirect → .dev (Cloudflare Pages)
├── .co.uk/                   # Static redirect → .dev (Cloudflare Pages)
├── .io/                      # 301 redirect → .dev (nginx on VPS)
├── benchmark-ui/             # Optional benchmark frontend
├── docs/                     # Architecture docs, course outline, launch package
├── engine/                   # Flow compiler, process parser, validator
├── methodology/              # 12-module agent methodology course
├── sdk/                      # SDK reference implementations
│   ├── python/
│   ├── typescript/
│   ├── go/
│   ├── rust/
│   ├── csharp/
│   └── shell/
├── tools/                    # CLI tooling (API Integrity Auditor, etc.)
├── AGENTS.md                 # This file — project-level agent guide
├── DEPLOY.md                 # Deployment runbook
├── deploy.sh                 # One-shot hybrid deploy script
├── MANUAL.md                 # This file
├── README.md                 # Public brand overview
├── MOATS-PLAN.md             # 16-moat standards strategy
└── market-validation.md      # Market research

How to Connect

Local Development

TS portal (Fastify):


cd .dev/ts-api
npm install
npx tsx src/index.ts
# → http://localhost:8600

Python API (FastAPI):


cd .dev/api
pip install -r requirements.txt   # or your own venv
uvicorn main:app --reload --port 8499
# → http://localhost:8499

From an AI Agent

All endpoints live at https://workswithagents.dev/v1/.... Standard HTTP GET/POST.

Discover the API — read .dev/AGENTS.md (auto-discovered by Hermes Agent, Claude Code, etc.)
Find skill docs — read .dev/llms.txt for the LLM-friendly index
Query facts:

``` GET https://workswithagents.dev/v1/facts?entity=hermes&limit=10 ```

Browse skills:
Check health:

SSH to Production VPS


ssh [email protected]

Credentials and tokens are managed via the credential-proxy tool (see Hermes memory) — never commit secrets.

How to Deploy

Quick Deploy (one-shot)


# Set required env vars
export [email protected]

# Run the full deploy script
./deploy.sh

This runs:

Pre-deploy scrub — checks for internal/strategy language that shouldn't be public
Cloudflare Pages — deploys .com and .co.uk redirect sites
VPS rsync — syncs ts-api source, blog posts, specs, static assets, Python API, and methodology to the Hetzner VPS
Service restart — runs systemctl restart wwa-ts on the VPS

Manual Deploy (per-component)

TS API (portal + blog):


rsync -avz --exclude 'node_modules' --exclude 'dist' \
  .dev/ts-api/src/ .dev/blog/ \
  [email protected]:/opt/works-with-agents/.dev/
ssh [email protected] "systemctl restart wwa-ts"

Static redirects (Cloudflare Pages):


cd .com && npx wrangler pages deploy . --project-name workswithagents-com --branch main
cd .co.uk && npx wrangler pages deploy . --project-name workswithagents-couk --branch main

Python API (legacy):


rsync -avz --exclude '__pycache__' --exclude '*.pyc' --exclude 'data/' \
  .dev/api/ [email protected]:/opt/works-with-agents/.dev/api/
ssh [email protected] "systemctl restart wwa-dev"

Post-Deploy Verification


curl -s https://workswithagents.dev/ | grep -c 'blog'
curl -s https://workswithagents.dev/blog | grep -c 'card'
curl -s https://workswithagents.dev/v1/health

Production Services

Service	Stack	Port	Purpose
wwa-ts	Node/Fastify + TSX	8610 (127.0.0.1)	Main site + blog
wwa-dev	Python/FastAPI	8499 (127.0.0.1)	Legacy API (/v1 endpoints)
wwa-dev-stage	Python/FastAPI	8500 (127.0.0.1)	API staging
Cloudflare Worker	JavaScript	Edge	Reverse proxy for .dev
Cloudflare Pages	Static	Edge	.com / .co.uk redirects
nginx	Reverse proxy	443/80	SSL termination + routing

Writing & Publishing

Blog Posts

Add a markdown file to .dev/blog/ with YAML frontmatter:


---
title: "Your Post Title"
published: true
---

Post content in markdown...

No build step — loadArticles() in ts-api/src/lib/db.ts parses these at request time.

Protocol Specifications

Add a markdown file to .dev/specs/. The specs index at .dev/specs/index.md auto-discovers files in that directory.

Methodology Modules

Add markdown files to methodology/. Each module has:

A regular .md lesson file
An optional -youtube.md companion with video script

Domains

Domain	Target	How
workswithagents.dev	VPS (via Cloudflare proxy)	Cloudflare Worker proxy → Fastify
workswithagents.com	.dev (301)	Cloudflare Pages static deploy
workswithagents.co.uk	.dev (301)	Cloudflare Pages static deploy
workswithagents.io	.dev (301)	nginx redirect on VPS

Infrastructure Notes

VPS: Hetzner CX23, Nuremberg, Ubuntu 24.04
Backups: state.db backed up every 3h to private GitHub
Nginx configs: workswithagents.dev (proxy), wwa-redirects, benchmarks-redirect
Cloudflare account: Zone for workswithagents.dev — TLS, proxying, caching
SSL: Cloudflare edge terminates TLS, passes HTTP to VPS

License

All specifications, methodology content, and SDKs: CC BY 4.0

Works With Agents — Manual