📦
What agents are actually deployed?
Many teams cannot produce a current inventory of agents, capabilities, or operating scope.
open standard / documentation-first
The open standard for AI agent documentation and governance
A file-first, machine-readable framework for agent inventory, access scope, oversight, validation, and compliance context. Built for teams that want governance artifacts in source control instead of slide decks.
Current draft: HelixDocs specification v1.0.0
spec / validator / registry
.agents.yamlv1.0.0
version: 1.0.0
agent:
id: research-analyst-v4
owner: operations-core
capabilities:
- search
- data-export
governance:
access: scoped-read-only
audit: persistent
human_oversight: required
$ helixdocs validate .agents.yaml
✓ Specification valid
✓ Required governance fields present
Registry digest: sha256:e3b0c442...human layer / machine layer
This page is the human-readable layer of the standard.
Agents and tooling can discover the machine-readable entry points here:
why this exists
Most agent systems are easier to run than to document.
🔐
What access has been granted?
Agents call APIs, process documents, and interact with internal systems. Governance starts with explicit permissions.
📚
What can be shown to auditors or customers?
Technical documentation, oversight controls, and processing context should be machine-readable and reviewable.
lifecycle
Declare, validate, publish.
The workflow is intentionally simple: define the agent in a documented schema, validate it in CI, and publish the resulting record to a shared registry or trust surface.
01declare
agent:
id: support-router-eu
owner: support-platform
interfaces:
- email
- crm
governance:
access: customer-record-read
oversight: escalation-requiredDescribe identity, interfaces, scope, and governance controls in a single machine-readable document.
02validate
$ helixdocs validate .agents.yaml
✓ schema version supported
✓ oversight field present
✓ access scope documented
✓ processing metadata complete
Run deterministic checks in local development or CI so required documentation fields do not depend on manual review alone.
03publish
registry_id: org/support-router-eu
schema: agents.yaml v1.0.0
digest: sha256:8f2d4c10…
status: valid
updated_at: 2026-03-21T14:22:00Z
Publish a canonical record for discovery, review, customer trust pages, or internal inventory systems.
registry
A registry for documented agent records.
The registry view is not a product dashboard gimmick. It represents the kind of structured discovery index that teams, auditors, and downstream systems can query or review.
records1,248
schema drift0.02%
⌕filter by id, owner, digest, or status
research-analyst-v4
org/research-analyst-v4
Schema
agents.yaml v1.0.0
Owner
operations-core
Digest
sha256:e3b0c442…
Last updated
2026-03-21 14:22 UTC
Note
validated
support-router-eu
org/support-router-eu
Schema
agents.yaml v1.0.0
Owner
support-platform
Digest
sha256:8f2d4c10…
Last updated
awaiting oversight review
Note
oversight pending
legacy-sync-worker
org/legacy-sync-worker
Schema
agents.yaml v0.9.2
Owner
integration-team
Digest
sha256:91ae77bc…
Last updated
2026-03-19 09:12 UTC
Note
schema upgrade required
devops-automata
org/devops-automata
Schema
agents.yaml v1.0.0
Owner
platform-engineering
Digest
sha256:d91ef23a…
Last updated
2026-03-20 16:05 UTC
Note
published
specification
One file. Structured governance context.
.agents.yaml is designed as a source-controlled description of agent identity, risk posture, oversight requirements, and processing context.
solution.example.yamlmachine-readable
agents:
- id: "acme/support-bot"
risk_class: limited
autonomy_level: supervised
data_processing:
legal_basis: "Art. 6(1)(b) DSGVO"
human_oversight:
required: true📄
file-first
File-first and portable
A plain text document in your repository. No proprietary control plane required.
🛡️
compliance-aware
Aligned with governance requirements
Fields can map to EU AI Act, DSGVO, NIS2, and internal review processes.
🌱
incremental
Start small, extend when needed
A team can begin with a minimal record and evolve toward fuller technical documentation.
regulatory mapping
Built for the frameworks teams already answer to.
EU AI Act Art. 11Technical documentation for high-risk AI
EU AI Act Art. 9Risk management system
EU AI Act Art. 14Human oversight requirements
EU AI Act Art. 50Transparency obligations
DSGVO Art. 30Records of processing activities (VVT)
NIS2Security incident documentation
community
An open standard should be developed in public.
HelixDocs is intended to feel closer to infrastructure documentation than to marketing collateral: explicit schema decisions, reusable tooling, and public discussion.
📄
license
Specification under CC-BY-4.0
The specification is intended to be reused, discussed, and implemented across tools and organizations.
🧰
tooling
Reference tooling under MIT
Validators, generators, and CI integrations should remain inspectable, composable, and easy to adopt.
🌐
governance
Developed in public
Schema evolution, implementation notes, and open questions belong in the open — not behind vendor workflows.
audience
For teams that need documentation to survive contact with reality.
Platform & AI engineers
A practical schema for describing agents, capabilities, and controls in source control.
Compliance & governance teams
A consistent structure for documentation, oversight, and processing context.
CTOs & technical leadership
A shared format for understanding what an AI estate contains and how it is governed.
Security & DevOps
Validation and review workflows that can run in CI instead of ad-hoc spreadsheet processes.
early access
Follow the standard, review the schema, or join early product access.
The specification stands on its own. If you want updates on tooling, validators, or hosted workflows, you can leave an email here.