# AgentPlat Context for AI Agents

## Public API Manifest

```json
{
  "schemaVersion": 1,
  "packages": [
    {"name":"@agentplat/collective-runtime","entrypoints":[".","./checkpoints","./collective-decision","./coordination-control","./mission-continuity","./mission-lifecycle","./team-formation","./team-execution","./sparse-peer"]},
    {"name":"@agentplat/collective-host","entrypoints":[".","./distributed-planning","./distributed-protocol","./autonomous-node"]},
    {"name":"@agentplat/collective-membership","entrypoints":["./agent-factory","./agent-lineage","./governed-agent-lifecycle"]},
    {"name":"@agentplat/collective-quorum","entrypoints":["./partial-view-agreement","./sparse-agreement","./sparse-agreement-runtime"]},
    {"name":"@agentplat/collective-sync","entrypoints":["."]},
    {"name":"@agentplat/mesh","entrypoints":[".","./coordination","./continuity","./durability","./overlay","./adaptive-overlay","./trust"]},
    {"name":"@agentplat/mesh-protocol","entrypoints":["."]},
    {"name":"@agentplat/mesh-crypto","entrypoints":["."]},
    {"name":"@agentplat/audit","entrypoints":[".","./collective-telemetry"]},
    {"name":"@agentplat/trust","entrypoints":["."]},
    {"name":"@agentplat/rooms","entrypoints":["."]},
    {"name":"@agentplat/rooms-mesh","entrypoints":["."]}
  ]
}

```

## OpenAPI Specification

```yaml
openapi: 3.0.0
info:
  title: AgentPlat deployment API template
  description: Reference template for an API exposed by an organization that deploys AgentPlat. AgentPlat does not operate a public API service.
  version: 1.0.0
servers:
  - url: https://your-agentplat.example.com
paths: {}

```

## Documentation: agent-mesh/failures.mdx

# Failures and partitions

During a partition, peers may have incomplete or conflicting views. Agent Mesh preserves scope and causal evidence so applications can pause, narrow eligibility or recover after connectivity returns.

Stale, equivocal or uncovered evidence is unresolved. Safe recovery requires reconciliation, revalidation and—where configured—quorum or independent witness certification.


## Documentation: agent-mesh/index.mdx

# Agent Mesh

Agent Mesh is the peer-to-peer coordination layer for distributed AgentPlat runtimes. It provides authenticated protocol messages, causal synchronization, governed membership and optional collective agreement without requiring a central scheduler for every decision.

Mesh capabilities are opt-in and policy-bound. A mesh message is not automatically an instruction, a lease or permission to perform an external action.

- [Protocol](/agent-mesh/protocol)
- [Causal Synchronization](/agent-mesh/synchronization)
- [Membership and Key Rotation](/agent-mesh/membership)
- [Sparse Overlays](/agent-mesh/sparse-overlays)
- [Failures and Partitions](/agent-mesh/failures)


## Documentation: agent-mesh/membership.mdx

# Membership and key rotation

Membership changes are represented by authenticated epochs. Enrollment, retirement, replacement and key rotation advance the governed membership state and invalidate stale authority where required.

Applications should persist membership heads and certificates when peer continuity matters. Never reuse an old peer key as evidence of a new lifecycle state.


## Documentation: agent-mesh/protocol.mdx

# Mesh protocol

Mesh protocol envelopes are bounded, versioned and authenticated. They carry the minimum coordination data required to validate scope, sender, predecessor, membership epoch and payload digest.

Implementations should reject malformed, oversized, stale, unsigned or out-of-scope messages before application handling. Compatibility is explicit; unknown fields or versions must not silently expand authority.


## Documentation: agent-mesh/sparse-overlays.mdx

# Sparse overlays

Sparse overlays derive bounded active and reserve peer views without allocating a complete global edge list. They support scale by limiting local coordination state while preserving policy-approved reachability and recovery paths.

Overlay adaptation must remain locally governed and independently witnessed. Remote evidence cannot replace the local quorum or policy required by the application.


## Documentation: agent-mesh/synchronization.mdx

# Causal synchronization

Peers exchange signed state and catch-up evidence through causal anti-entropy. Readiness gates prevent a peer from acting on a state that is missing required predecessors or membership context.

Synchronization establishes state visibility. It does not by itself certify a decision or authorize an effect.


## Documentation: agent-rooms/index.mdx

# Agent Rooms

An Agent Room is a tenant-scoped workspace where humans and agents collaborate toward a goal. It keeps messages, structured handoffs, runs, artifacts, approvals, policy decisions, memory provenance and audit events in one governed unit of work.

