legate 0.1.0

data/public/docs/guides/webhooks.md

@@ -0,0 +1,288 @@
+# Using Inbound Webhooks in Legate
+
+This document explains how to configure and use the inbound webhook feature in the Legate framework to trigger agent tasks from external systems.
+
+## Goal
+
+The primary goal of this feature is to allow external events (e.g., Git pushes, CI/CD notifications, CRM updates, IoT alerts) to initiate specific agent workflows asynchronously without requiring direct code integration or constantly running agent processes.
+
+## Architecture Overview
+
+The following diagram illustrates the flow of an inbound webhook request triggering an agent task:
+
+```mermaid
+graph LR
+    Ext[External System] -- HTTP Request --> Listen[Webhook Listener]
+    Listen -- Raw Request --> Router
+    Router -- Route Match --> Handler[Dynamic Agent Handler]
+    Handler -- Load Definition & Metadata --> Store[(Agent Definition Store)]
+    Handler -- Validation/Transform/Extract --> ThreadPool[Threaded Execution]
+    ThreadPool -- Concurrent::Promises.future --> AgentExec[Agent Execution]
+    AgentExec -- Load Definition --> Store
+    AgentExec -- Get Session --> SessionSvc[(Session Service)]
+    AgentExec -- Instantiate Agent --> AgentDef[Agent Definition]
+    AgentDef -- Uses --> SessionSvc
+    AgentExec -- Calls run_task --> AgentInst[Agent Instance]
+    AgentInst -- Logs Events --> SessionSvc
+    AgentInst -- Task Result --> AgentExec
+    AgentExec -- Logs Outcome --> Log[(Logs)]
+
+    subgraph "Webhook Listener Process"
+        Listen
+        Router
+        Handler
+    end
+
+    subgraph "In-Process Threaded Execution"
+        AgentExec
+        AgentInst
+        Log
+    end
+
+    style Store fill:#f9f,stroke:#333,stroke-width:2px
+    style SessionSvc fill:#f9f,stroke:#333,stroke-width:2px
+    style JobQueue fill:#ccf,stroke:#333,stroke-width:2px
+```
+
+**Key Components:**
+
+*   **Webhook Listener:** Receives HTTP requests, performs initial routing.
+*   **Dynamic Agent Handler:** Looks up agent definitions, validates, transforms, extracts session IDs based on agent metadata, and enqueues jobs.
+*   **Threaded Execution (`Concurrent::Promises.future`):** Runs webhook tasks asynchronously in background threads within the same process.
+*   **Agent Execution:** Loads definitions, instantiates agents, interacts with the Session Service, and executes `agent.run_task`.
+*   **Agent Definition Store:** Stores agent configurations, including webhook metadata.
+*   **Session Service:** Manages agent conversation state.
+
+## Enabling the Webhook Listener
+
+To receive webhooks, you first need to enable the built-in listener application within your Legate configuration (e.g., in `config/initializers/legate.rb` or your main setup file).
+
+```ruby
+# config/initializers/legate.rb or similar
+require 'legate'
+
+Legate.configure do |config|
+  # --- Enable the listener --- 
+  config.webhooks.listener_enabled = true
+
+  # --- Optional Listener Settings --- 
+  # Address to bind to (default: '127.0.0.1')
+  # Use '0.0.0.0' to listen on all interfaces (common for containers/production)
+  config.webhooks.listen_address = "0.0.0.0" 
+  
+  # Port to listen on (default: 9292)
+  config.webhooks.listen_port = 9293 
+
+  # Base path for all webhook routes (default: '/webhooks')
+  config.webhooks.base_path = "/myhooks"
+
+  # ... other Legate configurations ...
+end
+```
+
+When `listener_enabled` is `true`, the `legate web start` command will automatically mount the listener alongside the main Web UI (in development/test environments). For production, see the Deployment section.
+
+## Triggering Agents via Webhook
+
+The recommended way to trigger specific agents is using the dynamic agent route handler.
+
+### Enabling the Dynamic Handler
+
+Enable the dynamic route in your Legate configuration:
+
+```ruby
+Legate.configure do |config|
+  config.webhooks.listener_enabled = true
+  # ... other listener settings ...
+
+  # --- Enable the dynamic route --- 
+  config.webhooks.enable_dynamic_agent_handler = true
+
+  # --- Optional: Customize the route pattern ---
+  # The default pattern includes :agent_name parameter.
+  # config.webhooks.dynamic_agent_route_pattern = '/invoke/:agent_name' # Example override
+  
+  # ... other Legate configurations ...
+end
+```
+
+With the default settings (`base_path = '/webhooks'`, `dynamic_agent_route_pattern = '/agents/:agent_name/trigger'`), you can trigger an agent named `:my_cool_agent` by sending a `POST` request to:
+
+`POST /webhooks/agents/my_cool_agent/trigger`
+
+### Configuring an Agent to Receive Webhooks
+
+For an agent to be triggerable via the dynamic route, you **must** configure specific metadata within its definition:
+
+```ruby
+# app/agents/my_webhook_agent.rb (or loaded via DefinitionStore)
+require 'legate'
+
+Legate::Agent.define do |a|
+  a.name :my_webhook_agent
+  a.description "Processes incoming data from external service X."
+  a.instruction "Summarize the provided data."
+  # ... other agent settings (tools, model) ...
+
+  # --- Webhook Configuration Metadata --- 
+  
+  # 1. Enable Webhook Triggering (REQUIRED)
+  # MUST be true for the dynamic route to work for this agent.
+  a.webhook_enabled true 
+
+  # 2. Define Payload Transformation (REQUIRED if enabled)
+  # A Proc that takes the parsed request body (Hash/Array) and returns
+  # the specific String or Hash expected by this agent's `run_task` `user_input`.
+  a.webhook_transformer ->(request_body) do
+    # Example: Extract data from a specific key
+    data = request_body['important_data']
+    unless data
+      # You can raise errors for invalid payloads
+      raise Legate::WebhookConfigurationError, "Missing 'important_data' in webhook payload."
+    end
+    "Summarize this: #{data}" # Return the user_input for run_task
+  end
+
+  # 3. Define Session ID Extraction (REQUIRED if enabled)
+  # A Proc that takes the parsed request body and returns a String 
+  # to be used as the session_id for this task.
+  # Allows grouping related events (e.g., multiple events for the same resource).
+  a.webhook_session_extractor ->(request_body) do
+    # Example: Use a resource ID from the payload
+    resource_id = request_body.dig('resource', 'id') 
+    raise Legate::WebhookConfigurationError, "Missing resource ID in payload." unless resource_id
+    "external_resource_#{resource_id}" # Return the session_id string
+  end
+
+  # 4. Configure Validation (Optional, but Recommended)
+  # Option A: Use a globally registered named validator (see below)
+  a.webhook_validator :hmac_sha256 
+  # Option B: Provide a custom Proc directly
+  # a.webhook_validator ->(request, secret) { request.params['token'] == secret }
+
+  # 5. Provide a Secret for the Validator (Optional)
+  # Used by the validator logic (e.g., the HMAC key or the token).
+  a.webhook_secret ENV['MY_SERVICE_X_WEBHOOK_SECRET'] 
+end
+```
+
+**Key Requirements:**
+*   `webhook_enabled` **must** be set to `true`.
+*   `webhook_transformer` Proc **must** be defined.
+*   `webhook_session_extractor` Proc **must** be defined.
+
+If these are not met, the dynamic route handler will return an error (likely 404 or 500) when a request for that agent is received.
+
+## Request Validation
+
+It's highly recommended to validate incoming webhooks to ensure they originate from the expected source.
+
+### Using Named Validators (HMAC Example)
+
+You can define reusable validation logic globally in your Legate configuration and reference it by name in your agent definitions.
+
+> **Note:** Legate already ships with a built-in `:hmac_sha256` validator (registered automatically), so you can reference `a.webhook_validator :hmac_sha256` without defining it yourself. The example below shows how an equivalent validator is implemented if you want to register your own.
+
+```ruby
+# config/initializers/legate.rb or similar
+require 'openssl'
+
+Legate.configure do |config|
+  # ... listener config ...
+  config.webhooks.enable_dynamic_agent_handler = true
+
+  # --- Define a named HMAC SHA256 validator ---
+  config.webhooks.register_validator(:hmac_sha256) do |request, secret|
+    # Ensure a secret is configured for the agent/route
+    return false unless secret 
+    # GitHub example: X-Hub-Signature-256: sha256=...
+    signature_header = request.env['HTTP_X_HUB_SIGNATURE_256']
+    return false unless signature_header&.start_with?('sha256=')
+    
+    expected_signature = signature_header.delete_prefix('sha256=')
+    
+    request.body.rewind # Read body for calculation
+    payload_body = request.body.read
+    request.body.rewind # Rewind for transformer
+    
+    calculated_signature = OpenSSL::HMAC.hexdigest('sha256', secret, payload_body)
+    
+    # Compare in constant time to prevent timing attacks. A length check is
+    # required first because OpenSSL.fixed_length_secure_compare raises on
+    # unequal-length inputs.
+    calculated_signature.bytesize == expected_signature.bytesize &&
+      OpenSSL.fixed_length_secure_compare(calculated_signature, expected_signature)
+  end
+
+  # Optional: Define a global secret if many agents share one
+  # config.webhooks.global_secret = ENV['LEGATE_GLOBAL_WEBHOOK_SECRET']
+  
+  # Optional: Set a default validator if an agent doesn't define one
+  # config.webhooks.global_validator = :hmac_sha256
+end
+```
+
+Then, in your agent definition, reference the validator and provide the secret:
+
+```ruby
+Legate::Agent.define do |a|
+  # ... name, description, transformer, extractor ...
+  a.webhook_enabled true
+  a.webhook_validator :hmac_sha256 # Use the named validator
+  a.webhook_secret ENV['SPECIFIC_AGENT_WEBHOOK_SECRET'] # Provide the secret
+end
+```
+
+### Using Custom Validator Procs
+
+For unique validation logic, provide a Proc directly in the agent definition:
+
+```ruby
+Legate::Agent.define do |a|
+  # ... name, description, transformer, extractor ...
+  a.webhook_enabled true
+  a.webhook_validator ->(request, secret) do 
+    # Example: Check a query parameter against the secret
+    request.params['auth_token'] == secret
+  end
+  a.webhook_secret ENV['AGENT_AUTH_TOKEN']
+end
+```
+
+The validator proc receives the Rack `request` object and the configured `secret` string (or `nil` if none is set).
+
+## Workflow Overview
+
+1.  **External System** sends `POST /webhooks/agents/agent_name/trigger` with a JSON payload.
+2.  **WebhookListener** receives the request.
+3.  **Dynamic Handler** matches the route pattern (`/agents/:agent_name/trigger`).
+4.  Handler loads the `:agent_name` **Agent Definition**.
+5.  Checks `webhook_enabled` (must be `true`).
+6.  Performs **Validation** using `webhook_validator` and `webhook_secret`.
+7.  If valid, performs **Transformation** using `webhook_transformer` to get `user_input`.
+8.  Extracts **Session ID** using `webhook_session_extractor`.
+9.  Constructs a **Job Payload** (`agent_name`, `session_id`, `user_input`, session service config).
+10. Dispatches the task via `Concurrent::Promises.future` for **threaded execution**.
+11. Listener returns **`202 Accepted`** to the external system.
+12. The background thread instantiates the **Session Service**.
+13. The thread loads the **Agent Definition**.
+14. The thread instantiates the **Agent** using the definition.
+15. The thread calls `agent.run_task(session_id:, user_input:, session_service:)`.
+16. `run_task` executes the agent logic (planning, tool use).
+17. The thread logs the outcome.
+
+## Security Considerations
+
+*   **HTTPS:** Always serve the webhook listener over HTTPS in production.
+*   **Secret Management:** Use environment variables or a secure secret management system for `webhook_secret` values. Never hardcode secrets.
+*   **Validation:** Strongly recommend validation (e.g., HMAC) for all webhooks triggering actions or handling sensitive data.
+*   **Input Sanitization:** Be mindful of how the `transformed_user_input` is used within your agent's instructions and tools to prevent potential injection issues.
+*   **Rate Limiting:** Consider adding rate limiting middleware (e.g., `rack-attack`) in front of the listener endpoint to prevent abuse.
+
+## Deployment
+
+*   **Development:** Run `bundle exec legate web start`. If `listener_enabled` is true, the listener will be mounted automatically within the main web server process.
+*   **Production:**
+    *   You can continue running the combined app as in development.
+    *   Alternatively, for better isolation and scaling, you can create a separate `config.ru` and Procfile entry to run the `Legate::Web::WebhookListener` Rack app as a standalone process using a server like Puma or Unicorn.
+    *   Webhook jobs run in-process via background threads using `Concurrent::Promises.future`, so no separate worker process is needed. 

