Skip to main content
Esprit CLI is a Python-based autonomous security testing framework that uses AI agents to perform security assessments. The architecture is designed around isolated execution environments, multi-agent orchestration, and a modular tool system.

​
Core Components

​
Key Architectural Principles

​
1. Isolation-First Design

All security testing operations run in isolated sandboxes (Docker containers or cloud instances) to:
  • Prevent host system contamination
  • Enable safe execution of potentially dangerous operations
  • Provide consistent testing environments
  • Support parallel agent execution

​
2. Multi-Agent Orchestration

Esprit uses a hierarchical agent system:
  • Root Agent: Coordinates the overall scan, creates sub-agents for specialized tasks
  • Sub-Agents: Handle specific security testing tasks (e.g., vulnerability scanning, reconnaissance)
  • Agents communicate via message passing through a shared graph structure

​
3. Modular Tool System

Tools are registered dynamically and can execute either:
  • In Sandbox: For operations requiring isolation (terminal, browser, file editing)
  • Locally: For coordination tasks (agent management, reporting)
See Tools for the complete tool catalog.

​
System Flow

  1. User initiates scan with target (repository, URL, or local code)
  2. Runtime creates isolated sandbox environment
  3. EspritAgent initializes with scan configuration
  4. Local sources are copied to sandbox workspace
  5. Agent loop begins execution
  1. Agent requests next action from LLM
  2. LLM returns tool invocations based on system prompt and conversation history
  3. Tool executor validates and routes tool calls
  4. Tools execute in sandbox via HTTP API
  5. Results return to agent and append to conversation history
  6. Loop continues until max iterations or explicit finish
  1. Root agent analyzes scan requirements
  2. Creates specialized sub-agents for different tasks
  3. Sub-agents execute independently with their own sandbox access
  4. Agents exchange messages through shared graph
  5. Root agent aggregates results and generates final report

​
Runtime Modes

Esprit supports two execution runtimes:
RuntimeUse CaseRequirements
DockerLocal development and testingDocker Desktop installed
Esprit CloudProduction scans, team collaborationEsprit account and API token
See Docker Sandbox and Cloud Runtime for details.

​
Technology Stack

  • Language: Python 3.11+
  • LLM Integration: LiteLLM (supports multiple providers)
  • Containerization: Docker
  • HTTP Client: httpx (async)
  • Templating: Jinja2 (for agent prompts)
  • Browser Automation: Playwright
  • Web Interception: mitmproxy

​
File Structure

Key source code locations: 
esprit/
├── agents/              # Agent implementations
│   ├── base_agent.py    # Core agent loop logic
│   ├── EspritAgent/     # Main security testing agent
│   └── state.py         # Agent state management
├── runtime/             # Sandbox runtime implementations
│   ├── docker_runtime.py
│   ├── cloud_runtime.py
│   └── tool_server.py
├── tools/               # Tool implementations (12+ modules)
│   ├── browser/         # Browser automation
│   ├── terminal/        # Shell execution
│   ├── file_edit/       # File operations
│   ├── proxy/           # HTTP interception
│   └── ...
├── llm/                 # LLM provider integration
├── config/              # Configuration management
└── telemetry/           # Tracing and observability

​
Next Steps

Agent System

Learn about EspritAgent and multi-agent orchestration

Tools

Explore the complete tool catalog

Docker Sandbox

Understand local sandbox environments

Cloud Runtime

Deploy scans to Esprit Cloud

Build docs developers (and LLMs) love

Get started for freeTalk to us