Develop and extend
Concept Available

How Agent Barn Fits Together

Agent Barn separates product control, runtime execution, communication delivery, telemetry, and cost reporting into distinct boundaries. Understanding those boundaries makes it easier to operate the platform, diagnose failures, and identify the correct source before changing behavior.

For
New contributors
On this page
  1. Stored cost authority
  2. Web Chat ownership
  3. Four operational areas
  4. Three HTTP boundaries
  5. The Organization is the tenant boundary
  6. An Agent is headless
  7. Runtimes and Platforms are independent
  8. How a message reaches an Agent
  9. Conversations and Tool Calls have different writers
  10. Keep operational records separate
  11. Runtime startup
  12. Deployment boundaries
  13. Choose the right source
01

Stored cost authority

Cost reports query persisted model-call records populated by synchronization and recovery. Organization cost reporting requires Organization membership authority; Platform Administrator privilege does not bypass that requirement. Separate Platform cost routes provide explicitly authorized cross-Organization oversight without granting Organization content access.

  1. 01.1

    See /guides/observe-and-govern/costs for Organization and Platform reporting.

02

Web Chat ownership

The api/domains/web_chat/ domain owns dashboard chat requests, user-scoped thread history, and the authenticated SSE surface. It uses the Communications delivery pipeline and built-in Web Chat Connection. Reads require Agent activity permission; mutations require Agent update permission. This is distinct from external provider webhook authentication and runtime protocol credentials.

  1. 02.1

    See /guides/agents/web-chat for permissions and thread behavior.

03

Four operational areas

Agent Barn is organized around four operational areas.

  1. 03.1

    The API area is served through three separate HTTP applications. They use different authentication boundaries and should not be treated as one interchangeable API.

  2. 03.2

    API and services: Authentication, authorization, product workflows, persistence, runtime orchestration, Tool Call ingest, and communication delivery.

  3. 03.3

    Web app: Organization-scoped product workflows and Platform View.

  4. 03.4

    Agent runtimes: Hermes and OpenClaw executing rendered Agent configuration.

  5. 03.5

    Deployment: Databases, LiteLLM, API processes, UI, workers, monitoring, runtime images, and Kubernetes resources.

04

Three HTTP boundaries

The web app normally communicates with the Product API. It uses Organization-scoped routes for tenant-owned resources and Platform routes for Platform Administrator operations.

  1. 04.1

    Agent runtimes use separate per-start credentials for Ingest and the Communications protocol. Those credentials are not user-session tokens and do not grant access to Product API operations.

  2. 04.2

    Provider webhooks and supervised provider sessions belong to the Communications Gateway. They do not pass through normal user authentication.

  3. 04.3

    Product API: base path /api/v1: User-facing and administrative product operations.

  4. 04.4

    Ingest API: base path /ingest/v1: Authenticated runtime Tool Call telemetry.

  5. 04.5

    Communications Gateway: base path /communications/v1: Provider ingress, durable communication delivery, and the runtime-neutral communication protocol.

05

The Organization is the tenant boundary

An Organization owns its Members, Agents, Organization Templates, Organization Skills, Shared Credentials, activity, and other tenant-scoped resources.

  1. 05.1

    A user must have a persisted Membership to use Organization-scoped routes. Platform Administrator authority is separate and does not create an implicit Organization Membership.

  2. 05.2

    Agent Access adds a second authorization boundary inside an Organization. It determines which Members may view or manage one Agent and its subordinate resources, including Communication Connections, Conversations, Tool Calls, logs, costs, Secrets, Skills, and configuration.

06

An Agent is headless