data/public/docs/introduction.md

@@ -0,0 +1,51 @@
+# Welcome to the Legate Documentation
+
+Legate — AI Agent Framework for Ruby — is a comprehensive framework designed to simplify the creation, management, and deployment of sophisticated AI agents. Whether you're building simple task-oriented bots or complex, multi-tool agents capable of intricate planning, the Legate provides the foundational components and a streamlined workflow to accelerate your development process.
+
+This documentation will guide you through understanding the core principles of Legate, setting up your development environment, utilizing its built-in features, and extending its capabilities to suit your specific needs.
+
+## What is Legate?
+
+Legate is a Ruby-based toolkit that empowers developers to:
+
+*   **Define Agent Capabilities:** Easily specify an agent's instructions, the tools it can use, the AI model it leverages (e.g., from Google's Gemini family), and its operational parameters.
+*   **Manage Agent Lifecycle:** Control how agents are started, how they process tasks, and how they are stopped or updated.
+*   **Utilize a Rich Toolset:** Leverage a variety of built-in tools (like calculators, webhooks, and even tools that delegate tasks to other agents) or create your own custom tools.
+*   **Handle Complex Interactions:** Employ a planner that enables agents to break down complex requests into a sequence of tool calls.
+*   **Persist and Manage State:** Use session services and definition stores to manage conversational history and agent configurations.
+*   **Integrate with External Systems:** Expose agents via web UIs, connect them to messaging platforms, or trigger them with webhooks.
+*   **Deploy with Ease:** Generate deployment assets (like Dockerfiles and cloud configuration scripts) to run your Legate applications in various environments.
+
+## Getting Started
+
+To begin your journey with Legate, we recommend the following steps:
+
+1.  **Understand the Fundamentals:** Familiarize yourself with the [Core Concepts](./core_concepts/legate_architecture_overview) that underpin the Legate, such as the [Agent Lifecycle](./core_concepts/legate_agent_lifecycle), [Tools and Registry](./tools/legate_tools_and_registry), and [Session Management](./core_concepts/legate_session_service).
+2.  **Setup Your Environment:** Ensure you have Ruby and Bundler installed. Most Legate projects will start by adding `legate` to their `Gemfile`.
+3.  **Explore the Configuration:** Learn how to configure Legate globally and per agent by reviewing the [Legate Configuration](./core_concepts/legate_configuration) guide.
+4.  **Try the CLI:** Use the [Legate Command-Line Interface](./cli/legate_cli_usage) to manage agent definitions, run the web UI, and interact with other Legate components.
+5.  **Run an Example:** Browse the [Examples Guide](./examples) for 16 hands-on examples covering every major feature, from basic agents to MCP integration.
+
+## Key Features
+
+*   **Modular Architecture:** Easily extendable and customizable.
+*   **Powerful Planner:** Enables multi-step reasoning and tool usage.
+*   **Rich Tool Ecosystem:** Comes with several built-in tools and a clear interface for adding new ones.
+*   **Agent Definition Store:** Persistently store and manage your agent configurations.
+*   **Session Management:** Track conversation history and agent state.
+*   **Web UI:** A built-in Sinatra application for managing agents and viewing sessions.
+*   **CLI for Management:** Robust command-line tools for development and administration.
+*   **Deployment Assistance:** Tools to generate Dockerfiles and deployment scripts.
+
+## Navigating these Docs
+
+This documentation is organized into several key areas:
+
+*   **[Core Concepts](./core_concepts/):** Deep dives into the fundamental building blocks and architecture of Legate.
+*   **[Guides](./guides/):** Practical step-by-step instructions for common tasks and integrations.
+*   **[CLI Reference](./cli/legate_cli_usage):** Detailed information on using the `legate` command-line tool.
+*   **[Web UI Overview](./web_ui/legate_web_ui):** Information about the built-in web interface.
+*   **[Built-in Tools Reference](./tools/legate_built_in_tools):** Documentation for the tools that come packaged with Legate.
+*   **[Error Handling](./error_handling/legate_error_handling):** Guidance on understanding and managing errors within Legate.
+
+We hope this documentation helps you build amazing AI agents with Legate! 

