Anthropic's Managed Agents engineering blog (2026-04-08) documents a design decision directly applicable to the homelab platform: stable interfaces over stable implementations. The five canonical calls they settled on are:
execute(name, input) → string — invoke a hand (sandbox or tool)
getEvents(sessionId, slice) — read positional slices of the session log
emitEvent(sessionId, event) — write a durable event during the agent loop
wake(sessionId) — reboot a crashed harness and resume from last event
provision({resources}) — spin up a new sandbox on demand
The principle: these names stay constant; implementations underneath change freely. This is the OS-abstraction pattern — read() is agnostic whether it's a 1970s disk pack or an SSD. Same idea here.
The homelab currently has:
hyperguild as the harness layer
agentsquad as the many-brains/many-hands orchestration layer
mcp-chassis implementing the credential proxy pattern (structurally equivalent to Managed Agents' vault-backed MCP proxy)
None of these have an explicit, written interface contract that defines what names are stable across harness evolution. Without it, any harness change risks requiring data migration or breaking agentsquad ↔ hyperguild coordination.
Why now
This is a prerequisite to the skills platform overhaul (#25) and any future multi-agent work — those assume a stable calling convention. Defining the contract costs little now; retrofitting it after three harness generations costs a lot.
The brain note knowledge/claude-managed-agents-architecture-notes-relevant-to-homelab-agent-platform.md has the full Managed Agents → homelab mapping table as a starting point.
Deliverable
An ADR written to docs/adr/NNNN-agent-platform-interface-contract.md in this repo (or mathias/infra, whichever is the canonical ADR home) covering:
The five interface names and their signatures, adapted for Go/homelab conventions
Which component owns each interface (e.g. session log → what backs it on koala; execute → routing pod? agentsquad?)
Credential isolation contract: what layer holds credentials, what layer never sees them
Session recovery contract: how a crashed harness resumes (wake equivalent)
Explicit statement of what is not stabilised (harness internals, model routing logic, sandbox implementation)
Relationship to open issues
Blocks or informs #25 (skills overhaul) — skill invocation is a "hand"; the interface name matters
Informs agentsquad design — flat peer-to-peer is the "many brains" pattern; the ADR should confirm agentsquad is the canonical many-hands layer
Does not block #35 (routing bootstrap) or #32 (brain injection) — those are independent
## Context
Anthropic's Managed Agents engineering blog (2026-04-08) documents a design decision directly applicable to the homelab platform: **stable interfaces over stable implementations**. The five canonical calls they settled on are:
- `execute(name, input) → string` — invoke a hand (sandbox or tool)
- `getEvents(sessionId, slice)` — read positional slices of the session log
- `emitEvent(sessionId, event)` — write a durable event during the agent loop
- `wake(sessionId)` — reboot a crashed harness and resume from last event
- `provision({resources})` — spin up a new sandbox on demand
The principle: these names stay constant; implementations underneath change freely. This is the OS-abstraction pattern — `read()` is agnostic whether it's a 1970s disk pack or an SSD. Same idea here.
The homelab currently has:
- **hyperguild** as the harness layer
- **agentsquad** as the many-brains/many-hands orchestration layer
- **mcp-chassis** implementing the credential proxy pattern (structurally equivalent to Managed Agents' vault-backed MCP proxy)
None of these have an explicit, written interface contract that defines what names are stable across harness evolution. Without it, any harness change risks requiring data migration or breaking agentsquad ↔ hyperguild coordination.
## Why now
This is a *prerequisite* to the skills platform overhaul (#25) and any future multi-agent work — those assume a stable calling convention. Defining the contract costs little now; retrofitting it after three harness generations costs a lot.
The brain note `knowledge/claude-managed-agents-architecture-notes-relevant-to-homelab-agent-platform.md` has the full Managed Agents → homelab mapping table as a starting point.
## Deliverable
An ADR written to `docs/adr/NNNN-agent-platform-interface-contract.md` in this repo (or `mathias/infra`, whichever is the canonical ADR home) covering:
- [ ] The five interface names and their signatures, adapted for Go/homelab conventions
- [ ] Which component owns each interface (e.g. session log → what backs it on koala; execute → routing pod? agentsquad?)
- [ ] Credential isolation contract: what layer holds credentials, what layer never sees them
- [ ] Session recovery contract: how a crashed harness resumes (`wake` equivalent)
- [ ] Explicit statement of what is **not** stabilised (harness internals, model routing logic, sandbox implementation)
## Relationship to open issues
- Blocks or informs #25 (skills overhaul) — skill invocation is a "hand"; the interface name matters
- Informs agentsquad design — flat peer-to-peer is the "many brains" pattern; the ADR should confirm agentsquad is the canonical many-hands layer
- Does **not** block #35 (routing bootstrap) or #32 (brain injection) — those are independent
## References
- Anthropic engineering blog: https://www.anthropic.com/engineering/managed-agents
- brain: `knowledge/claude-managed-agents-architecture-notes-relevant-to-homelab-agent-platform.md`
- `mathias/agentsquad` — homelab many-hands implementation
- `mathias/mcp-chassis` — credential proxy (Managed Agents vault pattern equivalent)
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Context
Anthropic's Managed Agents engineering blog (2026-04-08) documents a design decision directly applicable to the homelab platform: stable interfaces over stable implementations. The five canonical calls they settled on are:
execute(name, input) → string— invoke a hand (sandbox or tool)getEvents(sessionId, slice)— read positional slices of the session logemitEvent(sessionId, event)— write a durable event during the agent loopwake(sessionId)— reboot a crashed harness and resume from last eventprovision({resources})— spin up a new sandbox on demandThe principle: these names stay constant; implementations underneath change freely. This is the OS-abstraction pattern —
read()is agnostic whether it's a 1970s disk pack or an SSD. Same idea here.The homelab currently has:
None of these have an explicit, written interface contract that defines what names are stable across harness evolution. Without it, any harness change risks requiring data migration or breaking agentsquad ↔ hyperguild coordination.
Why now
This is a prerequisite to the skills platform overhaul (#25) and any future multi-agent work — those assume a stable calling convention. Defining the contract costs little now; retrofitting it after three harness generations costs a lot.
The brain note
knowledge/claude-managed-agents-architecture-notes-relevant-to-homelab-agent-platform.mdhas the full Managed Agents → homelab mapping table as a starting point.Deliverable
An ADR written to
docs/adr/NNNN-agent-platform-interface-contract.mdin this repo (ormathias/infra, whichever is the canonical ADR home) covering:wakeequivalent)Relationship to open issues
References
knowledge/claude-managed-agents-architecture-notes-relevant-to-homelab-agent-platform.mdmathias/agentsquad— homelab many-hands implementationmathias/mcp-chassis— credential proxy (Managed Agents vault pattern equivalent)