# aliasrobotics/cai architecture

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

- Interactive diagram: https://gitdiagram.com/aliasrobotics/cai
- Repository: https://github.com/aliasrobotics/cai

## Overview

1. **What this repo is**
CAI is a Python cybersecurity-agent framework, not a single application. The runtime lives under `src/cai`, while `examples/`, `benchmarks/`, and `docs/` are supporting layers for demonstrations, evaluation, and documentation. The repo is organized so that the reusable SDK sits below higher-level CLI/REPL UX and domain-specific security agents.

2. **Primary runtime boundary**
The main execution path is `cai` → `src/cai/cli.py` → REPL/UI commands under `src/cai/repl` → agent execution in `src/cai/sdk/agents`. The CLI is the human entrypoint, and the SDK is the reusable engine that can also be imported directly from Python code.

3. **Agent execution core**
`src/cai/sdk/agents` contains the core agent runtime: `Agent`, `Runner`, `RunContext`, lifecycle hooks, result types, streaming events, usage tracking, and model abstractions. The runtime is built around a ReAct-style loop: the model reasons, may invoke tools, and repeats until the turn finishes. A “turn” is one or more interactions; an interaction is one reasoning/action cycle.

4. **Model/provider layer**
Model access is abstracted behind provider classes for OpenAI-style chat/responses APIs, plus adapters and helpers for custom/OpenAI-compatible endpoints. The README shows support for OpenAI, Azure OpenAI, OpenRouter, Ollama, and custom base URLs via environment configuration. In architecture terms, CAI treats the model as an external service boundary, not an embedded component.

5. **Tooling layer**
Tools are the action surface of the agents. `src/cai/tools` groups them by security domain: reconnaissance, exploitation, privilege escalation, lateral movement, exfiltration, command-and-control, web, and miscellaneous utilities. These tools bridge LLM decisions to real host/network actions such as shell commands, scanning, file operations, web requests, code execution, and traffic capture.

6. **Handoffs and multi-agent coordination**
CAI supports delegation between agents via handoffs and patterns. The reusable handoff machinery lives in `src/cai/sdk/agents/handoffs.py` and related extensions, while higher-level security-specific patterns live in `src/cai/agents/patterns`. This is where hierarchical, chained, swarm-like, or recursive agent arrangements are defined, along with specialized prompt wiring.

7. **Domain-specific agent catalog**
`src/cai/agents` contains prebuilt cybersecurity agents such as red team, blue team, web pentester, bug bounty, DFIR, memory analysis, reverse engineering, Wi-Fi, Android, and SDR-focused agents. These are thin domain wrappers around the core SDK: they combine prompt templates, model settings, and tool sets for a specific security workflow.

8. **Prompt and policy assets**
Prompt templates live in `src/cai/prompts`, separated by agent role and system behavior. This is an important architecture boundary because prompt content is treated as first-class configuration rather than hardcoded logic. The repository also includes guardrail prompts and use-case prompts that shape behavior before tool execution.

9. **Safety and guardrails**
Guardrails are a dedicated layer, not an afterthought. Input/output validation is implemented in `src/cai/sdk/agents/guardrail.py` and related agent wrappers, with README-described protections against prompt injection and dangerous command execution. This layer sits between user/model/tooling and acts as a policy gate for both content and action.

10. **Observability, state, and replay**
Tracing is built around OpenTelemetry/Phoenix concepts in `src/cai/sdk/agents/tracing`, with additional internal support in `src/cai/internal/components`. Runs can be logged to JSONL, cost/usage can be tracked, and the REPL supports loading prior runs back into context. Architecturally, CAI is mostly stateless per model call, but session history and run logs create an observable interaction timeline.

11. **External protocol integration**
CAI supports MCP as a dynamic tool-ingestion boundary. `src/cai/sdk/agents/mcp` and the REPL MCP commands can load tools over SSE or stdio and attach them to agents at runtime. This is the main extension point for connecting external services like Burp or other local servers into the agent tool graph.

12. **Separate voice stack**
Voice is a distinct subsystem under `src/cai/sdk/agents/voice`, with STT/TTS models, pipeline configuration, workflow, and event types. It is not embedded in the text agent loop; instead, it provides an alternate input/output modality that can feed or receive from agent workflows.

