Agent.md

Markdown-first runtime for AI agents

Write a .md file, describe what your agent should do, and let it run. No boilerplate. No frameworks to learn. Just Markdown.

Get Started Browse Examples API Docs

---

Why Agent.md?

Most agent frameworks require dozens of files, complex configurations, and deep knowledge of LLM internals. Agent.md takes a different approach:

• One file = One agent

  ---

  Each .md file is a complete agent definition — YAML frontmatter for config, Markdown body for the system prompt.

• Zero boilerplate

  ---

  No classes, no decorators, no framework lock-in. Just write what your agent should do in plain English.

• Flexible triggers

  ---

  Run manually, on schedules (cron/intervals), or automatically when files change.

• Built-in tools

  ---

  File I/O and HTTP requests work out of the box. Add custom tools or MCP servers when you need more.

• Execution tracking

  ---

  Every run is logged with status, duration, token usage, and full message history — queryable via SQL.

• Git-friendly

  ---

  Version control your prompts. See exactly how agents evolved. Roll back with confidence.

---

Quick Example

Create agents/hello-world.md in your workspace:

---
name: hello-world
---

You are a friendly assistant. When asked to execute your task,
write a creative greeting and save it to 'greeting.txt'.

No model needed — uses the default from your config.yaml.

Run it:

agentmd run hello-world

Output:

▶ Running hello-world  google/gemini-2.5-flash  custom_tools: none

17:29:32 hello-world 🤖 Greetings, esteemed user!

May your day be filled with as much wonder and intrigue as a hidden scroll in an ancient library, and may your tasks unfold with the grace and preci…
17:29:32 hello-world 🔧 file_write → {'content': "Greetings, esteemed user!\n\nMay your day be filled with as much wo
17:29:32 hello-world 📎 file_write ← File written successfully: /Users/.../workspace/output/greeting.txt (235 chars)
17:29:35 hello-world 🤖 Greetings, esteemed user!

I've successfully written a creative greeting to 'greeting.txt'. You can find it at `/Users/.../workspace/output/greeting.txt`.

May your day be filled with a

17:29:35 hello-world ✅ Final answer:
  Greetings, esteemed user!

I've successfully written a creative greeting to 'greeting.txt'. You can find it at `/Users/zfab/repos/agentmd/workspace/output/greeting.txt`.

May your day be filled with as much wonder and intrigue as a hidden scroll in an ancient library, and may your tasks unfold with the grace and 
precision of a master artisan. I'm delighted to assist you today!

✓ hello-world done in 5121ms  tokens: 1130 in / 243 out / 1373 total  execution #51

That's it. Your agent ran, used tools, and logged everything.

---

Key Features

Multi-Provider Support

Use any LLM provider — switch with a simple config change:

Google GeminiOpenAI GPTAnthropic ClaudeOllama (Local)Custom Endpoint

model:
  provider: google
  name: gemini-2.5-flash

model:
  provider: openai
  name: gpt-4o

model:
  provider: anthropic
  name: claude-sonnet-4-5-20250929

model:
  provider: ollama
  name: llama3

model:
  provider: local
  name: mistral-7b
  base_url: "http://localhost:8000"

See all providers →

Trigger System

Agents can run in three ways:

Trigger Type	Description	Example
Manual	Run on-demand via CLI	agentmd run my-agent
Chat	Interactive multi-turn conversation	agentmd chat my-agent
Schedule	Run on cron or intervals	Every 5 minutes, daily at 9am, weekdays only
Watch	Run when files change	Monitor logs, process uploads automatically

Learn about triggers →

Built-in Tools

Every agent automatically gets:

• file_read — Read files from workspace
• file_write — Create and write files (with security restrictions)
• http_request — Make HTTP calls (GET, POST, etc.)
• memory_save / memory_append / memory_retrieve — Persistent long-term memory

Explore tools →

MCP Integration

Connect to any Model Context Protocol server:

mcp:
  - fetch      # Web fetching
  - github     # GitHub API
  - puppeteer  # Browser automation

MCP integration guide →

Custom Tools

Extend agents with Python:

# workspace/agents/tools/sentiment.py
from langchain_core.tools import tool

@tool
def analyze_sentiment(text: str) -> str:
    """Analyzes sentiment of the given text."""
    # Your implementation
    return "positive"

custom_tools:
  - sentiment

Create custom tools →

---

What's Next?

• Quick Start

  ---

  Install Agent.md and run your first agent in 5 minutes.

• Agent Configuration

  ---

  Learn about agent files, triggers, providers, and execution flow.

• Examples

  ---

  See real-world examples for every use case and feature.

• Documentation

  ---

  Copy-paste ready agents for common tasks — just add your API keys.

---

Features at a Glance

• Multi-provider support — Google, OpenAI, Anthropic, Ollama, custom endpoints
• Flexible triggers — Manual, schedule (cron/interval), file watching
• Built-in tools — File I/O, HTTP requests
• Custom tools — Extend with Python
• MCP integration — Connect to external tool servers
• File access security — Read/write path restrictions
• Execution tracking — Full history with token usage
• Git-friendly — Version control your prompts
• Memory & context persistence — Session history + long-term memory tools
• Skills support — Coming soon
• Agent pipelines — Chain agents together
• Terminal UI (TUI) — Real-time monitoring

View full roadmap →

---

Community & Support

• Documentation: You're reading it!
• GitHub: github.com/z-fab/agentmd
• Issues: Report bugs or request features
• Discussions: Share your agents and ideas

---

Built with and Markdown

If agents could write themselves, they'd choose Markdown too.

Get Started →