ZeroHuman
Protocol Specification

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:

Agent Builder (Builder SDK)

The development-time environment and scaffolding framework used to generate, test, and package skills and tools.

Target Runtime (Agent Runtime)

The production environment that executes the run loop, manages state, enforces policies, and invokes tools.

Agent CLI

A command-line interface provided by an agent framework to interact with the agent locally.

Capability Factory

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.

01

Progressive disclosure by default

Load metadata early; load full content only when needed (skills, tools, references).

02

Typed tool surfaces + explicit approvals

Tools carry schemas and are gateable at runtime (per-call approvals, network restrictions, guardrails).

03

"Most restrictive wins" for permissions

Allow text overrides, but never allow policy overrides to broaden permissions at lower scopes.

04

Everything is testable

Treat skills like prompts that must be continuously evaluated with captured traces and artefacts.

05

Every run is auditable

Traces + artefacts + usage accounting are first-class. Opt-outs must be explicit.

06

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

SKILL.md

Reusable procedural knowledge in YAML frontmatter + Markdown.

Tool

tool.yaml

Typed integration surface with schema + auth + permissions and runtime gating.

Capability

capability.yaml

Versioned composition of tools + skills + policies + tests.

Profile

profile.yaml

Role configuration — model/runtime, budgets, concurrency, memory, and which capabilities are enabled.

Heartbeat

HEARTBEAT.md

The run-loop checklist that keeps an agent from "blank slate drift" and ensures consistent routines.

Soul

SOUL.md

Identity + values + boundaries that should change rarely.

Policy

policy.yaml

Enforceable rules — permissions, approval requirements, network policy, data sensitivity, logging, retention.

Artefact

artifact.json

Immutable record of what was produced (docs, code patches, configs, exports) and how.

Manifest

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.yamlyaml
# 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.

tool.yamlyaml
# 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.

SKILL.mdmarkdown
---
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.

capability.yamlyaml
# 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_note

Profile & Agent Configuration

Profiles define the execution context: runtime engine, model, budgets, concurrency limits, and references to soul + heartbeat.

profile.yamlyaml
# 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.

HEARTBEAT.mdmarkdown
<!-- 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.

SOUL.mdmarkdown
<!-- 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 privilege

Policy

Enforceable rules that map to runtime guardrails, tool approvals, and network restrictions.

policy.yamlyaml
# 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: redacted

Artefact

Immutable record correlated with tracing — records outputs, policy checks, tool approvals, and lineage.

artifact.jsonjson
// 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.yamlyaml
# 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-specialist

Profile 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.yamlyaml
# 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.yamlyaml
# 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.pypython
# 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)

1Explicit user/task input
Task payload + human steering notes
2Task-local overrides
Task folder overlays (e.g. tasks/<id>/AGENTS.override.md)
3Profile overlays
Profile-specific heartbeat + soul + profile policy
4Capability package content
capability.yaml → skills / tools / policies
5Organisation global policy
Org-level AGENTS.md and baseline instructions
6Runtime defaults
Engine defaults and safe baselines

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_version in zerohuman.yaml is SemVer
  • ·Each object declares version (SemVer)
  • ·requires.protocol: ">=0.1.0 <0.2.0"
  • ·requires.runtime.engine and optional min_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.

Requested→ SpecDraft→ SpecReview→ Scaffolded→ Implemented→ AutoReviewed→ Sandboxed→ HumanGate→ Published→ Observed→ Iterating
StageRequired ArtefactsAutomated ChecksHuman Gate
Requestedrequest.md, initial risk.mdSchema skeleton validationOptional
SpecDrafttool.yaml, capability.yaml, policy.yaml, draft skillsLint (YAML/JSON), policy completenessRequired for high-risk
SpecReviewFrozen spec + interface schemasInterface contract testsRequired
ScaffoldedRepo layout + stubs + zerohuman.yamlBuild passesOptional
ImplementedCode + tests + docsUnit tests; static analysis; secret scansOptional
AutoReviewedEval suite + golden outputsEval run; failure-path tests; security scanOptional
SandboxedSandbox run artefacts + tracePolicy enforcement + runtime checksRequired if outbound/PII
HumanGateApproval recordCryptographic signingRequired
PublishedRelease notes, SBOM/attestationsIndexer validationOptional
ObservedTelemetry + incident reportsAnomaly detectionOptional
IteratingNew PRs + updated versionsRegression evalsPer-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.

Capability request→ Spec compiler→ SDK codegen worker→ Repo scaffold + manifests→ Unit + contract tests→ Evals: trace + artefacts→ Security scan + policy gate→ Sandbox run→ Human approval + signing→ Publish release→ Indexer ingest + validate→ Runtime packages available

Runtime Binding Example

The runtime adapter translates tool.yaml into function tools, approvals, and policies.

runtime_binding.pypython
# 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. 1.Fetch zerohuman.yaml and referenced manifests (capabilities/tools/policies).
  2. 2.Validate schemas + signatures + licensing.
  3. 3.Run static checks (no forbidden outbound domains, no undeclared auth).
  4. 4.Run security scanning for tool/skill supply-chain risk.
  5. 5.Assign a trust tier (unverified → community-verified → publisher-verified).
  6. 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:

1.Load profile.yaml.
2.Load SOUL.md (identity + non-negotiables).
3.Load HEARTBEAT.md (operational routine).
4.Resolve capabilities (from capability.yaml) and verify versions/compatibility.
5.Load tool metadata and skill metadata only (names/descriptions).
6.Apply policy: compute effective allow/deny, approvals, network policy.
7.Fetch next task (ticket).
8.Execute using engine — use handoffs for delegation, tool search/namespaces for large surfaces, approvals for high-impact tools.
9.Emit artefacts and attach trace IDs.
10.Update task state, budgets, and learning signals.

Security & Data Sensitivity

Supply-chain security is no longer hypothetical. Skills registries are under active attack. ZeroHuman adopts a layered control model:

Publisher identity

Require signed releases for trusted tiers.

Permission manifests

tool.yaml and policy.yaml must declare outbound domains, data classification, and approval requirements.

Isolation

Run high-risk tools in sandbox/containers with network policies and allowlists.

Network egress controls

Deny-by-default policy. Allowlisted domains. Domain-secret patterns where supported.

Redaction

Log tool I/O in redacted form for PII. Keep full payloads in secure stores.

Trace retention

Tracing may be disabled under Zero Data Retention policies. Treat observability as a configurable constraint.

Authentication

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:

TrackPurposeOutputsChange Process
ProtocolFile formats + resolution ruleszerohuman.yaml schema, precedence rulesRFCs → spec releases
EcosystemListings, trust, moderationRegistry/indexer rules, trust tiers, auditsDiscussions → PRs
FrameworkReference implementationRuntime adapters, middleware, validation toolingVersioned 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.