13. **Examples, benchmarks, and test boundaries**
`examples/` demonstrates single-agent, multi-agent, MCP, tool, and voice usage; `benchmarks/` evaluates the framework on security datasets; `tests/` mirrors the package structure to verify runtime, CLI, MCP, tracing, tools, and voice behavior. These are support boundaries around the core runtime, useful for architecture diagrams as “consumers” and “validation” layers rather than runtime components.

14. **Packaging and deployment context**
The repo is a Python package with containerized development/runtime support via `.devcontainer/` and `dockerized/`. That matters because many tools assume a Linux/Kali-like environment, and the project explicitly supports reproducible container-based execution alongside local installs. The external boundary is therefore both the LLM API surface and the host OS/tooling environment.

Main entry points: [`src/cai/sdk/agents`](https://github.com/aliasrobotics/cai/tree/main/src/cai/sdk/agents) (Agent SDK), [`src/cai/agents`](https://github.com/aliasrobotics/cai/tree/main/src/cai/agents) (Security Agents), [`tests`](https://github.com/aliasrobotics/cai/tree/main/tests) (Tests), [`docs`](https://github.com/aliasrobotics/cai/tree/main/docs) (Docs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_repl["REPL<br/>ui/commands"]
  node_sdk_agents["Agent SDK<br/>runtime core"]
  node_sdk_handoffs["Handoffs<br/>coordination<br/>[handoffs.py]"]
  node_sdk_guardrails["Guardrails<br/>policy gate<br/>[guardrail.py]"]
end

subgraph group_domain["Domain Layer"]
  node_sdk_tools["Tools<br/>action surface"]
  node_domain_agents["Security Agents<br/>agent catalog"]
  node_agent_patterns["Patterns<br/>multi-agent recipes"]
  node_prompts["Prompts<br/>prompt assets"]
end

subgraph group_support["Support"]
  node_examples["Examples<br/>consumers"]
  node_benchmarks["Benchmarks<br/>evaluation"]
  node_tests["Tests<br/>validation"]
  node_docs["Docs<br/>documentation"]
end

subgraph group_integration["Integrations"]
  node_sdk_models["Model APIs<br/>provider adapters"]
  node_sdk_tracing["Tracing<br/>observability"]
  node_sdk_mcp["MCP<br/>tool protocol"]
  node_sdk_voice["Voice<br/>modal pipeline"]
  node_internal_components["Internal"]
end

node_cli -->|"launches"| node_repl
node_repl -->|"drives"| node_sdk_agents
node_sdk_agents -->|"calls"| node_sdk_models
node_sdk_agents -->|"invokes"| node_sdk_tools
node_sdk_agents -->|"delegates"| node_sdk_handoffs
node_sdk_agents -->|"checks"| node_sdk_guardrails
node_sdk_agents -->|"emits"| node_sdk_tracing
node_sdk_agents -->|"loads"| node_sdk_mcp
node_sdk_agents -->|"supports"| node_sdk_voice
node_domain_agents -->|"build on"| node_sdk_agents
node_domain_agents -->|"compose"| node_sdk_tools
node_domain_agents -->|"uses"| node_prompts
node_agent_patterns -->|"extends"| node_sdk_handoffs
node_agent_patterns -->|"orchestrates"| node_domain_agents
node_sdk_tools -->|"relies on"| node_internal_components
node_examples -->|"demonstrates"| node_sdk_agents
node_examples -->|"demonstrates"| node_sdk_mcp
node_examples -->|"demonstrates"| node_sdk_voice
node_benchmarks -->|"evaluates"| node_domain_agents
node_tests -->|"verifies"| node_sdk_agents
node_tests -->|"verifies"| node_sdk_models
node_tests -->|"verifies"| node_sdk_mcp
node_tests -->|"verifies"| node_sdk_tracing
node_tests -->|"verifies"| node_sdk_voice
node_docs -->|"documents"| node_cli
node_docs -->|"documents"| node_sdk_agents
node_docs -->|"documents"| node_domain_agents
node_docs -->|"documents"| node_sdk_mcp
node_docs -->|"documents"| node_sdk_voice

click node_cli "https://github.com/aliasrobotics/cai/blob/main/src/cai/cli.py"
click node_repl "https://github.com/aliasrobotics/cai/tree/main/src/cai/repl"
click node_sdk_agents "https://github.com/aliasrobotics/cai/tree/main/src/cai/sdk/agents"
click node_sdk_models "https://github.com/aliasrobotics/cai/tree/main/src/cai/sdk/agents/models"
click node_sdk_tools "https://github.com/aliasrobotics/cai/tree/main/src/cai/tools"
click node_sdk_handoffs "https://github.com/aliasrobotics/cai/blob/main/src/cai/sdk/agents/handoffs.py"
click node_sdk_guardrails "https://github.com/aliasrobotics/cai/blob/main/src/cai/sdk/agents/guardrail.py"
click node_sdk_tracing "https://github.com/aliasrobotics/cai/tree/main/src/cai/sdk/agents/tracing"
click node_sdk_mcp "https://github.com/aliasrobotics/cai/tree/main/src/cai/sdk/agents/mcp"
click node_sdk_voice "https://github.com/aliasrobotics/cai/tree/main/src/cai/sdk/agents/voice"
click node_domain_agents "https://github.com/aliasrobotics/cai/tree/main/src/cai/agents"
click node_agent_patterns "https://github.com/aliasrobotics/cai/tree/main/src/cai/agents/patterns"
click node_prompts "https://github.com/aliasrobotics/cai/tree/main/src/cai/prompts"
click node_internal_components "https://github.com/aliasrobotics/cai/tree/main/src/cai/internal/components"
click node_examples "https://github.com/aliasrobotics/cai/tree/main/examples"
click node_benchmarks "https://github.com/aliasrobotics/cai/tree/main/benchmarks"
click node_tests "https://github.com/aliasrobotics/cai/tree/main/tests"
click node_docs "https://github.com/aliasrobotics/cai/tree/main/docs"

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_cli,node_repl,node_sdk_agents,node_sdk_handoffs,node_sdk_guardrails toneBlue
class node_sdk_tools,node_domain_agents,node_agent_patterns,node_prompts toneAmber
class node_examples,node_benchmarks,node_tests,node_docs toneMint
class node_sdk_models,node_sdk_tracing,node_sdk_mcp,node_sdk_voice,node_internal_components toneRose
```

## Components

### Runtime

CLI, REPL, SDK, and execution subsystems

- [CLI](https://github.com/aliasrobotics/cai/blob/main/src/cai/cli.py): entrypoint · Main human entrypoint into the framework · `src/cai/cli.py`
- [REPL](https://github.com/aliasrobotics/cai/tree/main/src/cai/repl): ui/commands · Interactive command layer and terminal UI · `src/cai/repl`
- [Agent SDK](https://github.com/aliasrobotics/cai/tree/main/src/cai/sdk/agents): runtime core · Reusable agent engine with runs, turns, context, and lifecycle · `src/cai/sdk/agents`
- [Handoffs](https://github.com/aliasrobotics/cai/blob/main/src/cai/sdk/agents/handoffs.py): coordination · Delegation and multi-agent transfer machinery · `src/cai/sdk/agents/handoffs.py`
- [Guardrails](https://github.com/aliasrobotics/cai/blob/main/src/cai/sdk/agents/guardrail.py): policy gate · Input/output checks and dangerous-action controls · `src/cai/sdk/agents/guardrail.py`

### Domain Layer

Security-focused agent catalogs, prompts, and tools

- [Tools](https://github.com/aliasrobotics/cai/tree/main/src/cai/tools): action surface · Security and utility tools exposed to agents · `src/cai/tools`
- [Security Agents](https://github.com/aliasrobotics/cai/tree/main/src/cai/agents): agent catalog · Prebuilt red team, blue team, DFIR, web, Wi-Fi, Android, and related agents · `src/cai/agents`
- [Patterns](https://github.com/aliasrobotics/cai/tree/main/src/cai/agents/patterns): multi-agent recipes · Hierarchical, chained, parallel, and specialized agent wiring · `src/cai/agents/patterns`
- [Prompts](https://github.com/aliasrobotics/cai/tree/main/src/cai/prompts): prompt assets · System and role prompt templates treated as first-class configuration · `src/cai/prompts`

### Support

Docs, examples, benchmarks, and tests

- [Examples](https://github.com/aliasrobotics/cai/tree/main/examples): consumers · Usage demos for agents, tools, MCP, patterns, and voice · `examples`
- [Benchmarks](https://github.com/aliasrobotics/cai/tree/main/benchmarks): evaluation · Security benchmark runners and datasets · `benchmarks`
- [Tests](https://github.com/aliasrobotics/cai/tree/main/tests): validation · Package-mirrored tests for runtime, CLI, MCP, tracing, tools, and voice · `tests`
- [Docs](https://github.com/aliasrobotics/cai/tree/main/docs): documentation · Architecture, setup, API, CLI, tool, MCP, tracing, and voice documentation · `docs`

### Integrations

External protocol, model, tracing, and voice boundaries

- [Model APIs](https://github.com/aliasrobotics/cai/tree/main/src/cai/sdk/agents/models): provider adapters · OpenAI-style model interfaces and provider adapters · `src/cai/sdk/agents/models`
- [Tracing](https://github.com/aliasrobotics/cai/tree/main/src/cai/sdk/agents/tracing): observability · Run tracing, spans, processors, and trace logging · `src/cai/sdk/agents/tracing`
- [MCP](https://github.com/aliasrobotics/cai/tree/main/src/cai/sdk/agents/mcp): tool protocol · Dynamic tool ingestion via stdio or SSE servers · `src/cai/sdk/agents/mcp`
- [Voice](https://github.com/aliasrobotics/cai/tree/main/src/cai/sdk/agents/voice): modal pipeline · Speech-to-text and text-to-speech agent pipeline · `src/cai/sdk/agents/voice`
- [Internal](https://github.com/aliasrobotics/cai/tree/main/src/cai/internal/components): platform internals · Shared metrics, endpoints, network, and transfer helpers · `src/cai/internal/components`

## Connections

- CLI → REPL: launches · CLI starts the interactive terminal experience
- REPL → Agent SDK: drives · Commands ultimately execute agents and runs
- Agent SDK → Model APIs: calls · Agent runtime delegates inference to model providers
- Agent SDK → Tools: invokes · Agents select and execute tools during reasoning loops
- Agent SDK → Handoffs: delegates · Agents can hand off work to other agents
- Agent SDK → Guardrails: checks · Policy gates validate inputs and outputs around execution
- Agent SDK → Tracing: emits · Runs produce spans, events, and trace records
- Agent SDK → MCP: loads · External MCP servers can attach tools at runtime
- Agent SDK → Voice: supports · Voice workflow can feed into or out of agent execution
- Security Agents → Agent SDK: build on · Domain-specific agents wrap the reusable SDK runtime
- Security Agents → Tools: compose · Security agents bundle domain-appropriate tools
- Security Agents → Prompts: uses · Agent roles are shaped by prompt templates
- Patterns → Handoffs: extends · Pattern definitions build on reusable handoff machinery
- Patterns → Security Agents: orchestrates · Patterns combine specialized agents into workflows
- Tools → Internal: relies on · Tool execution shares lower-level internal helpers
- Examples → Agent SDK: demonstrates · Examples show agent runtime usage patterns
- Examples → MCP: demonstrates · Examples cover local and remote MCP tool loading
- Examples → Voice: demonstrates · Examples show both static and streamed voice flows
- Benchmarks → Security Agents: evaluates · Benchmarks exercise security workflows and model behavior
- Tests → Agent SDK: verifies · Tests cover core runtime behavior
- Tests → Model APIs: verifies · Tests validate provider adapters and conversions
- Tests → MCP: verifies · Tests validate MCP connection, caching, and server behavior
- Tests → Tracing: verifies · Tests cover tracing and telemetry paths
- Tests → Voice: verifies · Tests validate the voice pipeline and workflow
- Docs → CLI: documents · Docs explain commands and interactive usage
- Docs → Agent SDK: documents · Docs describe the core runtime and APIs
- Docs → Security Agents: documents · Docs describe agent catalog and workflows
- Docs → MCP: documents · Docs cover MCP setup and integration
- Docs → Voice: documents · Docs cover the voice subsystem