An Agent combines versioned configuration with one Runtime. Each Agent has:

  1. 06.1

    A Platform is not an Agent field.

  2. 06.2

    An Agent may have zero or many Communication Connections, including multiple Connections to the same Platform. This allows one Agent to serve several Slack workspaces, Discord servers, Telegram bots, Microsoft Teams applications, or other supported endpoints without creating another Runtime.

  3. 06.3

    An Agent with no Communication Connections is still a valid headless Agent.

  4. 06.4

    One Organization

  5. 06.5

    One Runtime: Hermes or OpenClaw

  6. 06.6

    One immutable Platform Template, Organization Template, or Agent Template Override Version

  7. 06.7

    Explicit Skill assignments pinned to immutable Skill Versions

  8. 06.8

    Agent Secrets or Shared Credential references for tool Integrations

  9. 06.9

    Runtime resources managed through Kubernetes

  10. 06.10

    A LiteLLM key identity used for cost attribution

  11. 06.11

    Organization structure: an Organization owns Memberships, Templates and Template Versions, Skills and Skill Versions, Shared Credentials, Domain Events, and Agent.

  12. 06.12

    Agent structure: an Agent's pinned Template or Override Version, assigned Skill Versions, Agent Secrets and Integration references, zero or more Communication Connections, Runtime resources, Conversation Messages, Tool Calls, and LiteLLM cost identity.

07

Runtimes and Platforms are independent

Hermes and OpenClaw are Runtimes. They execute the Agent's rendered configuration.

  1. 07.1

    Slack, Microsoft Teams, Telegram, and Discord are Platforms. Support for each Platform is supplied by a shipped Platform Plugin.

  2. 07.2

    Both Runtimes consume the same versioned, runtime-neutral Communications protocol. Runtimes do not own provider sessions and do not receive Slack, Teams, Telegram, or Discord credentials.

  3. 07.3

    A Platform Plugin owns its Platform-specific behavior, including:

  4. 07.4

    Adding or changing a Communication Connection does not change the Agent's Runtime. Connection settings and credentials can be reconciled independently without rebuilding a running Agent.

  5. 07.5

    Typed Connection settings and credential schemas

  6. 07.6

    Credential validation and protected identity checks

  7. 07.7

    Provider ingress or supervised sessions

  8. 07.8

    Message normalization and admission policy

  9. 07.9

    Optional directory and display-name enrichment

  10. 07.10

    Outbound message delivery

  11. 07.11

    Provider-specific processing feedback

  12. 07.12

    Connection health reporting

08

How a message reaches an Agent

Inbound communication follows the Communications path.

  1. 08.1

    The Runtime processes the claimed delivery and submits its reply against the source Communication Delivery.

  2. 08.2

    The source Connection remains attached to the conversation and reply. This prevents messages from one Connection from being delivered through another Connection, even when both Connections use the same Platform or provider channel identifiers.

  3. 08.3

    Communication Connection health is separate from Agent lifecycle. A provider session may be degraded or disconnected while the Agent Runtime remains running.

  4. 08.4

    Inbound: Communication Platform

  5. 08.5

    Inbound: Shipped Platform Plugin

  6. 08.6

    Inbound: Communications Gateway

  7. 08.7

    Inbound: Durable inbound Communication Delivery

  8. 08.8

    Inbound: Canonical Conversation Message

  9. 08.9

    Inbound: Runtime-neutral Communications protocol

  10. 08.10

    Inbound: Hermes or OpenClaw

  11. 08.11

    Outbound: Hermes or OpenClaw

  12. 08.12

    Outbound: Communications Gateway

  13. 08.13

    Outbound: Durable outbound Communication Delivery

  14. 08.14

    Outbound: Source Communication Connection

  15. 08.15

    Outbound: Shipped Platform Plugin

  16. 08.16

    Outbound: Communication Platform

09

Conversations and Tool Calls have different writers

Conversation Messages and Tool Calls appear together in Agent Activity, but they do not share the same write path.

  1. 09.1

    The Communications Gateway persists canonical inbound and outbound Conversation Messages.

  2. 09.2

    The Ingest API persists Tool Call state and results reported by the Runtime. Ingest does not own provider message delivery or canonical Conversation persistence.

  3. 09.3

    Conversation locations include both the Communication Connection and provider channel identifier. Two Connections may therefore use the same provider channel identifier without merging their histories.

  4. 09.4

    Conversation Message: writer: Communications Gateway. Identity boundary: Communication Connection and provider message identity.

  5. 09.5

    Tool Call: writer: Ingest API. Identity boundary: Agent identity, per-start Ingest key, and runtime invocation identity.