data/public/docs/multi_agent_systems/advanced_features.md

@@ -0,0 +1,57 @@
+# Advanced Features
+
+## Agent Delegation
+
+Agents can dynamically delegate tasks to other specialized agents during execution. This allows an agent to "ask for help" or hand off a sub-task.
+
+### Configuration
+
+Use `can_delegate_to` to specify which agents are available for delegation.
+
+```ruby
+Legate::Agent.define do |agent|
+  agent.name :manager
+  agent.instruction "Manage the project and delegate tasks."
+  
+  # Allow delegation to these agents
+  agent.can_delegate_to :researcher, :coder
+end
+```
+
+### How it Works
+
+1.  **Planning**: The `Legate::Planner` sees the available delegation targets as "tools" (e.g., `agent_transfer_to_researcher`).
+2.  **Execution**: If the agent decides to delegate, it invokes the delegation tool.
+3.  **Transfer**: The `Legate::Agent` intercepts this call and executes the target agent with the specified task.
+4.  **Session Reuse**: `can_delegate_to` / `Agent#transfer_to` delegation **reuses the calling session** — the same `session_id` is passed to the target agent, so both agents share session state. It does *not* create a new isolated session.
+
+### Delegation vs. `AgentTool`
+
+A separate mechanism, the `AgentTool` (registered as the `:delegate_task` tool), runs another agent from within a tool call. Unlike `transfer_to`, `AgentTool` defaults to a **new isolated session**. It exposes a `use_calling_session` parameter (default `false`) that, when set to `true`, makes it reuse the caller's session and share state instead.
+
+## Callbacks
+
+You can hook into the agent's lifecycle to execute custom logic.
+
+```ruby
+Legate::Agent.define do |agent|
+  # ...
+  
+  agent.before_agent_callback do |context|
+    Legate.logger.info "Agent starting for session #{context.session_id}"
+  end
+  
+  agent.after_tool_callback do |tool, params, context, result|
+    # Modify result or log execution
+    Legate.logger.info "Tool #{tool.name} executed."
+  end
+end
+```
+
+Available callbacks:
+- `before_agent_callback`
+- `after_agent_callback`
+- `before_model_callback`
+- `after_model_callback`
+- `before_tool_callback`
+- `after_tool_callback`

