Agents.md Node Demo

A minimal Node.js + TypeScript demo of OpenAI’s AGENTS.md spec . It shows how you can define agent tools in a YAML file and expose them automatically as Express endpoints.

✅ Quick win: run a hello-world agent (sayHello)

✅ Minimal repro: Node script that loads AGENTS.md

✅ Extended demo: Express + MongoDB server that exposes tools from AGENTS.md

Getting Started

1. Clone and install git clone https://github.com/sameem786-blip/agents-md-node.git cd agents-md-node npm install

2. Seed the database

Start MongoDB (local or Docker):

docker run -d -p 27017:27017 --name agents-mongo mongo:6

Then insert a test user:

npx tsx seed.ts

Expected:

✅ Seeded user: Alice alice@example.com

Quick Win: Runner Script npm run start:runner

Expected output:

{ "greeting": "Hello, Alice!" }

Minimal Repro: Express Agent Server

Start the server:

npm run start:server

You should see:

✅ Agent server running on :3000

Try the Tools Add a new user curl -X POST http://localhost:3000/agent/addUser
-H "Content-Type: application/json"
-d '{"name":"Bob","email":"bob@example.com"}'

Expected:

{ "success": true }

Fetch a user curl -X POST http://localhost:3000/agent/getUser
-H "Content-Type: application/json"
-d '{"email":"bob@example.com"}'

Expected:

{ "_id":"...","name":"Bob","email":"bob@example.com","__v":0 }

How It Works

AGENTS.md describes tools in YAML.

server.ts parses the spec and auto-generates Express routes.

Each tool has a handler in Node that maps directly to MongoDB functions.

Think of it as OpenAPI for AI agents — a contract between agents and your backend.

Next Steps

Add more tools in AGENTS.md (e.g., deleteUser, listUsers)

Wire an LLM (OpenAI, Qwen, etc.) to read the spec and call these endpoints automatically

Deploy with Docker or Vercel for a public demo

License

MIT