10

Keep operational records separate

Agent Barn maintains several record types for different purposes.

  1. 10.1

    A Connection Journal entry is not a Domain Event or Event Delivery.

  2. 10.2

    Conversation Messages and Tool Calls do not determine costs. Cost reports query stored cost records imported from LiteLLM spend logs through background synchronization and attribution, with OpenRouter recovery for missing charges.

  3. 10.3

    Runtime logs are also separate from Conversation history. Logs may help explain a failure, but they are not durable business or communication records.

  4. 10.4

    Conversation Messages: Canonical human and Agent communication history.

  5. 10.5

    Tool Calls: Runtime tool execution state and results.

  6. 10.6

    Connection Journal: Content-free provider, policy, delivery, retry, and recovery diagnostics.

  7. 10.7

    Domain Events: Immutable typed business facts committed with product mutations.

  8. 10.8

    Event Deliveries: Delivery state for registered internal Domain Event handlers.

  9. 10.9

    Runtime logs and health: Recent execution and Kubernetes diagnosis.

  10. 10.10

    Cost records: Stored model usage and spend attributed by synchronization, including recovered OpenRouter charges.

11

Runtime startup

Starting an Agent is a Product API orchestration flow. Agent Barn:

  1. 11.1

    Communication Connection credentials are not included in the Runtime configuration. They remain encrypted inside the Communications boundary.

  2. 11.2

    A Runtime startup failure can move the Agent to ERROR. A provider or Connection failure updates Connection health instead and does not change the Agent lifecycle state.

  3. 11.3

    Loads the Agent and its pinned Template or Agent Template Override Version.

  4. 11.4

    Resolves the effective model.

  5. 11.5

    Loads the Agent's exact Skill Version assignments.

  6. 11.6

    Decrypts Agent Secrets used by tool Integrations.

  7. 11.7

    Renders the Runtime configuration.

  8. 11.8

    Generates fresh Ingest and Communications protocol credentials.

  9. 11.9

    Builds the Runtime's Kubernetes resources.

  10. 11.10

    Starts Hermes or OpenClaw.

12

Deployment boundaries

A complete Agent Barn deployment includes:

  1. 12.1

    Only the provider-webhook portion of the Communications service requires public ingress. Runtime protocol traffic and supervised provider-session management remain internal service concerns.

  2. 12.2

    Prometheus can scrape Product API, Ingest, Communications, LiteLLM, and Agent health metrics independently. A healthy Product API does not prove that Ingest, Communications, a provider Connection, or an Agent Runtime is healthy.

  3. 12.3

    Product API on port 8000

  4. 12.4

    Ingest API on port 8001

  5. 12.5

    Communications service on port 8002

  6. 12.6

    Web app, PostgreSQL, Redis, and LiteLLM

  7. 12.7

    Background worker and Domain Event reconciliation

  8. 12.8

    Monitoring services

  9. 12.9

    Hermes and OpenClaw Runtime images

  10. 12.10

    Kubernetes resources for running Agents

13

Choose the right source

Use the guide that owns the behavior you are investigating:

  1. 13.1

    Treat current feature and architecture documentation as the description of the running system. Changelogs describe delivered slices, while architecture decision records preserve the rationale behind decisions.

  2. 13.2

    Use Agent guides for lifecycle, configuration, Template pins, Skills, Integrations, and Agent Access.

  3. 13.3

    Use Platform guides for Communication Connection setup and Platform Plugin behavior.

  4. 13.4

    Use Activity guides for Conversation Messages and Tool Calls.

  5. 13.5

    Use Domain Event guides for internal business facts and Event Delivery.

  6. 13.6

    Use runtime and deployment guides for Hermes, OpenClaw, Kubernetes resources, services, and release topology.

  7. 13.7

    Use API and web app architecture guides when changing implementation boundaries.

  8. 13.8

    Use architecture decision records to understand why a consequential decision was made.

Documentation