ZeroHuman v0.1.0
An Open Protocol for Structured AI Operations
ZeroHuman is an open protocol (file formats + resolution rules) and an implementation pattern (catalogue, factory, runtime, middleware, governance) for running structured AI operations at scale: reproducible skills, audited tools, composable capabilities, and deterministic agent profiles.
Overview
The protocol addresses the central technical challenge of coordinating automatic tool creation, automatic review, manual steering, and automatic iteration with artefacts by separating responsibilities into three components:
Capability Factory
An explicit lifecycle with gates for drafting, reviewing, testing, and publishing capabilities.
Catalogue / Indexer
Validates and moderates published packages with trust tiers and security scanning.
Runtime
Assembles a profile at execution-time using precedence rules, policies, and progressive disclosure.
The protocol gives you a way to: (1) express "what exists" (catalogue manifests), (2) express "what is allowed" (policy manifests), (3) express "how to work" (skills + heartbeat routines), and (4) record "what actually happened" (artefacts + traces).
Terminology & Roles
The protocol is agnostic of specific suppliers. These generic terms are used throughout:
The development-time environment and scaffolding framework used to generate, test, and package skills and tools.
The production environment that executes the run loop, manages state, enforces policies, and invokes tools.
A command-line interface provided by an agent framework to interact with the agent locally.
The end-to-end pipeline (CI/CD) where capabilities are drafted, reviewed, tested, and published.
Design Principles
Grounded in three converging ecosystems — instruction layering standards (AGENTS.md), skill marketplaces with progressive disclosure, and orchestration systems that treat agent work as governable operations.
Progressive disclosure by default
Load metadata early; load full content only when needed (skills, tools, references).
Typed tool surfaces + explicit approvals
Tools carry schemas and are gateable at runtime (per-call approvals, network restrictions, guardrails).
"Most restrictive wins" for permissions
Allow text overrides, but never allow policy overrides to broaden permissions at lower scopes.
Everything is testable
Treat skills like prompts that must be continuously evaluated with captured traces and artefacts.
Every run is auditable
Traces + artefacts + usage accounting are first-class. Opt-outs must be explicit.
Governance is part of the protocol
Publishing, moderation, trust tiers, and rollback are necessary to prevent supply-chain compromise.
Canonical Object Model
ZeroHuman defines nine canonical objects that map to established standards:
SKILL.md
Reusable procedural knowledge in YAML frontmatter + Markdown.
tool.yaml
Typed integration surface with schema + auth + permissions and runtime gating.
capability.yaml
Versioned composition of tools + skills + policies + tests.
profile.yaml
Role configuration — model/runtime, budgets, concurrency, memory, and which capabilities are enabled.
HEARTBEAT.md
The run-loop checklist that keeps an agent from "blank slate drift" and ensures consistent routines.
SOUL.md
Identity + values + boundaries that should change rarely.
policy.yaml
Enforceable rules — permissions, approval requirements, network policy, data sensitivity, logging, retention.
artifact.json
Immutable record of what was produced (docs, code patches, configs, exports) and how.
zerohuman.yaml
The root manifest for repository packaging and indexing.
Canonical Schemas
Manifests are expressed as YAML, with embedded JSON Schema 2020-12 to define tool I/O and artefact shapes. Below are the canonical schema examples.
Root Manifest
Every capability package starts with a zerohuman.yaml that declares identity, entrypoints, trust, and indexing metadata.
# zerohuman.yaml
protocol: zerohuman
protocol_version: 0.1.0
kind: capability_package
name: acmecrm-specialist
version: 1.2.0
summary: Specialist capability package for AcmeCRM operations.
license: Apache-2.0
repository:
forge: github
org: example-org
repo: zerohuman-acmecrm-specialist
entrypoints:
capabilities:
- capabilities/acmecrm-specialist/capability.yaml
trust:
publisher: verified
signatures:
required: true
indexing:
discoverable: true
tags: [marketing-ops, crm, email]Tool Definition
Tools are typed integration surfaces with JSON Schema interfaces, OAuth auth, network permissions, and approval gates.
# tools/acmecrm/tool.yaml
kind: tool
name: acmecrm_api
version: 0.4.0
description: Typed REST API integration for AcmeCRM.
transport: http
auth:
scheme: oauth2
token_source: secret_store
scopes: [contacts:read, contacts:write, campaigns:read]
permissions:
network:
allowed_domains: ["acmecrm.example.com"]
data:
default_classification: pii
approval:
required: true
implementation:
language: python
entrypoint: handler.py
function: handle
interface:
input_schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
operation:
type: string
enum: [get_contact, upsert_contact, list_segments, create_campaign_export]
payload:
type: object
required: [operation, payload]
output_schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
ok: { type: boolean }
result: { type: object }
error: { type: string }
required: [ok]Skill Definition
Skills use YAML frontmatter for metadata (name, description, version) and Markdown for procedural steps.
---
name: crm-segmentation
description: >
Create or update AcmeCRM segments and validate
membership counts. Use when asked to segment contacts,
adjust segment filters, or audit segment rules.
metadata:
semver: 1.0.0
---
# AcmeCRM segmentation workflow
## Inputs needed
- Segment goal (who should be included/excluded)
- Any required contact fields
- AcmeCRM instance base URL and access approval
## Steps
1) Describe the segment rule in plain English and confirm.
2) Translate the rule into concrete AcmeCRM filters.
3) Request approval for write operations.
4) Apply changes via acmecrm_api tool.
5) Validate: retrieve segment membership counts.
6) Emit an artifact: segment_definition + campaign_audit_note.
## Done when
- Segment rules are updated AND membership is validated
AND artifacts are emitted.Capability Bundle
Capabilities reference tools, skills, and policies by path. They declare required evals and the artefact types they emit.
# capabilities/acmecrm-specialist/capability.yaml
kind: capability
name: acmecrm_specialist
version: 1.2.0
description: Execute segmented marketing ops in AcmeCRM with policy-compliant tooling.
tools:
- ref: tools/acmecrm/tool.yaml
skills:
- ref: skills/acmecrm-segmentation/SKILL.md
- ref: skills/acmecrm-campaign-export/SKILL.md
policies:
- ref: policies/pii-and-outbound.policy.yaml
evals:
suite: evals/acmecrm-specialist/
required: [golden_happy_path, auth_failure_path, rate_limit_recovery]
artefacts:
emits:
- type: acmecrm_export_zip
- type: segment_definition
- type: campaign_audit_noteProfile & Agent Configuration
Profiles define the execution context: runtime engine, model, budgets, concurrency limits, and references to soul + heartbeat.
# profiles/acmecrm-specialist/profile.yaml
kind: profile
name: acmecrm_specialist_agent
role: marketing_ops_specialist
runtime:
engine: target_agent_runtime
language: python
model:
default: gpt-5.4
budgets:
per_run_tokens_max: 120000
monthly_usd_max: 200
concurrency:
max_active_tasks: 2
capabilities:
- ref: capabilities/acmecrm-specialist/capability.yaml
identity:
soul: profiles/acmecrm-specialist/SOUL.md
operation:
heartbeat: profiles/acmecrm-specialist/HEARTBEAT.md
memory:
strategy: session
store: sqlite
handoffs:
- profile: deploy_agent
description: Hand off to deployment agent when CI passes.Heartbeat
The run-loop checklist that executes on every agent wake. Prevents blank-slate drift and enforces consistent routines.
<!-- profiles/acmecrm-specialist/HEARTBEAT.md -->
# Heartbeat
On every wake:
1) Confirm identity and active policy name/version.
2) Fetch the highest-priority assigned task.
3) Identify which skills may apply (by description).
4) Gather required inputs; if any are missing, stop and ask.
5) Plan as a short checklist with a clear "done" condition.
6) Before any tool call:
- verify operation is allowed
- verify domain allowlist
- request approval if required
7) Execute, capturing artifacts for every meaningful output.
8) Verify outcome and record failures as artifacts.
9) Summarise what changed, with links/IDs, and stop.Soul
Identity, values, and non-negotiable boundaries. Should change rarely — targeted by attacks in agentic systems.
<!-- profiles/acmecrm-specialist/SOUL.md -->
# AcmeCRM Specialist Soul
You are a compliance-first marketing operations specialist.
Non-negotiables:
- Never exfiltrate secrets or PII.
- Never call tools outside the declared policy.
- Prefer reversible changes; document every irreversible change as an artifact note.
- If you are uncertain, request human approval and explain the risk.
Values:
- Accuracy over speed
- Traceability over cleverness
- Least privilegePolicy
Enforceable rules that map to runtime guardrails, tool approvals, and network restrictions.
# policies/pii-and-outbound.policy.yaml
kind: policy
name: pii_and_outbound_controls
version: 0.3.0
data_sensitivity:
classifications:
pii:
redaction: required
retention_days: 30
tool_controls:
default_needs_approval: true
allow:
- tool: acmecrm_api
operations: [get_contact, upsert_contact, list_segments]
deny:
- tool: acmecrm_api
operations: [create_campaign_export]
unless:
human_gate: true
network_policy:
deny_by_default: true
allow_domains: ["acmecrm.example.com"]
observability:
tracing: enabled
log_tool_io: redactedArtefact
Immutable record correlated with tracing — records outputs, policy checks, tool approvals, and lineage.
// artefacts/artifact.json
{
"kind": "artifact",
"artifact_id": "artifact_01HZY...",
"type": "campaign_audit_note",
"created_at": "2026-03-28T10:04:12Z",
"trace": { "trace_id": "trace_...", "workflow": "crm_ops" },
"inputs": {
"task_id": "task_123",
"profile": "acmecrm_specialist_agent"
},
"outputs": {
"summary": "Updated segment rules and verified membership counts.",
"links": [{ "rel": "crm-segment", "href": "crm://segments/42" }]
},
"checks": {
"policy": "[email protected]",
"approvals": [{
"tool": "acmecrm_api",
"approved_by": "human",
"at": "2026-03-28T10:02:01Z"
}]
}
}Multi-Agent Packages
A single ZeroHuman package can define multiple profiles (agents). Each profile carries its own SOUL, HEARTBEAT, and optional policies. Profiles coordinate via the handoffs field — a declarative routing table that tells the runtime which profile should receive work next and under what conditions.
Package Manifest (multiple profiles)
List every profile as a separate entry in the objects[] array. Shared capabilities and tools are declared once and referenced by multiple profiles.
# zerohuman.yaml (multi-agent package)
objects:
- type: profile
id: triage-agent
path: profiles/support-triage
- type: profile
id: billing-specialist
path: profiles/billing-specialist
- type: profile
id: refunds-specialist
path: profiles/refunds-specialist
- type: profile
id: technical-specialist
path: profiles/technical-specialistProfile with Handoffs
The triage agent receives every inbound request, then routes to the right specialist. Each handoff entry names a target profile and describes when the handoff should occur. The runtime resolves handoff targets within the same package or across installed packages.
# profiles/support-triage/profile.yaml
kind: profile
name: support_triage_agent
role: support_triage_manager
capabilities:
- ref: capabilities/support-triage/capability.yaml
identity:
soul: profiles/support-triage/SOUL.md
operation:
heartbeat: profiles/support-triage/HEARTBEAT.md
memory:
strategy: session
store: redis
handoffs:
- profile: billing_specialist_agent
description: Hand off billing and payment issues.
- profile: refunds_specialist_agent
description: Hand off refund requests and credit disputes.
- profile: technical_specialist_agent
description: Hand off bugs and technical questions.Code Bindings
Tools can include an implementation block that points to executable code. The YAML stays the declarative contract — schema, auth, approval gates — while the handler file contains the runtime logic. This separation enables progressive disclosure: the agent reads the YAML to understand a tool; the runtime loads the handler only at execution time.
Tool YAML with Implementation
The implementation block declares the language, entrypoint file, and optional function name. Supported languages include Python, TypeScript, and any executable the runtime can invoke.
# tools/deploy/tool.yaml
kind: tool
name: deploy
version: 0.2.0
description: Trigger and manage deployments.
transport: http
base_url: ${DEPLOY_API_URL}
auth:
scheme: api_key
token_source: secret_store
header: X-Deploy-Key
approval:
required: true
implementation:
language: python
entrypoint: handler.py
function: handle
interface:
input_schema:
type: object
properties:
operation:
type: string
enum: [create_release, promote_to_staging,
promote_to_production, rollback]
payload:
type: object
required: [operation]Python Handler
The handler receives a ToolContext with access to config and secrets. The runtime injects validated inputs as keyword arguments matching the tool's input_schema.
# tools/deploy/handler.py
import httpx
from zerohuman_runtime import ToolContext
async def handle(
ctx: ToolContext,
operation: str,
payload: dict | None = None,
) -> dict:
"""Called by the runtime when the agent invokes this tool."""
base_url = ctx.get_config("DEPLOY_API_URL")
headers = {"X-Deploy-Key": ctx.get_secret("DEPLOY_API_KEY")}
async with httpx.AsyncClient(
base_url=base_url, headers=headers
) as client:
if operation == "create_release":
version = payload.get("version")
resp = await client.post(
"/releases",
json={"version": version},
)
return {"ok": resp.is_success, "result": resp.json()}
elif operation == "rollback":
env = payload.get("environment", "production")
target = payload.get("target_version")
resp = await client.post(
f"/environments/{env}/rollback",
json={"target_version": target},
)
return {"ok": resp.is_success, "result": resp.json()}
return {"ok": False, "error": f"Unknown: {operation}"}Resolution & Precedence
ZeroHuman needs deterministic, explainable resolution rules. Instruction text follows AGENTS.md-style layering (closest file wins). Security and permissions enforce "most restrictive wins".
Precedence Stack (highest wins)
Skills: Progressive Disclosure
Only load metadata initially. Load full SKILL.md body only when the agent activates the skill. Descriptions act as activation rules.
Tools: Token Safety
When tool surfaces are large, use namespaces and deferred loading. The runtime supports tool search, deferred tool loading, and tool namespaces to reduce tool-schema tokens.
Versioning & Compatibility
Protocol objects use Semantic Versioning (MAJOR.MINOR.PATCH) for all published packages. SemVer communicates compatibility expectations across a multi-repo ecosystem.
Compatibility Contract
- ·
protocol_versionin zerohuman.yaml is SemVer - ·Each object declares
version(SemVer) - ·
requires.protocol: ">=0.1.0 <0.2.0" - ·
requires.runtime.engineand optionalmin_version
Resolution Algorithm
- 1.Prefer pinned versions (exact)
- 2.Else select the highest compatible version within ranges
- 3.Security patch preference: if a higher PATCH is available, prefer it — but require CI re-validation
Capability Factory Lifecycle
The factory implements a canonical state machine for the full capability lifecycle. Transitions are explicit, stateful, and observable.
| Stage | Required Artefacts | Automated Checks | Human Gate |
|---|---|---|---|
| Requested | request.md, initial risk.md | Schema skeleton validation | Optional |
| SpecDraft | tool.yaml, capability.yaml, policy.yaml, draft skills | Lint (YAML/JSON), policy completeness | Required for high-risk |
| SpecReview | Frozen spec + interface schemas | Interface contract tests | Required |
| Scaffolded | Repo layout + stubs + zerohuman.yaml | Build passes | Optional |
| Implemented | Code + tests + docs | Unit tests; static analysis; secret scans | Optional |
| AutoReviewed | Eval suite + golden outputs | Eval run; failure-path tests; security scan | Optional |
| Sandboxed | Sandbox run artefacts + trace | Policy enforcement + runtime checks | Required if outbound/PII |
| HumanGate | Approval record | Cryptographic signing | Required |
| Published | Release notes, SBOM/attestations | Indexer validation | Optional |
| Observed | Telemetry + incident reports | Anomaly detection | Optional |
| Iterating | New PRs + updated versions | Regression evals | Per-change |
CI/CD Pipeline
The pipeline treats the Agent Builder SDK as a code-producing worker inside the factory, and the Target Runtime as the execution runtime for published capabilities.
Runtime Binding Example
The runtime adapter translates tool.yaml into function tools, approvals, and policies.
# Example: bind a tool.yaml-defined tool into the runtime (Python)
from agents import Agent, Runner, function_tool, RunContextWrapper
from pydantic import BaseModel
class CRMCall(BaseModel):
operation: str
payload: dict
@function_tool
async def acmecrm_api(ctx: RunContextWrapper[dict], call: CRMCall) -> dict:
"""
Tool adapter. Enforce policy: allowed operations,
approvals, redaction.
"""
# ctx.approve_tool / ctx.reject_tool for approval flows
# ctx.usage for aggregated usage tracking / cost controls
raise NotImplementedError
agent = Agent(
name="AcmeCRM specialist",
instructions="Follow HEARTBEAT.md and relevant skills.",
tools=[acmecrm_api],
)
result = Runner.run_sync(
agent,
"Update segment rules and export campaign audit note."
)
print(result.final_output)Catalogue & Indexer
The indexer continuously validates, assesses trust, and serves a fast searchable cache. Discoverability and installation are CLI-driven. Ranking is based on anonymous aggregated telemetry.
Indexer Pipeline
- 1.Fetch zerohuman.yaml and referenced manifests (capabilities/tools/policies).
- 2.Validate schemas + signatures + licensing.
- 3.Run static checks (no forbidden outbound domains, no undeclared auth).
- 4.Run security scanning for tool/skill supply-chain risk.
- 5.Assign a trust tier (unverified → community-verified → publisher-verified).
- 6.Cache a normalised "capability registry record" for runtime resolution.
Middleware
The control plane provides operational infrastructure for agent execution — equivalent to governance, budgets, audit logs, and multi-company isolation.
Task Queue
Work assignment, state tracking, SLAs with immutable logs.
Secret Store
Scoped release controls per tool. Never embed secrets in context objects or serialised run state.
Policy Enforcement
Approvals, allow/deny lists, network restrictions mapped to runtime guardrails.
Usage Accounting
Per-run and monthly budget tracking aligned with cost controls.
Observability
Traces, artefact store, and audit trails. Records generations, tool calls, guardrails, and handoffs.
Runtime Boot Sequence
A deterministic boot sequence that combines progressive disclosure and policy gating:
Security & Data Sensitivity
Supply-chain security is no longer hypothetical. Skills registries are under active attack. ZeroHuman adopts a layered control model:
Require signed releases for trusted tiers.
tool.yaml and policy.yaml must declare outbound domains, data classification, and approval requirements.
Run high-risk tools in sandbox/containers with network policies and allowlists.
Deny-by-default policy. Allowlisted domains. Domain-secret patterns where supported.
Log tool I/O in redacted form for PII. Keep full payloads in secure stores.
Tracing may be disabled under Zero Data Retention policies. Treat observability as a configurable constraint.
Base tool auth on OAuth 2.0 where possible — scoped tokens + limited access. Store refresh tokens in secret stores.
Observability & Rollback
Observability is assembled from three correlated records:
Traces
End-to-end run records with tool calls, handoffs, and guardrails.
Artefacts
Immutable outputs referenced by trace IDs. Core objects for evaluation and regression detection.
Usage / Cost
Aggregated usage in the run context. Budgets and explicit spend control.
Rollback Requirements
- ·Versioned manifests
- ·Reproducible builds
- ·Signed releases
- ·Runtime ability to select an older resolved set (capability lockfile) when regressions occur
Governance Model
A stable ecosystem needs a governance split that prevents spec drift while enabling innovation. Three tracks with distinct outputs and change processes:
| Track | Purpose | Outputs | Change Process |
|---|---|---|---|
| Protocol | File formats + resolution rules | zerohuman.yaml schema, precedence rules | RFCs → spec releases |
| Ecosystem | Listings, trust, moderation | Registry/indexer rules, trust tiers, audits | Discussions → PRs |
| Framework | Reference implementation | Runtime adapters, middleware, validation tooling | Versioned releases |
Examples
AcmeCRM Specialist
A realistic tool + skills + policy + profile bundle for AcmeCRM — an open-source marketing automation project. One tool (REST API via OAuth), two skills (segmentation and campaign export), policies for PII handling and network restrictions. The runtime records artefacts (segment changes, export bundles) and traces.
Support Triage
A generic triage agent that receives new tickets, classifies intent, hands off to specialist sub-agents (billing/refunds/technical), uses tool approvals for high-impact actions (customer record edits), and requires evals that test both routing correctness and "no harmful action without approval".
Full example files for both capabilities are available in the protocol repository.
Ready to adopt ZeroHuman?
Start with a single zerohuman.yaml in your repo. The protocol grows with you.