# s-k-agrawal/apra-agent-kit architecture

> Architecture diagram of the GitHub repository s-k-agrawal/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/s-k-agrawal/apra-agent-kit
- Repository: https://github.com/s-k-agrawal/apra-agent-kit

## Overview

Apra Agent Kit is a modular toolkit for running autonomous agents on Apra Fleet. The main path is a user request entering through chat, HTTP, or MCP, being routed as a task, and executed by the configured run loop with tools and Fleet workers. Separate capabilities add queued jobs, scheduled workflows, notifications, and optional memory. The graph preserves these documented branches and the central pool, adapter, and task layers; unsampled implementation links are omitted or marked unverified rather than inferred.

Main entry points: [`host/index.mjs`](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/index.mjs) (Host lifecycle), [`pool/worker-dispatcher.mjs`](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/pool/worker-dispatcher.mjs) (Worker dispatcher), [`mcp/server.mjs`](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/mcp/server.mjs) (MCP server), [`host/tasks.mjs`](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/tasks.mjs) (Task execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces"]
  node_host["Host lifecycle<br/>[index.mjs]"]
  node_http_routes["HTTP routes<br/>[routes.mjs]"]
  node_chat["Chat UI<br/>[app.mjs]"]
  node_comm_router["Comm routing<br/>[router.mjs]"]
  node_azure_adapter["Azure adapter<br/>[http.mjs]"]
  node_mcp_server["MCP server<br/>[server.mjs]"]
  node_mcp_registry["MCP tools<br/>[registry.mjs]"]
end

subgraph group_execution["Agent execution"]
  node_tasks["Task execution<br/>[tasks.mjs]"]
  node_run_loop["Run loop<br/>[run-loop.mjs]"]
  node_strategies["Run strategies"]
  node_prompts["Prompt stages"]
  node_tool_execution["Tool execution<br/>[executor.mjs]"]
  node_guardrails["Guardrails<br/>[guardrails.mjs]"]
  node_budgets["Run budgets<br/>[budgets.mjs]"]
  node_domain_tools["Agent tools"]
end

subgraph group_fleet["Fleet workers"]
  node_pool["Worker dispatcher"]
  node_worker_pool["Worker pool<br/>[worker-pool.mjs]"]
  node_member_manager["Member lifecycle<br/>[member-manager.mjs]"]
  node_pooled_api["Pooled Fleet API"]
  node_fleet_transport["Fleet transport<br/>[stdio-fleet.mjs]"]
end

subgraph group_capabilities["Host capabilities"]
  node_jobs["Jobs backend<br/>[interface.mjs]"]
  node_scheduler["Workflow scheduler<br/>[interface.mjs]"]
  node_notifications["Notifications<br/>[index.mjs]"]
  node_cli_workflows["Standalone workflows<br/>[standalone.mjs]"]
end

subgraph group_state["State and storage"]
  node_memory["Agent memory<br/>[index.mjs]"]
  node_memory_stores[("Memory stores<br/>[interface.mjs]")]
  node_job_stores[("Job stores<br/>[interface.mjs]")]
end

node_user(("Agent user"))

node_user -->|"sends request"| node_chat
node_chat -.->|"uses host routes"| node_http_routes
node_user -->|"invokes tools"| node_mcp_server
node_host -->|"builds routes"| node_http_routes
node_host -->|"creates dispatcher"| node_pool
node_host -->|"executes tasks"| node_tasks
node_host -->|"creates backend"| node_jobs
node_host -->|"initializes memory"| node_memory
node_host -->|"configures schedules"| node_scheduler
node_http_routes -->|"runs or submits"| node_tasks
node_http_routes -->|"reads and cancels"| node_jobs
node_comm_router -.->|"dispatches routes"| node_http_routes
node_azure_adapter -->|"uses routing"| node_comm_router
node_mcp_server -->|"registers tools"| node_mcp_registry
node_mcp_server -->|"creates leased API"| node_pooled_api
node_mcp_server -.->|"dispatches workers"| node_pool
node_tasks -->|"uses Fleet API"| node_pool
node_tasks -->|"runs task loop"| node_run_loop
node_tasks -->|"applies limits"| node_budgets
node_run_loop -.->|"selects strategy"| node_strategies
node_strategies -.->|"uses prompt stages"| node_prompts
node_tasks -.->|"checks tool policy"| node_guardrails
node_mcp_server -->|"guards execution"| node_tool_execution
node_tool_execution -.->|"executes registered tools"| node_domain_tools
node_pool -.->|"dispatches leases"| node_worker_pool
node_pool -->|"provisions roster"| node_member_manager
node_pool -->|"exposes leased API"| node_pooled_api
node_cli_workflows -->|"spawns Fleet"| node_fleet_transport
node_cli_workflows -->|"creates dispatcher"| node_pool
node_cli_workflows -->|"provides leased API"| node_pooled_api
node_jobs -.->|"persists job state"| node_job_stores
node_scheduler -.->|"queues scheduled work"| node_jobs
node_jobs -->|"emits job updates"| node_notifications
node_memory -->|"uses configured stores"| node_memory_stores
node_host -.->|"starts MCP service"| node_mcp_server
node_host -->|"starts Azure adapter"| node_azure_adapter

click node_host "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/index.mjs"
click node_http_routes "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/routes.mjs"
click node_chat "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/chat/app.mjs"
click node_comm_router "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/comm/router.mjs"
click node_azure_adapter "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/comm/azure-functions/http.mjs"
click node_mcp_server "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/mcp/server.mjs"
click node_mcp_registry "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/mcp/registry.mjs"
click node_tasks "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/tasks.mjs"
click node_run_loop "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/run-loop.mjs"
click node_strategies "https://github.com/s-k-agrawal/apra-agent-kit/tree/main/host/strategies"
click node_prompts "https://github.com/s-k-agrawal/apra-agent-kit/tree/main/host/prompts"
click node_tool_execution "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/tools/executor.mjs"
click node_guardrails "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/guardrails.mjs"
click node_budgets "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/budgets.mjs"
click node_pool "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/pool/worker-dispatcher.mjs"
click node_worker_pool "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/pool/worker-pool.mjs"
click node_member_manager "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/pool/member-manager.mjs"
click node_pooled_api "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/pool/pooled-fleet-api.mjs"
click node_jobs "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/jobs/interface.mjs"
click node_scheduler "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/scheduler/interface.mjs"
click node_notifications "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/notify/index.mjs"
click node_memory "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/memory/index.mjs"
click node_memory_stores "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/memory/store/interface.mjs"
click node_job_stores "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/jobs/store/interface.mjs"
click node_cli_workflows "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/workflows/standalone.mjs"
click node_fleet_transport "https://github.com/s-k-agrawal/apra-agent-kit/blob/main/transport/stdio-fleet.mjs"
click node_domain_tools "https://github.com/s-k-agrawal/apra-agent-kit/tree/main/tools"

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_host,node_http_routes,node_chat,node_comm_router,node_azure_adapter,node_mcp_server,node_mcp_registry,node_user toneBlue
class node_tasks,node_run_loop,node_strategies,node_prompts,node_tool_execution,node_guardrails,node_budgets,node_domain_tools toneAmber
class node_pool,node_worker_pool,node_member_manager,node_pooled_api,node_fleet_transport toneMint
class node_jobs,node_scheduler,node_notifications,node_cli_workflows toneRose
class node_memory,node_memory_stores,node_job_stores toneIndigo
```

## Components

### Interfaces

- [Host lifecycle](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/index.mjs): `host/index.mjs`
- [HTTP routes](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/routes.mjs): `host/routes.mjs`
- [Chat UI](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/chat/app.mjs): `host/chat/app.mjs`
- [Comm routing](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/comm/router.mjs): `comm/router.mjs`
- [Azure adapter](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/comm/azure-functions/http.mjs): `comm/azure-functions/http.mjs`
- [MCP server](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/mcp/server.mjs): `mcp/server.mjs`
- [MCP tools](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/mcp/registry.mjs): `mcp/registry.mjs`

### Agent execution

- [Task execution](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/tasks.mjs): `host/tasks.mjs`
- [Run loop](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/run-loop.mjs): `host/run-loop.mjs`
- [Run strategies](https://github.com/s-k-agrawal/apra-agent-kit/tree/main/host/strategies): `host/strategies`
- [Prompt stages](https://github.com/s-k-agrawal/apra-agent-kit/tree/main/host/prompts): `host/prompts`
- [Tool execution](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/tools/executor.mjs): `host/tools/executor.mjs`
- [Guardrails](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/guardrails.mjs): `host/guardrails.mjs`
- [Run budgets](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/budgets.mjs): `host/budgets.mjs`
- [Agent tools](https://github.com/s-k-agrawal/apra-agent-kit/tree/main/tools): `tools`

### Fleet workers

- [Worker dispatcher](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/pool/worker-dispatcher.mjs): `pool/worker-dispatcher.mjs`
- [Worker pool](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/pool/worker-pool.mjs): `pool/worker-pool.mjs`
- [Member lifecycle](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/pool/member-manager.mjs): `pool/member-manager.mjs`
- [Pooled Fleet API](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/pool/pooled-fleet-api.mjs): `pool/pooled-fleet-api.mjs`
- [Fleet transport](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/transport/stdio-fleet.mjs): `transport/stdio-fleet.mjs`

### Host capabilities

- [Jobs backend](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/jobs/interface.mjs): `host/jobs/interface.mjs`
- [Workflow scheduler](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/scheduler/interface.mjs): `host/scheduler/interface.mjs`
- [Notifications](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/notify/index.mjs): `host/notify/index.mjs`
- [Standalone workflows](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/workflows/standalone.mjs): `workflows/standalone.mjs`

### State and storage

- [Agent memory](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/memory/index.mjs): `host/memory/index.mjs`
- [Memory stores](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/memory/store/interface.mjs): `host/memory/store/interface.mjs`
- [Job stores](https://github.com/s-k-agrawal/apra-agent-kit/blob/main/host/jobs/store/interface.mjs): `host/jobs/store/interface.mjs`

### Other components

- **Agent user**

## Connections

- Agent user → Chat UI: sends request
- Chat UI → HTTP routes: uses host routes
- Agent user → MCP server: invokes tools
- Host lifecycle → HTTP routes: builds routes (evidence: `host/index.mjs`)
- Host lifecycle → Worker dispatcher: creates dispatcher (evidence: `host/index.mjs`)
- Host lifecycle → Task execution: executes tasks (evidence: `host/index.mjs`)
- Host lifecycle → Jobs backend: creates backend (evidence: `host/index.mjs`)
- Host lifecycle → Agent memory: initializes memory (evidence: `host/index.mjs`)
- Host lifecycle → Workflow scheduler: configures schedules (evidence: `host/index.mjs`)
- HTTP routes → Task execution: runs or submits (evidence: `host/routes.mjs`)
- HTTP routes → Jobs backend: reads and cancels (evidence: `host/routes.mjs`)
- Comm routing → HTTP routes: dispatches routes
- Azure adapter → Comm routing: uses routing (evidence: `comm/azure-functions/http.mjs`)
- MCP server → MCP tools: registers tools (evidence: `mcp/server.mjs`)
- MCP server → Pooled Fleet API: creates leased API (evidence: `mcp/server.mjs`)
- MCP server → Worker dispatcher: dispatches workers
- Task execution → Worker dispatcher: uses Fleet API (evidence: `host/tasks.mjs`)
- Task execution → Run loop: runs task loop (evidence: `host/tasks.mjs`)
- Task execution → Run budgets: applies limits (evidence: `host/tasks.mjs`)
- Run loop → Run strategies: selects strategy
- Run strategies → Prompt stages: uses prompt stages
- Task execution → Guardrails: checks tool policy
- MCP server → Tool execution: guards execution (evidence: `mcp/server.mjs`)
- Tool execution → Agent tools: executes registered tools
- Worker dispatcher → Worker pool: dispatches leases
- Worker dispatcher → Member lifecycle: provisions roster (evidence: `pool/index.mjs`)
- Worker dispatcher → Pooled Fleet API: exposes leased API (evidence: `pool/pooled-fleet-api.mjs`)
- Standalone workflows → Fleet transport: spawns Fleet (evidence: `workflows/standalone.mjs`)
- Standalone workflows → Worker dispatcher: creates dispatcher (evidence: `workflows/standalone.mjs`)
- Standalone workflows → Pooled Fleet API: provides leased API (evidence: `workflows/standalone.mjs`)
- Jobs backend → Job stores: persists job state
- Workflow scheduler → Jobs backend: queues scheduled work
- Jobs backend → Notifications: emits job updates
- Agent memory → Memory stores: uses configured stores (evidence: `host/memory/index.mjs`)
- Host lifecycle → MCP server: starts MCP service (evidence: `host/index.mjs`)
- Host lifecycle → Azure adapter: starts Azure adapter (evidence: `comm/azure-functions/main.mjs`)