data/public/docs/multi_agent_systems/agent_delegation.md

@@ -0,0 +1,190 @@
+# Agent Delegation in Legate
+
+## Overview
+
+Agent delegation is a powerful feature in Legate that allows one agent to dynamically transfer control to another specialized agent during execution. This enables complex workflows where a coordinator agent can make decisions about which specialized agent should handle a particular task.
+
+Unlike the `AgentTool` approach, which creates a new isolated session for the target agent, delegation maintains the same session context. This ensures continuity and allows agents to share state through the session.
+
+## Key Concepts
+
+### Delegation Targets
+
+For an agent to delegate to another agent, the target agents must be explicitly defined as "delegation targets" in the delegating agent's definition:
+
+```ruby
+coordinator_agent = Legate::Agent.define do |a|
+  a.name :coordinator_agent
+  a.description 'A coordinator agent that delegates tasks'
+  a.instruction 'You are a coordinator. Analyze tasks and delegate to specialists.'
+  
+  # Define which agents this agent can delegate to
+  a.can_delegate_to :math_agent, :research_agent, :translation_agent
+  
+  # ... other configuration ...
+end
+```
+
+### Agent Hierarchy
+
+Delegation works within the agent hierarchy. An agent can:
+
+1. **Delegate to direct sub-agents**: When agents are organized in a parent-child relationship.
+2. **Delegate to any agent in the hierarchy**: By searching up and down the agent tree.
+3. **Delegate to registered agents**: Even agents not directly in the hierarchy can be delegated to if their definitions are registered globally.
+
+### Session State Continuity
+
+When delegation occurs:
+
+- The same session ID is used across all agents
+- The session state is shared, allowing agents to read and write state
+- The `output_key` feature can be used by each agent to store its results in the session state
+
+## Implementation Methods
+
+### 1. LLM-Driven Delegation
+
+The primary way delegation happens is through the LLM planner, which can generate plan steps with special "agent_transfer_to_X" tool names:
+
+```json
+{
+  "thought_process": "This is a math question, should delegate to math agent",
+  "plan": [
+    {
+      "step": 1,
+      "type": "tool_use",
+      "tool_name": "agent_transfer_to_math_agent",
+      "tool_input": {
+        "task": "Calculate the square root of 144"
+      },
+      "reason": "This is a mathematical calculation"
+    }
+  ]
+}
+```
+
+When the agent executes this plan, it recognizes the `agent_transfer_to_` prefix and performs delegation to the specified agent.
+
+### 2. Direct Transfer Method
+
+You can also programmatically delegate using the `transfer_to` method:
+
+```ruby
+result = agent.transfer_to(
+  :math_agent,           # Target agent name
+  "Calculate 2 + 2",     # Task to delegate
+  session_id,            # Current session ID
+  session_service        # Session service instance
+)
+```
+
+This returns a standard result hash:
+
+```ruby
+{
+  status: :success,
+  target_agent: "math_agent",
+  result: { status: :success, result: "4" }
+}
+```
+
+## Code Examples
+
+### Basic Delegation Setup
+
+```ruby
+# Define a math specialist agent
+math_agent = Legate::Agent.define do |a|
+  a.name :math_agent
+  a.description 'Specialized in calculations'
+  a.instruction 'You are a math expert. Solve calculations accurately.'
+  a.use_tool :calculate
+  a.output_key :calculation_result
+end
+
+# Define a coordinator that can delegate to the math agent
+coordinator = Legate::Agent.define do |a|
+  a.name :coordinator
+  a.description 'Coordinates tasks between agents'
+  a.instruction 'Analyze the task and delegate to specialists.'
+  a.can_delegate_to :math_agent
+  a.use_tool :echo
+end
+
+# Create and link the agents
+coordinator_instance = Legate::Agent.new(definition: coordinator)
+math_instance = Legate::Agent.new(definition: math_agent)
+
+# Establish parent-child relationship
+math_instance.instance_variable_set(:@parent_agent, coordinator_instance)
+coordinator_instance.instance_variable_set(:@sub_agents, [math_instance])
+
+# Start the agents
+coordinator_instance.start
+math_instance.start
+
+# Run a task that might be delegated
+result = coordinator_instance.run_task(
+  session_id: session_id,
+  user_input: "What is 125 * 45?",
+  session_service: session_service
+)
+```
+
+### Working with Session State
+
+```ruby
+# The delegated agent can store its result in the session state
+math_agent = Legate::Agent.define do |a|
+  a.name :math_agent
+  a.description 'Specialized in calculations'
+  a.instruction 'You are a math expert. Solve calculations accurately.'
+  a.use_tool :calculate
+  a.output_key :calculation_result  # Will store results with this key
+end
+
+# Later, another agent can access this result
+translator_agent = Legate::Agent.define do |a|
+  a.name :translator_agent
+  a.description 'Translates content'
+  a.instruction <<~INSTRUCTION
+    You are a translator. Translate text using the calculation results
+    from the math agent if available in the session state.
+  INSTRUCTION
+  a.use_tool :translate
+end
+```
+
+## Comparison: Delegation vs. AgentTool
+
+| Feature | Agent Delegation | AgentTool |
+|---------|-----------------|-----------|
+| **Session Context** | Maintains the same session | Creates a new session |
+| **State Sharing** | Shared session state | No state sharing, isolated execution |
+| **Agent Registration** | Uses agent hierarchy and registry | Uses agent definitions from store |
+| **Use Case** | Complex workflows with state continuity | Isolated, independent agent operations |
+| **Implementation** | Direct `transfer_to` or LLM-driven | Tool execution via `tool_registry` |
+
+## Best Practices
+
+1. **Be Specific with Instructions**: Provide clear guidelines in your coordinator agent's instructions about when to delegate and which specialized agent to use for different tasks.
+
+2. **Use `output_key`**: Have specialized agents store their results using the `output_key` feature to make them available in the session state.
+
+3. **Validate Delegation Targets**: Ensure all agents defined in `can_delegate_to` actually exist. The system will warn you about missing targets, but it's best to address these warnings.
+
+4. **Avoid Circular Delegation**: The system prevents direct circular dependencies, but complex cascading delegation chains should be avoided.
+
+5. **Consider Agent Hierarchy**: Organize your agents in a logical hierarchy that reflects your delegation patterns, with coordinator agents at the top and specialists as sub-agents.
+
+## Implementation Details
+
+Under the hood, delegation is implemented through:
+
+1. The `agent_transfer_to_` special tool name pattern recognized by `execute_step`
+2. The `transfer_to` method that handles the delegation logic
+3. Agent hierarchy navigation through `root_agent` and `find_agent` methods
+4. Session state persistence across agent boundaries
+
+For detailed implementation examples, see `examples/11_agent_delegation.rb` (and `examples/advanced/mas/proper_delegation_example.rb`) in the Legate codebase. 

