bruno/agent-protocol
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v1.0.0-draft: First public draft release

Browse Source 
agents.md protocol for AI agent web discovery.

Key features:
- Two formats: Pure Markdown (simple) or YAML frontmatter (structured)
- MCP gateway integration for tool access
- Discovery via /.well-known/agents.md
- Security: origin trust, endpoint validation, auth guidance
- Backward compatible with robots.txt and llms.txt

Design based on 3-iteration process:
1. Gap analysis and planning
2. Multi-model consensus on format decisions
3. Code review for completeness and clarity

Philosophy: robots.txt says what agents CANNOT do,
agents.md says what they CAN do.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Bruno Sarlo
2026-01-14 09:18:13 -03:00
parent f2b3a14685
commit da9207ded3
3 changed files with 327 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
README.md
View File

@@ -2,15 +2,18 @@
**Tell AI agents what they can do on your website.**
## The Gap
[![Version](https://img.shields.io/badge/version-1.0.0--draft-blue)]()
[![License](https://img.shields.io/badge/license-CC0-green)]()
| File | Purpose |
|------|---------|
| robots.txt | What bots **cannot access** |
## The Problem
| File | What it tells agents |
|------|---------------------|
| robots.txt | What you **cannot access** |
| llms.txt | What **content matters** |
| **agents.md** | What agents **can do** |
| **???** | What you **can do** |
## Quick Start
## The Solution
Create `/.well-known/agents.md`:
@@ -31,13 +34,20 @@ An online bookstore.
hello@mysite.com
```
That's it. Plain text. Human readable.
That's it. Plain text. Human readable. Machine parseable.
## With MCP Gateway
Point agents to your MCP server for structured tool access:
Point agents to your [MCP](https://modelcontextprotocol.io/) server for structured tool access:
```markdown
```yaml
---
version: "1.0"
mcp:
endpoint: https://mysite.com/.well-known/mcp
transport: streamable-http
auth: oauth2
---
# My Site
An online bookstore.
@@ -47,11 +57,6 @@ An online bookstore.
- Check prices
- Place orders (authenticated)
## MCP
endpoint: https://mysite.com/.well-known/mcp
transport: streamable-http
auth: oauth2
## Contact
hello@mysite.com
```
@@ -68,20 +73,31 @@ Agent requests /.well-known/agents.md
## Documentation
- [Specification](./spec/README.md) - Full protocol spec
- [Examples](./examples/) - Real-world examples
- [FAQ](./docs/FAQ.md) - Common questions
- **[Specification](./spec/README.md)** - Full protocol spec (v1.0.0-draft)
- **[Examples](./examples/)** - Real-world examples
- **[FAQ](./docs/FAQ.md)** - Common questions
- **[Changelog](./CHANGELOG.md)** - Version history
## Quick Comparison
| Aspect | robots.txt | llms.txt | agents.md |
|--------|------------|----------|-----------|
| Purpose | Crawl control | Content summary | Capabilities |
| Format | Custom | Markdown | Markdown + YAML |
| MCP | No | No | Yes |
## Status
**Draft** - Version 0.2.0
**v1.0.0-draft** - First public draft release
Feedback welcome via issues.
## Related Standards
- [robots.txt](https://www.rfc-editor.org/rfc/rfc9309) - Crawl restrictions (1994)
- [llms.txt](https://llmstxt.org/) - Content for LLMs (2024)
- [AGENTS.md](https://agents.md/) - Repository instructions (2025)
- [MCP](https://modelcontextprotocol.io/) - Tool protocol (2024)
- [robots.txt](https://www.rfc-editor.org/rfc/rfc9309) - RFC 9309 (1994)
- [llms.txt](https://llmstxt.org/) - Jeremy Howard (2024)
- [AGENTS.md](https://agents.md/) - OpenAI/Sourcegraph (2025)
- [MCP](https://modelcontextprotocol.io/) - Anthropic (2024)
## License