Rooms are the human-facing operational surface of AgentPlat. Collective Runtime and Agent Mesh provide distributed coordination underneath; a Room gives people a place to inspect context, review work, approve protected transitions and retain the resulting evidence.

> **The Agent Room design originated in the paper [Agent Rooms: A Conceptual Framework for Persistent Human-Governed Multi-Agent Collaboration](https://doi.org/10.5281/zenodo.20564834).** Read the [origin paper and citation](https://doc.agentplat.com/agent-rooms/origin-paper) to understand the framework behind this implementation.

## What a Room provides

- bounded context assembled from selected messages, artifacts and memory;
- human and agent participants with explicit roles;
- structured tasks and agent execution targets;
- append-only artifacts and audit events;
- approval and policy state;
- lifecycle transitions from active through paused, completed and archived;
- tenant-qualified persistence and transport boundaries.

Continue with [Room Lifecycle](/agent-rooms/lifecycle), [Rooms and Agent Mesh](/agent-rooms/mesh-bridge) or [Self-Hosting](/agent-rooms/self-hosting).


## Documentation: agent-rooms/lifecycle.mdx

# Room lifecycle

Rooms follow explicit lifecycle transitions:

```text
active → paused → active → completed → archived
```

Invalid transitions fail closed. Archived Rooms are read-only. Subrooms retain their parent relationship, and a parent cannot complete while a direct subroom remains active.

Tasks must resolve to an agent participant. Humans contribute messages, review artifacts and grant approvals, but are not silently selected as execution targets.

Task context is bounded and records provenance for the messages, artifacts and memory selected for a run. Artifact versions and audit events are append-only.


## Documentation: agent-rooms/mesh-bridge.mdx

# Rooms and Agent Mesh

`@agentplat/rooms-mesh` provides explicit projections between Room state and Mesh coordination data. It is a bridge, not a scheduler or trust service.

```ts
import {
  projectRoomToMeshObjective,
  projectRoomTaskToMeshWork,
} from '@agentplat/rooms-mesh';

const objective = projectRoomToMeshObjective({ room, policy });
const work = projectRoomTaskToMeshWork({ room, task, policy: workPolicy });
```

The projection is unsigned. Room roles, participant authority and metadata are never silently converted into Mesh admission, assignment or lease authority. Signing, publication, bidding, acceptance and execution remain application-owned steps.

Accepted Mesh decisions can be projected back into an ordinary Room message or draft artifact. Applying that result remains explicit, policy-bound and idempotent.


## Documentation: agent-rooms/origin-paper.mdx

# The paper behind Agent Rooms

Agent Rooms originated in the paper [**Agent Rooms: A Conceptual Framework for Persistent Human-Governed Multi-Agent Collaboration**](https://doi.org/10.5281/zenodo.20564834) by Douglas Rodriguez.

The paper defines an Agent Room as a persistent collaboration container that brings together human and AI participants, roles, goals, artifacts, memory, policies, communication protocols, audit events and governance boundaries. It argues that multi-agent collaboration should be treated as a governed socio-technical process—not merely as message exchange or task execution.

## Design contributions

The paper provides the conceptual foundation for:

- a persistent Room unit of collaboration;
- lifecycle and governance boundaries;
- structured handoffs and bounded agent mentions;
- artifact blackboards and persistent transcripts;
- context engineering and memory governance;
- recursive subrooms;
- quality gates and approval flows;
- audit events and observable evaluation hooks.

AgentPlat implements these ideas as open interfaces and adapters in `@agentplat/rooms`, `@agentplat/rooms-postgres`, `@agentplat/rooms-api` and `@agentplat/rooms-mesh`.

## Scope of the claim

The paper presents an implemented design reference and an evaluation protocol; it does not claim definitive empirical validation. AgentPlat documentation keeps that distinction explicit: the paper defines the architectural origin, while implementation and campaign artifacts document what has been built and measured.

## Cite the work

```bibtex
@misc{rodriguez2026agentrooms,
  title        = {Agent Rooms: A Conceptual Framework for Persistent Human-Governed Multi-Agent Collaboration},
  author       = {Rodriguez, Douglas},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.20564834},
  url          = {https://doi.org/10.5281/zenodo.20564834}
}
```

[Read the paper on Zenodo](https://zenodo.org/records/20564834).


## Documentation: agent-rooms/self-hosting.mdx

# Self-hosting Agent Rooms

The open-source repository includes the Room domain, API, PostgreSQL adapter, mock runtime and extension contracts.

```sh
cd examples/rooms-api
cp .env.example .env
docker compose up --build -d
curl --fail http://localhost:3000/health
bash scripts/demo.sh
```

The reference demo creates a Room, pauses and resumes it, adds human and agent participants, records a message, runs a structured task, produces a draft artifact, grants human approval and archives the Room.

For production, inject an authenticated tenant resolver, use `@agentplat/rooms-postgres`, configure encrypted storage and replace the mock runtime with a provider adapter. The trusted development tenant header is not an authentication mechanism for an untrusted network.


## Documentation: agents/chat-stream.mdx

# Streaming interfaces

AgentPlat does not provide a hosted chat or streaming endpoint. The adopting organization owns the application transport, user interface, session policy and credentials.

Use the public packages to integrate governed agent execution into that interface.


## Documentation: agents/cloning.mdx

# Agent cloning

Agent cloning is an application-level product decision. AgentPlat does not operate a shared cloning API or store customer agent definitions.

An adopting organization can implement cloning with its own persistence, identity and policy model while using AgentPlat for its coordination and control boundaries.


## Documentation: agents/discovery.mdx

# Provider discovery

AgentPlat does not operate a shared provider catalog, tenant service or API-key store. Each adopting organization selects model providers and manages credentials in its own infrastructure.

Configure provider adapters and secret handling at your application boundary. See the [integration guide](/getting-started/integration-guide).


## Documentation: agents/invocation.mdx

# Agent invocation

AgentPlat does not provide a hosted invocation endpoint. Adopting organizations define their own transport and authentication boundary, then compose AgentPlat packages into the resulting application.

Protected effects should remain subject to the deployment's policy, identity, authorization and evidence requirements.


## Documentation: agents/listing.mdx

# Listing agents

AgentPlat does not expose a global agent directory. Your application owns agent records, access controls and any API or UI used to list them.

The framework can be embedded behind those interfaces to provide governed execution and coordination.


## Documentation: agents/management.mdx

# Agent management

Agent creation and management interfaces are defined by the adopting application. AgentPlat does not provide a hosted agent-management API or dashboard.

Use the public packages and extension contracts to implement the lifecycle, authorization and user experience appropriate for your deployment.


## Documentation: agents/roles.mdx

# Agent roles

Role definitions, role-management interfaces and authorization are application-defined. AgentPlat does not operate a shared roles API.

Configure roles and policies in the deployment that adopts AgentPlat.


## Documentation: api-reference/entity-requests.mdx

# Application-defined asynchronous work

AgentPlat does not operate a shared entity-creation API or enrichment service. If your product needs asynchronous scraping, enrichment or entity creation, define the endpoints, queues, providers, retention rules and authorization policy in your own application.

AgentPlat can be composed with that application layer for governed coordination, policy decisions and operational evidence. See the [integration guide](/getting-started/integration-guide) and [package catalog](/reference/packages).


## Documentation: architecture.mdx

# Architecture

AgentPlat's technical architecture is designed by [Grishen](https://grishen.com/). The architecture treats autonomous agents as an operational system: coordination is bounded, authority is explicit, failures are recoverable and consequential outcomes are evidenced.

## Architectural principles

- **Local coordination over unrestricted broadcast:** peers operate through bounded views and policy-approved state.
- **Recovery as a first-class concern:** assignments, teams, missions and peer state can pause, recover or replan after failure.
- **Authority separation:** planning, coordination, execution and external effects have distinct boundaries.
- **Protected effects:** leases, fencing, identity and policy are revalidated before consequential actions.
- **Evidence by construction:** decisions, membership changes, recoveries and outcomes retain causal context.
- **Provider-neutral composition:** model providers, transports, persistence and deployment environments remain replaceable adapters.

## Architecture layers

```text
Applications and missions
        ↓
Collective Runtime: planning · teams · execution · recovery
        ↓
Agent Mesh: peers · membership · causal sync · quorum · sparse views
        ↓
Safety and Evidence: policy · authority · fencing · audit · trust
        ↓
Adapters: models · tools · PostgreSQL · transport · deployment
```

This architecture defines the public contracts. A deployment still requires the adopting organization to configure its infrastructure, policies, credentials, model providers and operational controls.

## Related technical references

- [Core Concepts](/core-concepts)
- [Collective Runtime](/collective-runtime)
- [Agent Mesh](/agent-mesh)
- [Safety and Governance](/safety)
- [Evidence and Operations](/evidence)
- [Grishen](https://grishen.com/)


## Documentation: collective-runtime/continuity.mdx

# Execution continuity

Execution continuity preserves mission progress when ownership changes. Checkpoints bind work to a mission, assignment, membership epoch and fencing state so a replacement peer cannot resume from an ambiguous snapshot.

Continuity is not exactly-once execution of arbitrary external effects. Protected effects must be revalidated at the boundary and may require idempotency, approval or a new lease.


## Documentation: collective-runtime/index.mdx

# Collective Runtime

The Collective Runtime composes planning, membership, teams, execution, recovery and evidence into a governed local control loop.

```text
mission intent → plan → team formation → assignment → execution
       ↑                                               ↓
       └──────────── evidence-backed recovery ─────────┘
```

The runtime is deliberately modular. Applications can begin with an in-memory local runtime and add PostgreSQL durability, peer synchronization, quorum certification or domain adapters as their operating requirements grow.

- [Planning and Assignment](/collective-runtime/planning)
- [Recovery Semantics](/collective-runtime/recovery)
- [Execution Continuity](/collective-runtime/continuity)
- [Mission Lifecycle](/collective-runtime/mission-lifecycle)


## Documentation: collective-runtime/mission-lifecycle.mdx

# Mission lifecycle

Missions move through explicit states such as proposed, admitted, planned, executing, recovering, completed, cancelled and failed. Lifecycle transitions are policy-bound and produce evidence.

Control proposals remain advisory until the application installs the corresponding fenced transition. Replanning, reassignment and team adaptation must preserve causal continuity instead of overwriting the prior state.


## Documentation: collective-runtime/planning.mdx

# Planning and assignment

Planning produces immutable or versioned artifacts that describe intended work, constraints, roles and admissible transitions. Assignment binds a role to an eligible agent under the current membership epoch and policy.

Planning is not execution authority. A plan can be rejected, superseded or recovered without granting permission to perform a protected effect.

Assignments should be treated as expiring operational state. Reassignment requires fresh eligibility checks and preserves the causal relationship to the original failure or expiry.


## Documentation: collective-runtime/recovery.mdx

# Recovery semantics

Failure is an operating condition. The runtime can represent peer loss, communication loss, capability failure, stale state, expired leases and unsafe outcomes as explicit recovery signals.

Recovery follows a bounded loop:

1. Detect and authenticate the failure signal.
2. Stop or fence work whose authority is no longer valid.
3. Preserve the causal predecessor and evidence.
4. Re-evaluate eligible peers, roles and policy.
5. Reassign or replan within the configured recovery budget.
6. Resume only after readiness and authority checks pass.

Missing, conflicting or stale evidence remains unresolved. The safe default is pause or fail closed, not silent continuation.


## Documentation: core-concepts.mdx

# Core concepts

## Agents

An agent is a model-backed worker with identity, instructions, capabilities and an execution boundary.

## Peers and membership

A peer hosts one or more local runtimes. Membership is governed by authenticated epochs, leases and lifecycle transitions. A peer can be retired or replaced without silently reusing its authority.

## Coordination cells

A coordination cell is a bounded local view used to plan, assign and recover work. It gives a collective a scalable operating shape without requiring every agent to maintain a complete global graph.

## Missions and teams

A mission is durable operational intent. A team is a policy-approved set of roles and assignments formed to advance that mission. Team structure and membership are coordination data; they are not external-action permissions.

## Authority and policy

AgentPlat separates planning authority, coordination authority, execution authority and effect authority. Policies determine which transitions and actions are eligible.

## Evidence and trust

Evidence records what was observed, decided, recovered or executed. Trust profiles and eligibility filters can narrow an existing local decision; they do not create authority by themselves.


## Documentation: entities/company.mdx

# Application entities

AgentPlat does not maintain a shared company database, scraping service or public entity API. Entity schemas, data collection, provider integrations, retention and access controls belong to the application that adopts AgentPlat.

Use the framework's extension boundaries to connect your own entity model and tools while keeping coordination, policy and evidence responsibilities explicit.


## Documentation: evidence/audit.mdx

# Audit events

Audit events should identify the actor, scope, predecessor, policy context, decision, effect and outcome. Recursive redaction and evidence boundaries prevent sensitive payloads from being copied into coordination records.


## Documentation: evidence/index.mdx

# Evidence and Operations

Evidence makes collective behavior inspectable. AgentPlat can record decisions, membership changes, assignments, recovery signals, protected actions, telemetry and outcomes with causal references.

- [Audit Events](/evidence/audit)
- [Recovery Receipts](/evidence/recovery)
- [Replay and Checkpoints](/evidence/replay)


## Documentation: evidence/postgres.mdx

# PostgreSQL operations

PostgreSQL adapters provide durable repositories for collective runtime, membership, synchronization, audit and checkpoint state. Run migrations as a versioned deployment step and preserve the migration revision with campaign evidence.

Operational requirements include:

- a dedicated database and least-privilege application role;
- encrypted transport and storage;
- backups tested against the checkpoint and evidence retention policy;
- connection limits sized for peer and worker concurrency;
- migration locking and rollback procedures;
- observability for outbox lag, delivery receipts and recovery checkpoints.

Persistence improves continuity; it does not make an unsafe authority state valid. Revalidate membership, leases and fences after restore.


## Documentation: evidence/recovery.mdx

# Recovery receipts

Recovery receipts connect a detected failure to the response: fence, pause, eligibility evaluation, reassignment, replan, resume or terminal failure. They make recovery measurable and replayable.


## Documentation: evidence/replay.mdx

# Replay and checkpoints

Checkpoints preserve the causal state needed to explain a mission transition. Replay should reconstruct decisions and evidence, not blindly repeat external side effects.


## Documentation: examples/index.mdx

# Examples

These examples are derived from the public repository and are intended to be runnable starting points, not claims that every deployment has the same performance or failure tolerance.

- [Local Runtime](/examples/local-runtime)
- [Membership and Key Rotation](/examples/membership)
- [Causal Synchronization](/examples/synchronization)
- [Collective Quorum](/examples/quorum)

The complete source examples are in the repository's [`examples/`](https://github.com/Agentplat/agentplat/tree/main/examples) directory.


## Documentation: examples/local-runtime.mdx

# Local runtime

Use the framework runtime for a small, local experiment before adding a peer transport or database.

```js
import { DefaultAgentRuntime } from '@agentplat/runtime';

const runtime = new DefaultAgentRuntime();
const result = await runtime.run({
  input: 'Summarize the incident timeline',
  policy: { protectedActions: 'deny-by-default' }
});
console.log(result);
```

This path is ephemeral: it does not create a durable collective mission, peer membership or room audit record. Use it to validate adapters and application boundaries, then move to the collective runtime when recovery or continuity matters.

Source: [`examples/basic-runtime.mjs`](https://github.com/Agentplat/agentplat/blob/main/examples/basic-runtime.mjs).


## Documentation: examples/membership.mdx

# Membership and key rotation

The membership package models authenticated configuration epochs and joint-majority transitions.

```ts
import {
  CollectiveMembershipHostV1,
  InMemoryCollectiveMembershipRegistryV1,
  InMemoryCollectiveMembershipRepositoryV1,
} from '@agentplat/collective-membership';

const registry = await InMemoryCollectiveMembershipRegistryV1.create({
  configurations: [initialConfiguration]
});
const repository = new InMemoryCollectiveMembershipRepositoryV1();
await repository.initialize(initialConfiguration);
```

In production, replace the in-memory repository with `@agentplat/collective-membership-postgres`. The protocol fails closed on invalid signatures, stale configuration digests, expired envelopes and insufficient old or new majorities.

Source: [`packages/collective-membership/README.md`](https://github.com/Agentplat/agentplat/blob/main/packages/collective-membership/README.md).


## Documentation: examples/quorum.mdx

# Collective quorum

Quorum adapters certify a coordination decision under an authenticated membership view. Certification remains coordination authority; it is not an external-action grant.

Use the multiprocess quorum example to inspect signed promises, votes, certificates and the behavior of minority or stale membership views.

Source: [`examples/collective-quorum-multiprocess`](https://github.com/Agentplat/agentplat/tree/main/examples/collective-quorum-multiprocess).


## Documentation: examples/synchronization.mdx

# Causal synchronization

The multiprocess synchronization example demonstrates signed causal records, catch-up, a failed-closed partition, key rotation and restart recovery.

```text
append objective → append work → catch up peers
peer loss → frontier threshold unavailable
peer returns → catch up and restore readiness
key rotation → stale certificate rejected → revalidated catch-up
restart → durable frontier restored
```

Run it with the repository's PostgreSQL example configuration. The output includes whether the partition failed closed, the recovered sequence and whether restart restored readiness.

Source: [`examples/collective-sync-multiprocess`](https://github.com/Agentplat/agentplat/tree/main/examples/collective-sync-multiprocess).


## Documentation: getting-started/core-concepts.mdx

# Core Concepts

Understanding the fundamental building blocks of AgentPlat is crucial for effective use in your own deployment.

- **Organization**: A deployment-defined boundary for people, policies and resources. AgentPlat does not provide accounts or billing.
- **Workspace**: An application-defined environment such as development or production. Its isolation model is configured by the adopting organization.
- **Agents**: AI entities configured with instructions, tools and policies to perform work.
- **Tasks**: Application-defined units of work assigned to agents.
- **Knowledge Base**: Information sources made available to agents by the adopting application.


## Documentation: getting-started/first-collective.mdx

# Your first collective

A collective is a bounded group of agents that coordinates around a mission under an explicit policy. Start locally before introducing persistence or a peer network.

## 1. Define agents and a mission

```ts
const mission = {
  id: 'incident-review-001',
  objective: 'Assess an incident and prepare a response brief',
  policy: { protectedActions: 'approval-required' }
}
```

Create specialized agents for observation, analysis and review. Give each agent only the tools and authority required for its assignment.

## 2. Run with bounded coordination

The collective runtime assigns work through a local coordination view. Agents do not receive every message or gain authority merely by participating in a decision.

## 3. Inspect the result

Capture the mission outcome together with assignment, policy and recovery evidence. The evidence is part of the operational result, not an optional log line.

See [recovery semantics](/collective-runtime/recovery) and [evidence](/evidence) before connecting external side effects.


## Documentation: getting-started/integration-guide.mdx

# Integration guide

AgentPlat can be introduced incrementally. Keep the first deployment local and in-memory, then add persistence, peer transport and protected effects one boundary at a time.

## Recommended progression

1. Use `@agentplat/framework` for a local agent and explicit model adapter.
2. Add `@agentplat/collective-runtime` when work requires multiple roles or recovery.
3. Add `@agentplat/collective-host-postgres` or the relevant persistence adapter for durable state.
4. Add `@agentplat/collective-sync` and `@agentplat/mesh-protocol` for authenticated peer exchange.
5. Add protected actions only after policy, identity, lease and evidence checks are configured.

Do not begin by exposing every tool to every agent. Start with a narrow capability catalog and expand it only when the evidence and policy boundary are clear.

## Integration boundaries

The application owns model credentials, external side-effect idempotency and deployment secrets. AgentPlat owns coordination contracts, lifecycle state, policy decisions and evidence interfaces.


## Documentation: getting-started/integration.mdx

# Integration Methods

There are multiple ways to integrate AgentPlat into an application that you run and operate in your own infrastructure.

- **Application UI**: Build the user interface for your product or operations console and connect it to your AgentPlat deployment.
- **REST API**: Connect your applications programmatically to the AgentPlat services running in your infrastructure.
- **Authentication**: Configure authentication and authorization through your own identity provider and deployment boundary.

AgentPlat does not provide a hosted dashboard, hosted API, or managed runtime. The open-source software is intended to be deployed and operated by each adopting organization.

## Common Integration Pitfalls

When integrating with the API, be aware of these common issues to ensure smooth operation.

### 1. Agent Role Object Structure

When listing agents, the `role` field is returned as a JSON Object, NOT a string. Attempting to parse it as a string will cause deserialization errors in strongly-typed languages like Go, Java, or C#.

```json
// Correct Structure:
{
  "id": "agent_123",
  "role": {
    "id": "role_456",
    "name": "Copywriter"
  }
}
```

#### Go Example Fix:

```go
// WRONG:
type Agent struct {
    Role string `json:"role"`
}

// CORRECT:
type AgentRole struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}
type Agent struct {
    Role *AgentRole `json:"role"`
}
```


## Documentation: getting-started/introduction.mdx

# Introduction

AgentPlat is open-source software for building and operating agent systems in your own infrastructure.

It provides reusable coordination, policy and evidence components. You choose the application interface, deployment model, identity provider, model providers and operational infrastructure. This guide introduces the concepts and integration boundaries needed to incorporate those components into your product.


## Documentation: getting-started/support.mdx

# Help & Resources

If you need assistance, our support team is available to help you configure complex agent behaviors.

Check the "API Docs" link for detailed technical specifications if you are a developer integrating with our code.


## Documentation: index.mdx

# AgentPlat

AgentPlat is an open platform for building resilient collective operations with autonomous agents. It provides governed coordination, local recovery, protected actions and verifiable operational evidence across distributed agent systems.

> **Technical architecture designed by [Grishen](https://grishen.com/).** AgentPlat's architecture combines resilient collective coordination, governed autonomy, fault recovery and verifiable operational evidence. Deployment, infrastructure and operations may be provided by the adopting organization.

## Start here

- [Install AgentPlat and run your first agent](/getting-started/introduction)
- [Understand the core concepts](/core-concepts)
- [Read the architecture](/architecture)
- [Explore Agent Rooms](/agent-rooms)
- [Read the Agent Rooms paper](https://doi.org/10.5281/zenodo.20564834)
- [Run your first collective](/getting-started/first-collective)
- [Learn how recovery works](/collective-runtime/recovery)
- [Integrate Agent Mesh](/agent-mesh)
- [For AI coding agents](/ai/context.md)

## What AgentPlat provides

AgentPlat combines agent execution with the operational controls required for dependable multi-agent systems:

- **Bounded coordination:** peers coordinate through local, policy-approved views rather than an unbounded global broadcast.
- **Recoverable execution:** assignments, teams and missions can recover from peer, link and capability failures.
- **Controlled authority:** planning, coordination and external effects are separate authority boundaries.
- **Verifiable operations:** decisions, recoveries, protected actions and outcomes produce inspectable evidence.

AgentPlat does not make autonomy magically safe or guarantee a specific scale in every environment. Behavior depends on topology, policy, model adapters, persistence and deployment conditions. The documentation separates implemented capability, validation evidence and operational limitations.

## Explore the platform

- [Collective Runtime](/collective-runtime)
- [Agent Rooms](/agent-rooms)
- [Agent Mesh](/agent-mesh)
- [Safety and Governance](/safety)
- [Evidence and Operations](/evidence)
- [Scale and Evaluation](/scale)
- [Package and API Reference](/reference/packages)

For machine-readable context, see [`/llms.txt`](/llms.txt) and [`/ai/context.md`](/ai/context.md).


## Documentation: kb/files.mdx

# Agent files

File storage and file-management endpoints belong to the application that deploys AgentPlat. AgentPlat does not host files or provide a shared file API.

Implement the required storage, authorization and retention policies in your own infrastructure.


## Documentation: kb/overview.mdx

# Knowledge bases

AgentPlat does not provide a shared knowledge-base service, file store or upload API. The adopting organization selects storage, retrieval, retention and access controls for its own knowledge sources.

Connect those services through the framework's application and tool boundaries.


## Documentation: reference/api.mdx

# API reference

The public API is organized around stable package boundaries rather than one monolithic client. The machine-readable [public API manifest](/raw/public-api.json) records the supported package entry points used by this documentation.

## Core entry points

| Package | Representative entry points |
| --- | --- |
| `@agentplat/collective-runtime` | missions, checkpoints, collective decisions, continuity, teams and sparse peers |
| `@agentplat/collective-membership` | lineage, agent factory and governed lifecycle |
| `@agentplat/collective-quorum` | partial-view and sparse agreement |
| `@agentplat/collective-sync` | signed causal synchronization |
| `@agentplat/mesh` | coordination, continuity, durability, trust and sparse overlays |
| `@agentplat/audit` / `@agentplat/trust` | evidence, telemetry and eligibility |

API signatures must be read together with the relevant concept and safety pages. A callable function does not by itself grant authority: policy, identity, lease and evidence requirements determine whether an operation is admissible.


## Documentation: reference/configuration.mdx

# Configuration

Configuration controls topology, persistence, policy, cryptography, recovery budgets, evidence sinks and adapter behavior. Treat production configuration as versioned operational input and review changes before deployment.


## Documentation: reference/index.mdx

# Reference

The reference section connects conceptual documentation to public packages, APIs, schemas, CLI commands and compatibility policies.

- [Package Catalog](/reference/packages)
- [API Reference](/reference/api)
- [Configuration](/reference/configuration)


## Documentation: reference/packages.mdx

# Package catalog

The public packages are organized by responsibility:

| Area | Packages | Purpose |
| --- | --- | --- |
| Composition | `@agentplat/framework`, `@agentplat/runtime` | Local defaults and portable execution |
| Collective runtime | `@agentplat/collective-runtime`, `@agentplat/collective-host` | Missions, teams, planning, recovery and lifecycle |
| Membership | `@agentplat/collective-membership` | Enrollment, epochs, lineage and retirement |
| Agreement | `@agentplat/collective-quorum` | Signed quorum and optional Byzantine agreement |
| Synchronization | `@agentplat/collective-sync` | Causal anti-entropy and readiness gates |
| Mesh | `@agentplat/mesh`, `@agentplat/mesh-protocol`, `@agentplat/mesh-crypto` | Sparse views, bounded wire protocol and signing |
| Evidence | `@agentplat/audit`, `@agentplat/trust` | Audit, telemetry, evidence and eligibility |
| Human collaboration | `@agentplat/rooms`, `@agentplat/rooms-postgres`, `@agentplat/rooms-api`, `@agentplat/rooms-mesh` | Governed Rooms, persistence, API transport and Mesh projections |
| Persistence | `*-postgres` packages | Durable repositories and outboxes |
| Evaluation | `@agentplat/mesh-sim`, `@agentplat/mesh-sim-local` | Sharding, fault injection and campaign artifacts |

The package surface is versioned independently from each organization's AgentPlat deployment. Check the package README and release notes before depending on an experimental entry point.


## Documentation: safety/authority.mdx

# Authority boundaries

AgentPlat distinguishes coordination authority from execution and effect authority. Collective agreement can narrow or certify a coordination decision, but it does not automatically grant an external side effect.

Every protected action should bind identity, scope, current assignment, lease or fence, policy decision and evidence context.


## Documentation: safety/index.mdx

# Safety and Governance

AgentPlat treats safety as an operational boundary rather than a prompt instruction. Identity, policy, leases, fencing, approvals, cancellation and evidence work together to constrain consequential actions.

- [Authority Boundaries](/safety/authority)
- [Protected Actions](/safety/protected-actions)
- [Inference Control](/safety/inference-control)
- [Threat Model](/safety/threat-model)


## Documentation: safety/inference-control.mdx

# Inference control

Inference control provides provider-neutral intervention points for cancellation, deny-oriented policy, budget and model-specific controls. It constrains how a model invocation may proceed; it does not make an untrusted model authoritative.


## Documentation: safety/protected-actions.mdx

# Protected actions

Protected actions are effects that can change an external system or durable state. Before execution, the runtime should verify current authority, policy eligibility, assignment, expiry, idempotency and required approvals.

If any required check is unavailable or stale, the action pauses or fails closed.


## Documentation: safety/threat-model-links.mdx

# Threat model references

The repository maintains threat models for the major distributed boundaries. Read the model that matches the runtime profile before making a deployment claim:

- [Agent Mesh threat models](https://github.com/Agentplat/agentplat/tree/main/docs/security)
- [Agent Mesh protocol](https://github.com/Agentplat/agentplat/blob/main/docs/agent-mesh/protocol-v0.md)
- [Distributed control model](https://github.com/Agentplat/agentplat/blob/main/docs/collective-runtime/decentralized-control-model-v1.md)
- [Empirical validation protocol](https://github.com/Agentplat/agentplat/blob/main/docs/collective-runtime/empirical-validation-protocol-v1.md)

Threat models define assumptions and failure boundaries; they do not certify a deployment by themselves.


## Documentation: safety/threat-model.mdx

# Threat model

The public threat model covers stale peers, replay, equivocation, malformed messages, membership confusion, unauthorized effects, partitioned views and compromised adapters. Read the repository security models before selecting a deployment profile.


## Documentation: scale/evaluation.mdx

# Evaluation methodology

Register the scenario, topology, agent population, fault profile, seeds, software revision, model configuration and acceptance criteria before execution. Preserve raw artifacts and generated reports separately from interpretation.


## Documentation: scale/index.mdx

# Scale and Evaluation

AgentPlat includes sharded simulation, fault injection, multi-domain adapters and registered benchmark artifacts for evaluating distributed collective behavior.

Scale results depend on topology, persistence, model adapters, workload and fault profile. Documentation distinguishes capability from measured performance.

- [Sharded Simulation](/scale/simulation)
- [Evaluation Methodology](/scale/evaluation)
- [Results and Limitations](/scale/limitations)


## Documentation: scale/limitations.mdx

# Results and limitations

A passing implementation check does not establish production reliability or universal scale. Report observed conditions, confidence boundaries, unresolved cases and resource costs alongside every benchmark result.


## Documentation: scale/reproducibility.mdx

# Reproducibility checklist

Before running a scale or fault campaign, record:

- source revision and package lockfile;
- scenario and topology definition;
- population, roles and adapter versions;
- random seeds and deterministic settings;
- fault schedule and recovery budgets;
- database and host configuration;
- acceptance criteria and comparison baseline.

Keep registrations, raw shard artifacts, evaluator checkpoints and the final interpretation separate. A summary without its raw evidence is not a reproducible result.


## Documentation: scale/simulation.mdx

# Sharded simulation

Sharded simulation partitions an evaluation into bounded workers with evaluator-owned checkpoints, cross-shard delivery and controlled fault injection. Campaign artifacts should be immutable and independently attributable.


## Documentation: tasks/execution.mdx

# Task execution

Task transport, queues, execution endpoints and operator interfaces are application concerns. AgentPlat does not provide a shared dashboard, queue, API endpoint or API-key service.

An adopting organization may expose its own task API and choose polling, events, streams or another delivery model. That deployment remains responsible for authentication, authorization, scheduling, storage and task results. AgentPlat packages can provide coordination, recovery, policy and evidence boundaries inside that architecture.


## Documentation: tenants/subtenants.mdx

# Deployment-defined tenancy

AgentPlat does not operate a tenant service or issue tenant API keys. The adopting organization defines its own tenant model, identity integration and authorization boundary.

Public package APIs can be composed with that boundary, but no shared AgentPlat tenant endpoint is required or provided.