v0.2.7

[sami-marreed]

🎉 Major Features

🔐 Enterprise Policy System

CUGA now includes a comprehensive policy framework that enables enterprise-grade governance, safety, and compliance controls for AI agents. The policy system provides declarative, configurable policies that can guide, block, modify, or format agent behavior based on various triggers and conditions.

Policy Types

Policy Type	Purpose	Enterprise Value
Intent Guard	Block unauthorized actions	Data deletion prevention, access restrictions, compliance enforcement
Playbook	Standardize workflows	Onboarding, audit workflows, regulatory compliance
Tool Approval	Human oversight	Financial transactions, data modifications
Tool Guide	Domain knowledge	Compliance notes, domain context
Output Formatter	Format, redirect, govern outputs	Report generation, response routing, output masking

Key Capabilities

• Multiple Trigger Types: Support for keyword, natural language (semantic), app, state, tool, and always triggers
• Intelligent Matching: Uses embeddings and LLM-based conflict resolution for semantic policy matching
• Priority System: Handles conflicts when multiple policies match, with Intent Guards having highest priority
• Vector Storage: Uses Milvus for efficient policy retrieval and semantic search
• Human-in-the-Loop: Tool Approval policies create interrupts for human approval before sensitive operations
• Context-Aware: Uses PolicyContext to extract relevant information from agent state for policy evaluation

Integration Points

Policies are seamlessly integrated into the CugaLite graph execution flow:

1. prepare_tools_and_apps Node: Checks for Intent Guards, Playbooks, and Tool Guides before tool preparation
2. call_model Node: Checks for Tool Approval requirements after code generation
3. CugaLiteCallback Node: Applies Output Formatters to final responses

SDK Support

Policies can be configured programmatically via the Python SDK:

from cuga import CugaAgent

agent = CugaAgent(tools=[...])

# Add an Intent Guard
await agent.policies.add_intent_guard(
    name="Block Delete Operations",
    description="Prevents deletion of critical data",
    keywords=["delete", "remove", "erase"],
    response="Deletion operations are not permitted for security reasons.",
    priority=100
)

# Add a Playbook
await agent.policies.add_playbook(
    name="Budget Analysis Workflow",
    description="Multi-step process for analyzing financial budgets",
    natural_language_trigger=["When user asks to analyze their budget"],
    content="""# Budget Analysis Workflow
    ## Step 1: Calculate Total Expenses
    ...
    """,
    priority=50
)

Documentation

• Policy System Guide: Comprehensive HTML documentation with interactive diagrams explaining policy matching, enactment, and integration
• SDK Documentation: SDK Guide | Policies Guide

---

☁️ E2B Cloud Sandbox Integration

CUGA now supports E2B for cloud-based code execution in secure, ephemeral sandboxes. This provides better isolation than local execution while being faster than Docker/Podman containers.

Key Features

• Cloud-Native Execution: Execute code in secure, isolated cloud sandboxes without requiring Docker/Podman
• Flexible Sandbox Modes: Three modes for different use cases:
  • per-session (default): One sandbox per conversation thread, cached for reuse
  • single: Single shared sandbox across all threads (most cost-effective)
  • per-call: New sandbox for each execution (most isolated, highest cost)
• Automatic Caching: Per-session sandboxes are cached and reused, optimizing costs
• TTL Management: Configurable idle timeout and max age for sandbox lifecycle management
• Tool Integration: E2B sandboxes can call back to local API registry via ngrok tunneling

Benefits

• ✅ No Docker/Podman required
• ✅ Faster than container-based sandboxing
• ✅ Cloud-native with automatic scaling
• ✅ Better isolation than local execution
• ✅ Supports per-session caching for cost optimization

Configuration

Enable E2B in ./src/cuga/settings.toml:

[advanced_features]
e2b_sandbox = true
e2b_sandbox_mode = "per-session"  # Options: "per-session" | "single" | "per-call"
e2b_sandbox_idle_ttl = 600  # Idle timeout in seconds (default: 10 min)
e2b_sandbox_max_age = 86400  # Max age for "single" mode in seconds (24h)
e2b_sandbox_ttl_buffer = 60  # Safety buffer in seconds before E2B timeout
e2b_cleanup_on_create = true  # Run periodic cleanup when creating new sandboxes
e2b_cleanup_frequency = 0  # Check all sandboxes every N get_or_create calls

