Agent Identity Documents: policy.md and Operational States
If you don’t tell a human team member which projects they can work on, that person doesn’t know what to do. The same is true for AI agents: not defining “what can you do, when can you do it, and what can you access” is organizational chaos.
This is where policy.md comes in. It’s a file that defines an agent’s responsibilities, access rights, and capabilities, much like a job description or role card for a human employee. But policy.md is not just paper: it must be systematically applied, tracked, and versioned.
What Does a Policy Define?
An agent’s policy.md specifies:
- Job boundaries: Which projects, deadlines, budget, or data categories can it touch?
- Capabilities: Which APIs, CLI tools, functions can it access? (builtin vs. mcp vs. http vs. function)
- Approval mechanisms: Are human approvals required for certain tasks or risk levels?
- Error and reporting: How does it log tasks? Who gets notified on failure?
For example, a “Technical Writer Agent” might be defined as:
Policy: Technical Writer Agent
- Projects: [docs, blog]
- Skills: [file_write, web_search, git_commit]
- Budget: max 5000 tokens per task
- Approval required for: commits to main branch
- Error escalation: ops-team@company.comThis might seem simple, but this definition can:
- Prevent accidental access to production data.
- Guard against unexpectedly expensive AI calls.
- Automatically notify the right people if a task fails.
Agent States: Draft, Active, Passive
An agent’s lifecycle is tracked across three states:
Draft
The agent is not yet live. It’s being tested, its policy is being written, and no one gives it work. A failed or removed draft breaks nothing.
Active
The agent is running production tasks. Its policy is final, its capabilities are limited and monitored, and it has defined accountability. Here, errors, data loss, or delays matter.
Passive
The agent no longer takes new work but continues finishing existing tasks. It operates under its old policy and capabilities; it doesn’t receive new policy updates or permission changes. This allows you to gracefully wind down task flow without abruptly shutting it down.
Without such a structure, agents drift with old policies, causing conflicts.
Types of Capabilities
In a policy, the question “Which tools can it access?” is critical:
- builtin: Functions provided by Hermes or your platform. Fast, reliable, limited.
- mcp: Locally installed MCP servers. More flexible, for custom business logic.
- http: External APIs. Internet dependency, latency, authentication risk.
- function: Custom Python/Node functions. Most flexible, but highest risk (arbitrary code execution).
Each capability level requires different levels of risk tolerance and trust. A policy must explicitly list which tool types an agent can use.
Why This Matters
Ask your organization: “Last week, how many people used a prompt that let ChatGPT run git push?” Often, the answer is unknown, because everyone makes their own choice with no central policy.
With policy.md:
- Every agent’s permissions are visible in version control (Git).
- To change access, you open a PR and get human approval.
- Audit trails (who changed what and when) happen automatically.
- Old policies remain in Git history.
The Next Step
Policy.md only has power in an environment controlled by your organization. You can’t change a Slack bot’s policy or public ChatGPT’s policy; but you can manage your own self-hosted agents’ policies in Git, via PRs.
If you don’t see many other organizations systematically defining agent policies in policy.md and versioning them, you’re ahead. That’s both accountability and competitive advantage.
After this series, how deeply can you write policy.md for your own agents? What capabilities does your operation need to restrict?