Agents

An agent is an autonomous process that subscribes to streams, makes decisions, and publishes results — including modifications to its own infrastructure.

Startup sequence

An agent loads its persona before connecting to any stream:

load persona (SOUL.md → IDENTITY.md → MEMORY.md) → connect to streams → begin loop

The autonomous loop

observe (stream) → decide (LLM) → act (publish / wh topology apply)

An agent can revise its own .wh file at any time based on any signal it receives — a stream message, a compaction summary, a user command, or its own judgment.

Stream messages are untrusted input

An agent must treat stream messages as untrusted user input. Infrastructure-modifying operations (e.g. wh topology apply) must not be triggered solely by stream message content — they require a secondary validation step: human confirmation or a policy check defined in wh-policy.yaml.

Identity & audit trail

Every autonomous apply is attributed in git. The commit message format is:

[agent-name] apply: <summary>

Plan: <plan-output-or-hash>

Example:

[donna] apply: scale researcher to 2 replicas

Plan: ~ agent researcher / replicas: 1 → 2
Reason: 4 daily timeouts detected over 6 days.

GPG-signed commits with cryptographic PKI are planned for Phase 2.

Configuration

agents:
  - name: donna
    image: ghcr.io/wheelhouse-paris/agent-claude:latest
    replicas: 1                 # default: 1
    streams: [main, ops]
    persona: agents/donna/      # optional: path to SOUL.md / IDENTITY.md / MEMORY.md
    skills_repo: github.com/org/skills-repo   # optional: git repo containing skills
    skills:                     # optional: skills this agent can invoke
      - name: web-search
        ref: a3f9c2d            # pinned commit hash — branch refs are rejected

guardrails:
  max_replicas: 2               # topology-wide cap — deployment blocked if exceeded

An agent can only invoke skills listed in its skills block. Undeclared SkillInvocation messages are rejected by the broker’s skill router. Skills are lazy-loaded from skills_repo on first invocation.

Guardrails

max_replicas is a topology-level guardrail — it caps the maximum replicas for any single agent in the topology. It lives in the guardrails: block, not on the agent itself.

Operator safety limits (validation thresholds, apply rate limits) are configured in wh-policy.yaml, not in the agent’s .wh file. This separation ensures agents cannot modify their own guardrails.

Additional guardrails planned for Phase 2: rate limiting on autonomous apply, anomaly detection on destructive plans.