This directory contains practical examples demonstrating how to use Paracle's features, organized by category.

• basics/ - Getting started with core tools and concepts
• agents/ - Agent creation, configuration, and inheritance
• tools/ - Tool registry and plugin development
• workflows/ - Workflow orchestration and conflict resolution
• security/ - Sandboxing, network isolation, and security features
• git/ - Git workflows, commits, and pre-commit hooks
• observability/ - Monitoring, profiling, and observability
• advanced/ - Advanced features (HITL, multi-provider, caching, etc.)
• governance/ - Logging, compliance, and governance

File: agents/real_world_inheritance.py

Demonstrates Paracle's unique agent inheritance feature - not available in any other framework!

Build a hierarchy of specialized code reviewers:

• Base Reviewer → Python Specialist → FastAPI Expert → Security Auditor
• 4-level inheritance chain with tool/skill accumulation
• Property overrides and metadata merging

uv run python content/examples/agents/real_world_inheritance.py

Learn more: Agent Inheritance Documentation

All examples can be run using uv:

# From project root
uv run python content/examples/basics/01_filesystem_tools.py

Located in basics/:

• 01_filesystem_tools.py - File and directory operations
• 02_http_tools.py - HTTP client operations
• 03_shell_tools.py - Safe shell command execution
• hello_world_agent.py - Your first Paracle agent

Located in agents/:

• 04_agent_with_tools.py - Agents using built-in tools
• 06_agent_skills.py - Agent skills system
• 14_agent_skills.py - Advanced skills usage
• 23_agent_groups.py - Multi-agent coordination
• agent_inheritance.py - Basic agent inheritance
• parac_agents_inheritance.py - Framework agent inheritance
• real_world_inheritance.py - ⭐ Real-world inheritance example

Located in tools/:

• 05_tool_registry.py - Tool registration and discovery
• 20_plugin_development.py - Plugin system development

Located in workflows/:

• 16_kanban_workflow.py - Kanban board workflow
• 18_conflict_resolution.py - Git conflict resolution workflow

Located in security/:

• 09_sandbox_execution.py - Docker sandbox execution
• 10_network_isolation.py - Network isolation
• security_agent.py - Security-focused agent

Located in git/:

• 17_automatic_commits.py - Automatic git commits
• 21_git_workflows.py - Git workflows and operations
• 21_precommit_hook.py - Pre-commit hook integration

Located in observability/:

• 13_phase8_profiling.py - Performance profiling
• 22_continuous_monitoring.py - Real-time monitoring
• 24_observability_basics.py - Observability fundamentals

Located in advanced/:

• 07_human_in_the_loop.py - Human approval workflows
• 07_multi_provider.py - Multi-provider support
• 08_self_hosted_providers.py - Self-hosted LLM providers
• 08_yolo_mode.py - YOLO mode (auto-approve)
• 11_rollback_on_failure.py - Automatic rollback
• 12_artifact_review.py - Artifact review system
• 13_phase5_integration.py - Phase 5 integration
• 14_response_caching.py - Response caching
• 25_remote_development.py - Remote development setup
• 26_ai_generation.py - AI-powered code generation

Located in governance/:

• 19_automatic_logging.py - Automatic action logging
• 20_ai_compliance_copilot.py - AI compliance assistant

Demonstrates file and directory operations:

• read_file: Read file contents with metadata
• write_file: Write content to files with auto-create directories
• list_directory: List directory contents (recursive option)
• delete_file: Delete files safely
• Path restrictions: Security through allowed paths

Run:

uv run python content/examples/basics/01_filesystem_tools.py

Key concepts:

• Path-based security sandboxing
• Automatic parent directory creation
• File metadata (size, lines, encoding)
• Error handling patterns

Demonstrates HTTP client operations:

• http_get: GET requests with headers and params
• http_post: POST with JSON or form data
• http_put: PUT requests for updates
• http_delete: DELETE requests
• Timeouts: Custom timeout configuration

Run:

uv run python examples/02_http_tools.py

Key concepts:

• RESTful API interactions
• JSON auto-detection and parsing
• Query parameters and headers
• Timeout handling
• Real-world API examples (GitHub, JSONPlaceholder)

Note: Requires httpx package (already in project dependencies)

Demonstrates safe shell command execution:

• run_command: Execute shell commands safely
• Security: Blocked dangerous commands (rm, sudo, etc.)
• Whitelists: Command whitelisting for production
• Timeouts: Prevent hung processes
• Stderr handling: Capture both stdout and stderr

