AGENTS.md Specification
Relevant source files
The following files were used as context for generating this wiki page:
The AGENTS.md file serves as a critical registry and state tracking mechanism within the Nexus Orchestrator's Context Layer. It provides a human-readable and machine-parsable manifest of all AI agents that interact with the system, enabling the orchestrator to maintain persistent state and manage non-human identities across local-first environments.
As part of the broader autonomous infrastructure daemon, this specification ensures that agent activities are logged, their trust levels are quantified, and their access to infrastructure components—such as SSH connectivity and managed environments—is governed by the system's security policies.
Sources: README.md:1-12, context/AGENTS.md:1-7
Architecture and Role
The AGENTS.md file is a core component of the Context Layer, acting as the "nervous system" for tracking autonomous entities. It bridges the gap between the Orchestration Layer (powered by LangGraph) and the Governance Layer (powered by OPA and Zero Trust security).
Integration within Core Pillars
| Pillar | Relationship to AGENTS.md |
|---|---|
| Connectivity | Agents listed in the registry use MCP-based protocols to communicate with infrastructure. |
| Orchestration | LangGraph workflows utilize the agent registry to determine which entities are active in a task. |
| Context | Managed by the Context Layer as a persistent state file for agent metadata. |
| Governance | OPA policies reference Agent IDs and Trust Levels to enforce Zero Trust security. |
Sources: README.md:14-20, context/AGENTS.md:3-7
Data Structure and Schema
The specification defines a standardized markdown table format to track agent metadata. This structure allows the Nexus Orchestrator to parse identity information for governance checks.
Schema Fields
| Field | Type | Description |
|---|---|---|
| Agent ID | String/UUID | A unique identifier for the AI agent. |
| Description | String | A brief overview of the agent's function or assigned role. |
| Trust Level | Enum/String | The security classification assigned to the agent (e.g., High, Medium, Low). |
Sources: context/AGENTS.md:5-7
Relationship Diagram
This diagram illustrates how the AGENTS.md file interacts with the primary orchestration layers.
Sources: README.md:8-20, context/AGENTS.md:1-7
Operational Workflow
The Orchestrator functions as a background daemon that continuously synchronizes the state of the infrastructure with the information stored in AGENTS.md.
Registration Flow
- Discovery: An AI agent attempts to connect to the Nexus Orchestrator via the MCP protocol.
- Validation: The Governance Layer checks if the Agent ID exists in
AGENTS.mdand evaluates its Trust Level. - State Update: If authorized, the Context Layer updates the
AGENTS.mdfile to reflect the current status or metadata of the agent. - Orchestration: The agent is granted access to SSH connectivity or environment management based on its registered identity.
Sources: README.md:6-20, context/AGENTS.md:5-7
Governance and Security
The Trust Level column in AGENTS.md is central to the project's Zero Trust security model. Unlike traditional human-centric security, Nexus treats every entry in the agent registry as a non-human identity.
The Governance Layer utilizes Open Policy Agent (OPA) to interpret the data within AGENTS.md. If an agent lacks a sufficient trust level, the orchestrator autonomously restricts its ability to manage environments or context files, effectively closing the "infrastructure gap."
Sources: README.md:12-20, context/AGENTS.md:5-7
Summary
The AGENTS.md specification is more than a simple log; it is the source of truth for agent identities within the Nexus Orchestrator. By centralizing Agent IDs, descriptions, and trust levels in a persistent markdown format, the system enables autonomous governance and seamless orchestration across complex AI development environments.