Agents

Airbeeps includes an AI agent system that enables assistants to perform actions beyond simple text generation. Agents can call tools, search knowledge bases, interact with external services, and coordinate with other agents.

Architecture

The agent system supports two execution engines:

Engine	Description	Use case
ReAct	Reason → Act → Observe loop	Simple tool calling
LangGraph (default)	State-machine graph execution	Complex workflows, multi-step reasoning

Both engines support streaming, tool calling, and memory.

Built-in tools

Agents have access to built-in tools that are automatically registered:

Tool	Description
Knowledge base search	Search any connected KB for relevant documents
Web search	Search the web via configured providers
Code execution	Run Python code in a sandboxed environment
File operations	Read, write, and manage files

Additional tools can be registered through MCP or custom tool definitions.

MCP integration

Airbeeps supports the Model Context Protocol (MCP) for connecting to external tool servers:

# Enable MCP
AIRBEEPS_MCP_ENABLED=true
AIRBEEPS_MCP_SERVERS_CONFIG_PATH=/path/to/mcp_servers.json

Example mcp_servers.json:

{
  "servers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
    }
  ]
}

MCP servers are started as subprocesses and their tools become available to agents.

Multi-agent system

For complex tasks, Airbeeps supports multi-agent orchestration with specialist agents:

Specialist types

Type	Description
Researcher	Finds and synthesizes information
Coder	Generates and reviews code
Analyst	Analyzes data and draws conclusions
Writer	Creates structured content

Agent routing

The agent router automatically selects the best specialist for each user query based on the intent. Routing decisions consider:

• Query topic classification
• Available specialist capabilities
• Conversation context

Orchestration

The MultiAgentOrchestrator manages handoffs between specialists, combining their results into a coherent response.

Memory

Agents support opt-in conversation memory for maintaining context across sessions:

AIRBEEPS_AGENT_ENABLE_MEMORY=false  # Disabled by default

When enabled, memory is encrypted and scoped per user.

Resilience

The agent system includes reliability patterns for production use:

Retry with backoff

Tool executions automatically retry on transient failures with configurable backoff:

RetryConfig(
    max_retries=3,
    initial_delay=1.0,
    max_delay=60.0,
    backoff_factor=2.0,
)

Circuit breaker

Prevents cascading failures by temporarily disabling tools that are consistently failing:

CircuitBreakerConfig(
    failure_threshold=5,
    recovery_timeout=30.0,
    half_open_max_calls=3,
)

Health checks

Monitor agent and tool health via the /api/v1/health endpoints.

Configuration

Setting	Default	Description
AIRBEEPS_AGENT_MAX_ITERATIONS	10	Max tool-calling rounds
AIRBEEPS_AGENT_TIMEOUT_SECONDS	300	Total agent execution timeout
AIRBEEPS_AGENT_ENABLE_MEMORY	false	Enable cross-session memory
AIRBEEPS_MCP_ENABLED	false	Enable MCP integration
AIRBEEPS_MCP_SERVERS_CONFIG_PATH	""	Path to MCP servers config

Security

Agent tools operate under a security layer that includes:

• Sandbox execution — Code runs in isolated environments
• Permission levels — Tools have security levels (LOW, MEDIUM, HIGH)
• Content filtering — Input/output filtering for safety
• Audit tracing — All tool invocations are traced via OpenTelemetry