Setup Requirements

1. E2B API Key: Sign up at e2b.dev and create an API key
2. E2B Template: Create the cuga-langchain template using E2B CLI
3. Registry Exposure: Expose local API registry via ngrok for tool execution
4. Dependencies: Install with uv sync --group e2b

Usage

Once configured, E2B automatically executes code in cloud sandboxes. You'll see logs indicating "CODE SENT TO E2B SANDBOX" when E2B is active.

Note: E2B is a paid service with a free tier. Check e2b.dev/pricing for details.

---

🔧 Configuration Updates

Policy System Configuration

Enable/disable the policy system in ./src/cuga/settings.toml:

[policy]
enabled = true  # Enable/disable policy system
playbook_refine = false  # Enable playbook refinement based on user progress

E2B Configuration

New settings in ./src/cuga/settings.toml:

[advanced_features]
e2b_sandbox = false  # Enable E2B cloud sandbox
e2b_sandbox_mode = "per-session"  # Sandbox lifecycle mode
e2b_sandbox_idle_ttl = 600  # Idle timeout in seconds
e2b_sandbox_max_age = 86400  # Max age for single mode
e2b_sandbox_ttl_buffer = 60  # Safety buffer before timeout
e2b_cleanup_on_create = true  # Enable cleanup on sandbox creation
e2b_cleanup_frequency = 0  # Cleanup frequency (0 = only on create)

[server_ports]
function_call_host = ""  # ngrok URL for exposing registry to E2B

---

📚 Documentation

Updated Documentation

• README.md: Updated with Policy System and E2B sections
• SDK Documentation: Enhanced with policy management examples
• Configuration Guides: Added E2B setup instructions

---

🧪 Testing

Policy System Tests

Comprehensive test suite in src/cuga/backend/cuga_graph/policy/tests/:

• Intent Guard: Blocking behavior, priority resolution, multiple guard scenarios
• Playbook: Guidance injection, plan refinement, workflow execution
• Tool Approval: Human-in-the-loop approval flows (approve/deny)
• Tool Guide: Context enhancement and metadata injection
• Output Formatter: Response formatting and routing
• NL Trigger Conflict Resolution: Embedding-based similarity search with LLM conflict resolution
• Embedding Similarity: Vector search, policy matching, threshold validation
• Keyword Operators: AND/OR logic, case sensitivity, multi-keyword matching

E2B Integration Tests

• Direct E2B Tests: src/cuga/backend/cuga_graph/nodes/cuga_lite/executors/tests/test_e2b_direct.py
• E2B Lite Tests: src/cuga/backend/cuga_graph/nodes/cuga_lite/executors/tests/test_e2b_lite.py
• Code Executor Tests: Local sandbox and E2B execution scenarios

---

🚀 Migration Guide

Enabling Policies

1. Ensure policy system is enabled in settings.toml:

   [policy]
   enabled = true

2. Policies are automatically checked during agent execution - no code changes required

3. To add policies programmatically, use the SDK:

   await agent.policies.add_intent_guard(...)

Enabling E2B

1. Install E2B dependencies:

   uv sync --group e2b

2. Set up E2B API key and template (see README.md for detailed instructions)

3. Configure ngrok tunnel for registry exposure

4. Enable in settings.toml:

   [advanced_features]
   e2b_sandbox = true

---

📊 Performance & Benchmarks

Policy System

• Matching Performance: Keyword triggers provide fast exact matching, while NL triggers use vector search for semantic understanding
• Storage: Milvus vector database enables efficient policy retrieval and similarity search
• Conflict Resolution: LLM-based conflict resolution ensures accurate policy selection when multiple policies match

E2B Integration

• Execution Speed: Faster than Docker/Podman containers while providing better isolation
• Cost Optimization: Per-session caching reduces sandbox creation costs
• Scalability: Cloud-native architecture with automatic scaling

---

🙏 Acknowledgments

Special thanks to the CUGA community for feedback, testing, and contributions that made these features possible.

---

📝 Notes

• Policy system requires Milvus for vector storage (supports both Milvus server and Milvus Lite)
• E2B requires an active API key and ngrok for registry exposure
• Both features are optional and can be enabled/disabled via configuration

For detailed setup instructions, see the README.md and SDK Documentation.

---

This discussion was created from the release v0.2.7.