data/public/docs/multi_agent_systems/agent_hierarchy.md

@@ -0,0 +1,49 @@
+# Agent Hierarchy
+
+The Legate supports a hierarchical agent structure, allowing agents to be composed of other agents (sub-agents). This enables the creation of complex systems where a parent agent coordinates the work of specialized child agents.
+
+## Core Concepts
+
+### Parent and Sub-Agents
+
+- **Parent Agent**: An agent that contains and manages other agents.
+- **Sub-Agent**: An agent that is managed by another agent. A sub-agent can also be a parent to other agents, creating a multi-level hierarchy.
+
+### Definition
+
+You can define sub-agents within an `Legate::AgentDefinition` using the `sub_agents_define` DSL method.
+
+```ruby
+Legate::Agent.define do |agent|
+  agent.name :parent_agent
+  agent.description "A parent agent that manages sub-agents"
+  agent.instruction "You are a manager. Delegate tasks to your sub-agents."
+  
+  # Define sub-agents by name
+  agent.sub_agents_define :researcher_agent, :writer_agent
+end
+```
+
+The sub-agents must be defined and registered in the `GlobalDefinitionRegistry` so they can be instantiated when the parent agent is initialized.
+
+## Runtime Structure
+
+When a parent agent is initialized, it attempts to instantiate its defined sub-agents.
+
+- **`agent.sub_agents`**: Returns a collection of initialized sub-agent instances.
+- **`agent.parent_agent`**: Returns the parent agent instance (if any).
+- **`agent.root_agent`**: Returns the top-level agent in the hierarchy.
+
+### Navigation
+
+You can navigate the hierarchy at runtime:
+
+- **`agent.find_sub_agent(name)`**: Finds a direct sub-agent by name.
+- **`agent.find_agent(name)`**: Finds an agent anywhere in the hierarchy (depth-first search).
+
+## Usage
+
+Hierarchies are fundamental to **Workflow Agents** (Sequential, Parallel, Loop) and **Delegation**.
+
+- **Workflow Agents**: Use sub-agents as steps in a predefined process.
+- **Delegation**: Uses sub-agents (or other agents in the hierarchy) as targets for dynamic task delegation.

