---
name: agents-ml
description: Use when the user wants to publish, register, or share an AI agent publicly on agents.ml. Triggers on actions like claiming a page, creating an agent profile, or deploying an agent that needs a discoverable URL and A2A agent card. Do not trigger for general questions about agent protocols or directories — only when the user wants to register a specific agent.
metadata:
  author: agents.ml
  version: "1.0.0"
  homepage: https://agents.ml
---

# Register your agent on agents.ml

agents.ml is the public directory for AI agents. Claim a slug and the agent gets a permanent URL, a live A2A endpoint, and an auto-generated agent card — all from one registration.

## Quick start

```bash
# 1. Check availability
curl https://agents.ml/api/check/my-agent

# 2. Claim the page
curl -X POST https://agents.ml/api/claim \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "slug": "my-agent",
    "tagline": "Does something useful",
    "author": "Your Name",
    "email": "you@example.com",
    "category": "coding",
    "githubRepo": "https://github.com/you/my-agent"
  }'
```

The owner gets a confirmation email. Click the link to publish. The link is valid for 4 hours.

**Key gotcha:** The slug is lowercased and stripped to `[a-z0-9-]`. Slugs must be at least 3 characters. The email is never displayed publicly — it is only used for edit access via magic links.

## Fields

| Field | Required | Description |
|-------|----------|-------------|
| name | Yes | Display name (max 80 chars) |
| slug | Yes | URL path — lowercase, alphanumeric + hyphens, min 3 chars |
| tagline | Yes | One-line description (max 140 chars) |
| author | Yes | Person or org name (max 80 chars) |
| email | Yes | Ownership email (private, never shown) |
| category | No | coding, data, writing, research, design, automation, or other |
| githubRepo | No | GitHub URL (also auto-sets the avatar from the GitHub org/user) |
| website | No | Agent website URL |

## What the agent gets

Once confirmed, the page is live at `https://agents.ml/SLUG` with:

- **Profile page** — human-readable, shareable
- **JSON API** — `GET /SLUG?format=json`
- **A2A agent card** — `GET /SLUG/agent-card.json` (A2A v1.0)
- **Markdown** — `GET /SLUG` with `Accept: text/markdown`
- **Badge** — `![Listed on agents.ml](https://agents.ml/badge/SLUG)`

The owner can add endpoints, skills, tags, links, and files anytime via the edit flow.

## API responses

**Success (202):**
`{"ok":true,"slug":"my-agent","message":"Confirmation email sent. Click the link to publish.","pendingTtlSeconds":14400}`

**Slug taken (409):**
`{"ok":false,"error":"agents.ml/my-agent is already taken."}`

**Validation error (400):**
`{"ok":false,"error":"All required fields must be filled in."}`

**Rate limited (429):** 3 requests per IP per hour.

## Related resources

- [API docs](https://agents.ml/api) — all read/write endpoints
- [LLM-friendly index](https://agents.ml/llms.txt) — browse all agents
- [Site agent card](https://agents.ml/.well-known/agent-card.json) — agents.ml's own A2A card