How aliasrobotics/cai works
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: sdk/agents Agent SDK · cai/agents Security Agents · tests Tests · docs Docs
Components 18
Runtime
CLI, REPL, SDK, and execution subsystems
- CLI · Main human entrypoint into the framework
src/cai/cli.py - REPL · Interactive command layer and terminal UI
src/cai/repl - Agent SDK · Reusable agent engine with runs, turns, context, and lifecycle
src/cai/sdk/agents - Handoffs · Delegation and multi-agent transfer machinery
src/cai/sdk/agents/handoffs.py - Guardrails · Input/output checks and dangerous-action controls
src/cai/sdk/agents/guardrail.py
Domain Layer
Security-focused agent catalogs, prompts, and tools
- Tools · Security and utility tools exposed to agents
src/cai/tools - Security Agents · Prebuilt red team, blue team, DFIR, web, Wi-Fi, Android, and related agents
src/cai/agents - Patterns · Hierarchical, chained, parallel, and specialized agent wiring
src/cai/agents/patterns - Prompts · System and role prompt templates treated as first-class configuration
src/cai/prompts
Support
Docs, examples, benchmarks, and tests
- Examples · Usage demos for agents, tools, MCP, patterns, and voice
examples - Benchmarks · Security benchmark runners and datasets
benchmarks - Tests · Package-mirrored tests for runtime, CLI, MCP, tracing, tools, and voice
tests - Docs · Architecture, setup, API, CLI, tool, MCP, tracing, and voice documentation
docs
Integrations
External protocol, model, tracing, and voice boundaries
- Model APIs · OpenAI-style model interfaces and provider adapters
src/cai/sdk/agents/models - Tracing · Run tracing, spans, processors, and trace logging
src/cai/sdk/agents/tracing - MCP · Dynamic tool ingestion via stdio or SSE servers
src/cai/sdk/agents/mcp - Voice · Speech-to-text and text-to-speech agent pipeline
src/cai/sdk/agents/voice - Internal · Shared metrics, endpoints, network, and transfer helpers
src/cai/internal/components
Connections 29
- 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