# apra-labs/apra-agent-kit architecture

> Architecture diagram of the GitHub repository apra-labs/apra-agent-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apra-labs/apra-agent-kit
- Repository: https://github.com/apra-labs/apra-agent-kit

## Overview

Apra Agent Kit is a modular toolkit for building autonomous agents on Apra Fleet. A user submits a task through the host’s chat or task interface, or invokes a tool through MCP; the host dispatches work to a leased Fleet worker and returns results. The kit also provides configurable run strategies, guardrails and budgets, asynchronous jobs, scheduling, memory, and standalone sample workflows. The README documents these capabilities, but several implementations were not sampled, so their internal links are left out or marked unverified.

Main entry points: [`host/index.mjs`](https://github.com/apra-labs/apra-agent-kit/blob/main/host/index.mjs) (Host Startup), [`pool/worker-dispatcher.mjs`](https://github.com/apra-labs/apra-agent-kit/blob/main/pool/worker-dispatcher.mjs) (Worker Dispatch), [`host/tasks.mjs`](https://github.com/apra-labs/apra-agent-kit/blob/main/host/tasks.mjs) (Task Execution), [`host/routes.mjs`](https://github.com/apra-labs/apra-agent-kit/blob/main/host/routes.mjs) (Host Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces"]
  node_comm["HTTP Adapters<br/>[router.mjs]"]
  node_host_routes["Host Routes<br/>[routes.mjs]"]
  node_chat["Chat UI<br/>[app.mjs]"]
  node_mcp["MCP Server<br/>[server.mjs]"]
end

subgraph group_runtime["Agent Runtime"]
  node_host["Host Startup<br/>[index.mjs]"]
  node_tasks["Task Execution<br/>[tasks.mjs]"]
  node_run_loop["Run Strategies<br/>[plan-execute.mjs]"]
  node_tools_registry["Tool Registry<br/>[registry.mjs]"]
end

subgraph group_workers["Fleet Workers"]
  node_pool["Worker Dispatch"]
  node_member_manager["Member Lifecycle<br/>[member-manager.mjs]"]
  node_stdio["Fleet Transport<br/>[stdio-fleet.mjs]"]
end

subgraph group_state["State And Operations"]
  node_jobs["Job Backends<br/>[in-process.mjs]"]
  node_scheduler["Workflow Scheduler<br/>[in-process.mjs]"]
  node_memory["Agent Memory<br/>[index.mjs]"]
  node_stores[("Memory Stores<br/>[sqlite.mjs]")]
  node_notifications["Notifications<br/>[index.mjs]"]
end

subgraph group_extensions["Workflows And Tools"]
  node_workflows["Sample Workflows<br/>[standalone.mjs]"]
  node_tool_examples["Example Tools"]
end

node_user(("Agent User"))
node_mcp_client(("MCP Client"))
node_fleet["Apra Fleet"]

node_user -->|"uses"| node_chat
node_user -->|"submits task"| node_host_routes
node_mcp_client -->|"invokes tools"| node_mcp
node_host -->|"creates adapter"| node_comm
node_host -->|"builds routes"| node_host_routes
node_comm -->|"routes requests"| node_host_routes
node_host_routes -->|"runs task"| node_tasks
node_host -->|"configures execution"| node_tasks
node_tasks -->|"runs strategy"| node_run_loop
node_tasks -->|"dispatches work"| node_pool
node_host -->|"creates dispatcher"| node_pool
node_pool -->|"provisions members"| node_member_manager
node_member_manager -->|"manages members"| node_fleet
node_pool -.->|"leases workers"| node_fleet
node_mcp -->|"leases worker"| node_pool
node_mcp -.->|"calls Fleet API"| node_fleet
node_host -->|"starts backend"| node_jobs
node_host -->|"starts scheduler"| node_scheduler
node_host -->|"initializes memory"| node_memory
node_memory -->|"configures stores"| node_stores
node_host -->|"configures notifications"| node_notifications
node_workflows -->|"spawns Fleet"| node_stdio
node_workflows -->|"creates dispatcher"| node_pool
node_workflows -.->|"runs workflow"| node_fleet
node_tool_examples -.->|"provides tool examples"| node_fleet

click node_host "https://github.com/apra-labs/apra-agent-kit/blob/main/host/index.mjs"
click node_comm "https://github.com/apra-labs/apra-agent-kit/blob/main/comm/router.mjs"
click node_host_routes "https://github.com/apra-labs/apra-agent-kit/blob/main/host/routes.mjs"
click node_chat "https://github.com/apra-labs/apra-agent-kit/blob/main/host/chat/app.mjs"
click node_mcp "https://github.com/apra-labs/apra-agent-kit/blob/main/mcp/server.mjs"
click node_tasks "https://github.com/apra-labs/apra-agent-kit/blob/main/host/tasks.mjs"
click node_run_loop "https://github.com/apra-labs/apra-agent-kit/blob/main/host/strategies/plan-execute.mjs"
click node_tools_registry "https://github.com/apra-labs/apra-agent-kit/blob/main/host/tools/registry.mjs"
click node_pool "https://github.com/apra-labs/apra-agent-kit/blob/main/pool/worker-dispatcher.mjs"
click node_member_manager "https://github.com/apra-labs/apra-agent-kit/blob/main/pool/member-manager.mjs"
click node_jobs "https://github.com/apra-labs/apra-agent-kit/blob/main/host/jobs/in-process.mjs"
click node_scheduler "https://github.com/apra-labs/apra-agent-kit/blob/main/host/scheduler/in-process.mjs"
click node_memory "https://github.com/apra-labs/apra-agent-kit/blob/main/host/memory/index.mjs"
click node_stores "https://github.com/apra-labs/apra-agent-kit/blob/main/host/memory/store/sqlite.mjs"
click node_notifications "https://github.com/apra-labs/apra-agent-kit/blob/main/host/notify/index.mjs"
click node_workflows "https://github.com/apra-labs/apra-agent-kit/blob/main/workflows/standalone.mjs"
click node_tool_examples "https://github.com/apra-labs/apra-agent-kit/tree/main/tools"
click node_stdio "https://github.com/apra-labs/apra-agent-kit/blob/main/transport/stdio-fleet.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_comm,node_host_routes,node_chat,node_mcp,node_user,node_mcp_client toneBlue
class node_host,node_tasks,node_run_loop,node_tools_registry toneAmber
class node_pool,node_member_manager,node_stdio toneMint
class node_jobs,node_scheduler,node_memory,node_stores,node_notifications toneRose
class node_workflows,node_tool_examples,node_fleet toneIndigo
```

## Components

### Interfaces

- [HTTP Adapters](https://github.com/apra-labs/apra-agent-kit/blob/main/comm/router.mjs): `comm/router.mjs`
- [Host Routes](https://github.com/apra-labs/apra-agent-kit/blob/main/host/routes.mjs): `host/routes.mjs`
- [Chat UI](https://github.com/apra-labs/apra-agent-kit/blob/main/host/chat/app.mjs): `host/chat/app.mjs`
- [MCP Server](https://github.com/apra-labs/apra-agent-kit/blob/main/mcp/server.mjs): `mcp/server.mjs`

### Agent Runtime

- [Host Startup](https://github.com/apra-labs/apra-agent-kit/blob/main/host/index.mjs): `host/index.mjs`
- [Task Execution](https://github.com/apra-labs/apra-agent-kit/blob/main/host/tasks.mjs): `host/tasks.mjs`
- [Run Strategies](https://github.com/apra-labs/apra-agent-kit/blob/main/host/strategies/plan-execute.mjs): `host/strategies/plan-execute.mjs`
- [Tool Registry](https://github.com/apra-labs/apra-agent-kit/blob/main/host/tools/registry.mjs): `host/tools/registry.mjs`

### Fleet Workers

- [Worker Dispatch](https://github.com/apra-labs/apra-agent-kit/blob/main/pool/worker-dispatcher.mjs): `pool/worker-dispatcher.mjs`
- [Member Lifecycle](https://github.com/apra-labs/apra-agent-kit/blob/main/pool/member-manager.mjs): `pool/member-manager.mjs`
- [Fleet Transport](https://github.com/apra-labs/apra-agent-kit/blob/main/transport/stdio-fleet.mjs): `transport/stdio-fleet.mjs`

### State And Operations

- [Job Backends](https://github.com/apra-labs/apra-agent-kit/blob/main/host/jobs/in-process.mjs): `host/jobs/in-process.mjs`
- [Workflow Scheduler](https://github.com/apra-labs/apra-agent-kit/blob/main/host/scheduler/in-process.mjs): `host/scheduler/in-process.mjs`
- [Agent Memory](https://github.com/apra-labs/apra-agent-kit/blob/main/host/memory/index.mjs): `host/memory/index.mjs`
- [Memory Stores](https://github.com/apra-labs/apra-agent-kit/blob/main/host/memory/store/sqlite.mjs): `host/memory/store/sqlite.mjs`
- [Notifications](https://github.com/apra-labs/apra-agent-kit/blob/main/host/notify/index.mjs): `host/notify/index.mjs`

### Workflows And Tools

- [Sample Workflows](https://github.com/apra-labs/apra-agent-kit/blob/main/workflows/standalone.mjs): `workflows/standalone.mjs`
- [Example Tools](https://github.com/apra-labs/apra-agent-kit/tree/main/tools): `tools`

### Other components

- **Agent User**
- **MCP Client**
- **Apra Fleet**

## Connections

- Agent User → Chat UI: uses
- Agent User → Host Routes: submits task
- MCP Client → MCP Server: invokes tools
- Host Startup → HTTP Adapters: creates adapter (evidence: `host/index.mjs`)
- Host Startup → Host Routes: builds routes (evidence: `host/index.mjs`)
- HTTP Adapters → Host Routes: routes requests
- Host Routes → Task Execution: runs task (evidence: `host/index.mjs`)
- Host Startup → Task Execution: configures execution (evidence: `host/index.mjs`)
- Task Execution → Run Strategies: runs strategy (evidence: `host/tasks.mjs`)
- Task Execution → Worker Dispatch: dispatches work (evidence: `host/tasks.mjs`)
- Host Startup → Worker Dispatch: creates dispatcher (evidence: `host/index.mjs`)
- Worker Dispatch → Member Lifecycle: provisions members (evidence: `pool/index.mjs`)
- Member Lifecycle → Apra Fleet: manages members (evidence: `pool/member-manager.mjs`)
- Worker Dispatch → Apra Fleet: leases workers
- MCP Server → Worker Dispatch: leases worker (evidence: `mcp/server.mjs`)
- MCP Server → Apra Fleet: calls Fleet API
- Host Startup → Job Backends: starts backend (evidence: `host/index.mjs`)
- Host Startup → Workflow Scheduler: starts scheduler (evidence: `host/index.mjs`)
- Host Startup → Agent Memory: initializes memory (evidence: `host/index.mjs`)
- Agent Memory → Memory Stores: configures stores (evidence: `host/memory/index.mjs`)
- Host Startup → Notifications: configures notifications (evidence: `host/index.mjs`)
- Sample Workflows → Fleet Transport: spawns Fleet (evidence: `workflows/standalone.mjs`)
- Sample Workflows → Worker Dispatch: creates dispatcher (evidence: `workflows/standalone.mjs`)
- Sample Workflows → Apra Fleet: runs workflow
- Example Tools → Apra Fleet: provides tool examples