Run:

uv run python examples/03_shell_tools.py

Key concepts:

• Command blocklist (security)
• Command whitelist (production safety)
• Timeout enforcement
• Exit code handling
• Git and pytest integration

Security notes:

• Dangerous commands blocked by default
• Use whitelists in production
• Always validate command inputs

Demonstrates building an agent that uses multiple tools together:

Scenario: Code analysis agent that:

1. Discovers Python files in a directory
2. Reads and analyzes source code
3. Runs test suite
4. Fetches external documentation
5. Generates comprehensive report

Run:

uv run python examples/04_agent_with_tools.py

Key concepts:

• Combining multiple tools in workflows
• Agent-based architecture
• Async/await patterns
• Report generation
• Real-world task automation

Tools used: list_directory, read_file, run_command, http_get, write_file

Advanced BuiltinToolRegistry usage:

• Discovery: List and inspect available tools
• Categorization: Tools organized by category
• Security: Configure permissions and restrictions
• Dynamic selection: Choose tools at runtime
• Batch operations: Execute multiple tools in parallel
• Reconfiguration: Update settings on the fly
• Introspection: Query tool metadata

Run:

uv run python examples/05_tool_registry.py

Key concepts:

• Centralized tool management
• Permission system
• Runtime configuration
• Tool metadata and introspection
• Error handling patterns
• Concurrent execution

Demonstrates the Agent Skills system (see existing example).

Demonstrates Paracle's Human-in-the-Loop approval system for AI governance (ISO 42001):

• Approval Gates: Steps that require human approval before proceeding
• Approval Manager: Create, approve, reject, cancel approval requests
• Workflow Integration: Automatic pause/resume based on approval status
• REST API: Full API endpoints for approval management
• Priority Levels: LOW, MEDIUM, HIGH, CRITICAL
• Timeout Handling: Auto-reject or manual handling on timeout

Scenario: CI/CD deployment pipeline where:

1. AI analyzes code changes (automatic)
2. AI performs security review (automatic)
3. Human reviews and approves deployment (REQUIRES APPROVAL)

Run:

uv run python examples/07_human_in_the_loop.py

Key concepts:

• requires_approval=True on WorkflowStep
• approval_config for timeout, priority, approvers
• ApprovalManager for approval lifecycle
• ExecutionStatus.AWAITING_APPROVAL state
• API endpoints: /approvals/pending, /approvals/{id}/approve

ISO 42001 Compliance:

• Human oversight for critical AI decisions
• Audit trail of all approvals/rejections
• Configurable approval policies

Demonstrates using multiple LLM providers (see existing example).

NEW - Phase 5: Docker-based isolated execution with resource limits:

• SandboxManager: Create and orchestrate sandboxes
• Resource Limits: CPU, memory, disk, timeout constraints
• SandboxMonitor: Real-time resource monitoring
• Automatic Cleanup: Context managers for resource safety
• Statistics: CPU/memory usage, network I/O tracking

Run:

uv run python examples/09_sandbox_execution.py

Key concepts:

• Isolated Docker containers for safe execution
• Resource limit enforcement
• Real-time monitoring and alerts
• Automatic cleanup on exit

NEW - Phase 5: Network isolation and security policies:

• NetworkIsolator: Create isolated Docker networks
• Network Policies: Control internet/intra-network access
• Container Attachment: Connect containers to networks
• Port Control: Allow/block specific ports
• IP Blocking: Block dangerous IP ranges

Run:

uv run python examples/10_network_isolation.py

Key concepts:

• Docker network creation and management
• Policy-based network access control
• Inter-container communication
• External access restrictions

NEW - Phase 5: Automatic snapshot-based recovery:

• RollbackManager: Snapshot and restore filesystem state
• Automatic Rollback: Policy-triggered recovery on errors
• Snapshot Management: Retention policies, cleanup
• Manual Rollback: Restore to specific checkpoints
• Tarball Strategy: Compressed snapshots

Run:

uv run python examples/11_rollback_on_failure.py

Key concepts:

• Filesystem snapshot creation
• Automatic recovery on failure
• Snapshot retention policies
• Manual checkpoint restoration

NEW - Phase 5: Human-in-the-loop artifact approval:

• ReviewManager: Create and manage artifact reviews
• Risk Assessment: Automatic pattern-based risk detection
• Approval Workflow: Multi-reviewer approval process
• Auto-Approval: Low-risk artifacts bypass review
• Review Statistics: Track approval metrics

Run:

uv run python examples/12_artifact_review.py

