// agents.md
Document your multi-agent system.
Define agent roles, tools, triggers, and handoff rules. Get a structured AGENTS.md any agent runtime or LLM can read to understand the system.
Name
When to use
Role
Tools
Name
When to use
Role
Tools
Preview updates as you type
Fill in at least one agent name or role
// what is agents.md
The context file for multi-agent systems.
As AI systems grow from single models to multi-agent pipelines — with specialized agents, tool calls, and handoff logic — the complexity of keeping every agent oriented grows too. AGENTS.md is the document that describes the system to every agent in it.
It captures what each agent is responsible for, which tools it can call, when to hand off to another agent, and the global rules that apply regardless of which agent is executing. Think of it as the org chart and operating manual for your AI pipeline — in a single readable file.
Agent runtimes like Claude Code, OpenAI Agents SDK, and LangGraph can load this file as context at the start of every session, keeping all agents aligned with the same operating rules.
# AGENTS.md — Support Triage System > A three-agent pipeline that triages requests, resolves known issues, and escalates complex cases. ## Global Rules - Never make promises about timelines without confirmation - Always cite the source when referencing documentation ## Agents ### Triage Agent Reads incoming requests, classifies intent, and routes to the appropriate specialist agent. **Tools:** `classify_intent`, `search_kb` **When to use:** First contact on every request --- ### Resolver Agent Searches the knowledge base and resolves known issue types without human intervention. **Tools:** `search_kb`, `create_ticket`, `send_email` **When to use:** Known issue identified ## Handoff Logic Triage Agent always runs first. If confidence < 0.8, hand off to Escalation Agent.
// use cases
When do you need an AGENTS.md?
Customer support pipelines
A triage agent routes to specialists; specialists resolve or escalate. Without a shared context file, each agent runs blind to what the others can do.
Triage → Billing / Tech Support → EscalationCoding agent fleets
Orchestrator assigns tasks to specialized subagents (code, test, review). AGENTS.md defines the division of labour and prevents agents from stepping on each other.
Planner → Coder → Reviewer → DeployerResearch pipelines
One agent searches, another summarizes, another fact-checks, another formats. Roles and tool access need to be explicit so each agent stays in its lane.
Search → Summarize → Verify → ReportAutomated ops systems
Alert triage, runbook execution, and escalation to on-call — each step handled by a different agent with a different tool set. AGENTS.md is the playbook.
Alert → Diagnose → Remediate → Notify// faq
Frequently asked questions
Is AGENTS.md a standard format?
Not yet — there's no universal spec. The format generated here is designed to be readable by any LLM and loadable by any agent runtime that accepts markdown context files. It mirrors conventions emerging in Claude Code, OpenAI Agents SDK, and LangGraph documentation.
How is this different from a system prompt?
A system prompt defines one agent's behavior. AGENTS.md describes a system of agents — their relationships, tools, and handoff rules. You'd typically reference AGENTS.md from each agent's system prompt, or load it as a shared context object at orchestration time.
Where do I put the file?
In your project root as AGENTS.md — same location as CLAUDE.md or README.md. Some runtimes (like Claude Code) auto-load this file as context. Others require you to pass it explicitly as part of the system prompt or context window.
How many agents is too many?
Practically, keep it under 8 agents in a single AGENTS.md. Beyond that, the file becomes hard for the orchestrator to reason about in context. For larger systems, consider splitting into subsystem files and referencing them.
Should tools be function names or descriptions?
Use the exact function/tool names from your implementation. If your code exposes `search_knowledge_base`, write that — not 'search tool' or 'KB lookup'. The exact name is what the agent needs to call the tool correctly.
Do I need handoff logic if I only have two agents?
For two agents, the handoff is usually obvious and doesn't need documentation. The Handoff Logic section becomes essential at 3+ agents — especially when multiple agents can receive the same type of input and you need deterministic routing rules.