data/public/docs/multi_agent_systems/state_management.md

@@ -0,0 +1,47 @@
+# State Management
+
+The Legate provides a robust state management system to share data between agents and persist execution context across sessions.
+
+## Session State
+
+Every agent execution happens within a `Session`. The session maintains:
+- **Event History**: A log of all interactions (user messages, agent responses, tool calls).
+- **State**: A key-value store for persisting data.
+
+## Output Keys
+
+Agents can automatically store their final result into the session state using the `output_key` definition.
+
+```ruby
+Legate::Agent.define do |agent|
+  agent.name :researcher
+  # ...
+  agent.output_key :research_summary # Result will be saved to state key :research_summary
+end
+```
+
+When this agent finishes execution, its result is saved to the session state under `:research_summary`.
+
+## Accessing State
+
+### In Other Agents
+Subsequent agents in a workflow (e.g., in a `SequentialAgent`) can access this state. The Legate automatically injects relevant state information or allows agents to query it.
+
+### In Tools
+Tools can access the session state via the `Legate::ToolContext`.
+
+```ruby
+def perform_execution(params, context)
+  # Read from state
+  previous_result = context.state_get(:research_summary)
+  
+  # Write to state (pending until tool completion)
+  context.state_set(:new_data, "value")
+  
+  # ...
+end
+```
+
+## Session Service
+
+The `Legate::SessionService` (e.g., `InMemory`) handles the actual storage and retrieval of state within the current process.