Key concepts:

• Pattern-based risk assessment
• Multi-approval workflow
• Auto-approval for low-risk changes
• Rejection and timeout handling

NEW - Phase 5: Complete safety stack integration:

• Full Stack: Sandbox + Network + Rollback + Review
• Safety Pipeline: Comprehensive execution protection
• Error Recovery: Automatic rollback on failures
• Approval Gates: Review workflow integration
• Statistics: End-to-end metrics

Run:

uv run python examples/13_phase5_integration.py

Key concepts:

• Complete Phase 5 feature integration
• Multi-layer security and safety
• Coordinated resource management
• Production-ready patterns

==============================================================
Paracle Filesystem Tools Example
==============================================================

1. Writing files...
✓ Created file: /path/to/hello.txt
  Size: 32 bytes
  Lines: 2
✓ Created config: /path/to/config.yaml
✓ Created nested file: /path/to/data/output.json

2. Listing directory contents...
✓ Found 3 items in /path/to/temp_example
  📄 hello.txt (32 bytes)
  📄 config.yaml (98 bytes)
  📁 data
...

==============================================================
Paracle HTTP Tools Example
==============================================================

1. GET request - Fetch user data from API...
✓ Status: 200
  URL: https://jsonplaceholder.typicode.com/users/1
  User: Leanne Graham
  Email: [email protected]
  City: Gwenborough
...

==============================================================
Paracle Shell Command Tool Example
==============================================================

1. Running simple commands...
✓ Command executed successfully
  Output: Hello from Paracle
  Return code: 0

6. Security - Blocked commands...
Attempting 'rm -rf /': success=False
  ✓ Blocked! Error: Command 'rm' is blocked for security
...

from paracle_tools import read_file

result = await read_file.execute(path="file.txt")

if result.success:
    print(result.output['content'])
else:
    print(f"Error: {result.error}")

from paracle_tools import BuiltinToolRegistry

# Create registry with security config
registry = BuiltinToolRegistry(
    filesystem_paths=["./data"],
    allowed_commands=["git", "pytest"]
)

# Execute tool by name
result = await registry.execute_tool(
    "read_file",
    path="data/config.yaml"
)

result = await some_tool.execute(...)

if result.success:
    # Happy path
    data = result.output
else:
    # Error handling
    error_msg = result.error
    error_context = result.metadata

import asyncio

# Execute multiple tools concurrently
results = await asyncio.gather(
    read_file.execute(path="file1.txt"),
    read_file.execute(path="file2.txt"),
    http_get.execute(url="https://api.example.com")
)

# ✅ DO: Restrict filesystem access
tool = ReadFileTool(allowed_paths=["/app/data", "/tmp"])

# ❌ DON'T: Allow unrestricted access in production
tool = ReadFileTool()  # No restrictions

# ✅ DO: Use explicit whitelists
tool = RunCommandTool(allowed_commands=["git", "pytest"])

# ❌ DON'T: Rely only on blocklist
tool = RunCommandTool()  # Default blocklist only

# ✅ DO: Set appropriate timeouts
registry = BuiltinToolRegistry(
    http_timeout=10.0,
    command_timeout=30.0
)

# ❌ DON'T: Use very long timeouts
registry = BuiltinToolRegistry(
    http_timeout=3600.0  # 1 hour - too long!
)

# ✅ DO: Validate inputs before executing
def safe_read_file(user_input: str):
    path = Path(user_input).resolve()
    if not path.is_file():
        raise ValueError("Not a file")
    return await read_file.execute(path=str(path))

# ❌ DON'T: Pass user input directly
result = await read_file.execute(path=user_input)

• Read the docs: See docs/builtin-tools.md for full API reference
• Build an agent: Combine tools to create your own agents
• Explore MCP tools: Check out Model Context Protocol integration
• Run tests: See how tools are tested in tests/unit/test_builtin_tools_*.py

Error: httpx is not installed. Install with: pip install httpx

Fix:

uv add httpx

Error: Access denied: /etc/passwd is not in allowed paths

Fix: Check your allowed_paths configuration or use a different path

Error: Command 'python' is not in allowed commands

Fix: Add the command to allowed_commands list or use a different command

Error: Command timed out after 30.0 seconds

Fix: Increase timeout or optimize the command

To add a new example:

1. Create examples/0X_example_name.py
2. Follow existing structure (imports, main function, docstring)
3. Add clear comments and error handling
4. Update this README
5. Test the example: uv run python examples/0X_example_name.py

See LICENSE file in the project root.