legate 0.1.0

data/public/docs/cli/legate_cli_usage.md

@@ -0,0 +1,363 @@
+# Legate Command-Line Interface (CLI)
+
+This document describes the `legate` command-line interface, a tool provided for managing Legate agents, definitions, and running related processes.
+
+## 1. Installation & Setup
+
+The `legate` CLI is typically made available when you install the `legate` gem or include it in your project's Gemfile and run `bundle install`.
+
+Ensure your environment is set up correctly (e.g., Ruby version, Bundler, necessary environment variables like `GOOGLE_API_KEY`).
+
+## 2. Basic Usage
+
+You invoke the CLI using the `legate` command, followed by a subcommand and its specific options.
+
+```bash
+legate <subcommand> [options]
+```
+
+Use `legate help` or `legate <subcommand> --help` to see available commands and their options.
+
+## 3. Core Commands
+
+### 3.1. Agent Management (`legate agent`)
+
+This subcommand group deals with managing agent definitions stored in the `GlobalDefinitionRegistry` (in-memory).
+
+*   **`legate agent save NAME [options]`**: Creates or updates an agent definition in the store.
+    *   **Required Argument:**
+        *   `NAME`: The unique name for the agent.
+    *   **Required Options:**
+        *   `--description "Agent description"`: Set the agent's description.
+    *   **Common Options:**
+        *   `--instruction "Agent instructions..."`: Set the core instructions/system prompt.
+        *   `--tools` / `-t` `tool1,tool2,tool3`: Comma-separated list of tool names (must be registered globally) to associate with the agent.
+        *   `--model "model-name"`: Specify the LLM to use (e.g., `gemini-3.5-flash`).
+        *   `--webhook-enabled`: Flag to enable this agent for inbound webhooks.
+        *   `--webhook-secret "your-secret"`: Set the secret for webhook validation.
+        *   `--mcp-servers-json '[{"type":"stdio", ...}]'`: JSON string defining MCP servers to connect to.
+    *   **Example:**
+        ```bash
+        legate agent save my_calculator --description "A simple calculator agent" --instruction "Use the calculator tool." --tools calculator --model gemini-pro
+        ```
+
+*   **`legate agent list`**: Lists all agent definitions found in the store.
+    *   **Options:**
+        *   `--json`: Output result in JSON format.
+    *   **Example Output:**
+        ```
+        Defined Agents:
+        - my_calculator: A simple calculator agent (Model: gemini-pro, Tools: calculator)
+        ```
+
+*   **`legate agent generate NAME [options]`**: Generates a new agent definition Ruby file from a template.
+    *   **Options:**
+        *   `--description "Agent description"`: Agent description (default: "A new Legate agent.").
+        *   `--instruction "Agent instruction"`: Agent instruction/system prompt (default: "You are a helpful assistant.").
+        *   `--tools` / `-t` `tool1,tool2`: Comma-separated list of tool names.
+        *   `--model "model-name"`: LLM model name.
+        *   `--dir "./agents"`: Directory to save the agent definition file (default: `./agents`).
+        *   `--force`: Overwrite existing file without prompting.
+        *   `--webhook-enabled`: Include webhook configuration placeholders.
+    *   **Example:** `legate agent generate my_calculator --description "A calculator" --tools calculator`
+
+*   **`legate agent delete NAME`**: Deletes an agent definition from the store. Prompts for confirmation.
+    *   **Example:** `legate agent delete my_calculator`
+
+*   **`legate agent stop \u003cagent_name\u003e [options]`**: Stops a persistent agent by marking it as 'stopped' in the definition store.
+    *   **Options:**
+        *   `--force`: Skip confirmation prompt
+        *   `--quiet` / `-q`: Suppress status messages, only output result.
+        *   `--json`: Output result in JSON format (implies --quiet).
+    *   **Notes:**
+        *   If the agent is running in a web server, it will stop on the next status check or server restart.
+        *   Useful for remotely stopping agents without accessing the web UI.
+    *   **Example:** `legate agent stop my_calculator --force`
+
+*   **`legate agent start NAME [options]`**: Verifies agent definition loading and starts the agent runtime (ephemeral diagnostic). Loads the definition, instantiates the agent, starts and stops the runtime, prints details, and exits.
+    *   **Options:**
+        *   `--quiet` / `-q`: Suppress status messages, only output result.
+        *   `--json`: Output result in JSON format (implies --quiet).
+    *   **Example:** `legate agent start my_calculator --json`
+
+*   **`legate agent status \u003cagent_name\u003e [options]`**: Checks the current status of an agent.
+    *   **Options:**
+        *   `--json`: Output result in JSON format.
+    *   **Example:** `legate agent status my_calculator --json`
+    *   **JSON Output Format:**
+        ```json
+        {
+          "agent": "my_calculator",
+          "status": "running",
+          "model": "gemini-2.0-flash",
+          "tools": ["calculator"]
+        }
+        ```
+
+*   **`legate agent ai_generate [options]`**: Uses AI (Gemini LLM) to generate production-ready agent definition code from a natural language description.
+    *   **Input Options (one required):**
+        *   `--description` / `-d`: Inline description
+        *   `--prompt-file` / `-f`: Read description from a file
+        *   **stdin**: Pipe description via stdin (auto-outputs to stdout)
+    *   **Output Options:**
+        *   `--output` / `-o`: Custom output file path (default: `./<suggested_name>_agent.rb`)
+        *   `--stdout`: Force output to stdout instead of file
+        *   `--force`: Overwrite existing file without prompting
+    *   **Environment:** Requires `GOOGLE_API_KEY` to be set
+    *   **Examples:**
+        ```bash
+        legate agent ai_generate -d "An agent that helps with customer support"
+        legate agent ai_generate -f prompt.txt -o ./agents/support_agent.rb
+        echo "A calculator agent" | legate agent ai_generate > calc_agent.rb
+        ```
+
+*   **`legate agent export <agent_name> [options]`**: Exports an agent definition to YAML or JSON.
+    *   **Options:**
+        *   `--format`: Output format, either `yaml` (default) or `json`.
+        *   `--output` / `-o`: Output file path. If omitted, prints to stdout.
+    *   **Example:** `legate agent export my_calculator --format=json --output=my_calculator.json`
+
+*   **`legate agent execute <agent_name> <task> [options]`**: Executes a single task with an agent and exits.
+    *   **Required Arguments:**
+        *   `<agent_name>`: Name of the agent to execute.
+        *   `<task>`: The task/prompt to execute.
+    *   **Options:**
+        *   `--session-id=<id>`: Continue an existing session.
+        *   `--user-id=<id>`: Associate session with a user ID for tracking and resumption.
+        *   `--quiet` / `-q`: Suppress status messages, only output result.
+        *   `--json`: Output result in JSON format (implies --quiet).
+    *   **Examples:**
+        ```bash
+        # Normal execution with verbose status
+        legate agent execute my_calculator "What is 5 + 3?"
+        
+        # Quiet mode - only show result
+        legate agent execute my_calculator "What is 5 + 3?" --quiet
+        
+        # JSON output for scripting/automation
+        legate agent execute my_calculator "What is 5 + 3?" --json
+        ```
+    *   **JSON Output Format:**
+        ```json
+        {
+          "session_id": "uuid-here",
+          "agent": "my_calculator",
+          "result": {
+            "role": "agent",
+            "content": {"status": "success", "result": "8"},
+            "timestamp": "2025-12-16 00:00:00 UTC"
+          }
+        }
+        ```
+
+### 3.2. Web Server (`legate web`)
+
+This subcommand group manages the built-in development web server, which includes the Web UI and potentially the Webhook Listener.
+
+*   **`legate web start [options]`**: Starts the Legate development web server (using Puma by default).
+    *   **Options:**
+        *   `--port <port>`: Specify the port number (default: `4567`).
+        *   `--host <address>`: Specify the address to bind to (default: `localhost`). Use `0.0.0.0` to listen on all interfaces.
+        *   `--no-autoload`: Disable auto-loading of custom tools and agents.
+    *   **Webhook Listener:** If `Legate.configure { |c| c.webhooks.listener_enabled = true }` is set in your configuration, this command will *also* typically start the webhook listener application, either mounted within the main web app or alongside it, according to the Legate's internal setup.
+    *   **Example:** `legate web start --port 3000 --host 0.0.0.0`
+
+### 3.3. Tool Management (`legate tool`)
+
+*   **`legate tool list`**: Lists all tools currently registered in the `Legate::GlobalToolManager`. Useful for seeing which tools are available to be added to agent definitions.
+    *   **Options:**
+        *   `--json`: Output result in JSON format.
+    *   **Example Output:**
+        ```
+        Available tools:
+        - calculator: Performs basic arithmetic operations.
+        - echo: Echoes back the input message.
+        - webhook: Sends an outbound HTTP POST request (webhook).
+        ```
+
+*   **`legate tool info NAME`**: Shows detailed information about a specific tool, including its description and parameter definitions (names, types, required/optional status).
+    *   **Example:** `legate tool info calculator`
+
+*   **`legate tool ai_generate [options]`**: Uses AI (Gemini LLM) to generate production-ready tool class code from a natural language description. Automatically determines if the tool should be simple, HTTP API, or async.
+    *   **Input Options (one required):**
+        *   `--description` / `-d`: Inline description
+        *   `--prompt-file` / `-f`: Read description from a file
+        *   **stdin**: Pipe description via stdin (auto-outputs to stdout)
+    *   **Output Options:**
+        *   `--output` / `-o`: Custom output file path (default: `./<suggested_name>.rb`)
+        *   `--stdout`: Force output to stdout instead of file
+        *   `--force`: Overwrite existing file without prompting
+    *   **Environment:** Requires `GOOGLE_API_KEY` to be set
+    *   **Examples:**
+        ```bash
+        legate tool ai_generate -d "A tool that converts temperatures"
+        echo "A URL status checker" | legate tool ai_generate > url_checker.rb
+        ```
+
+*   **`legate tool execute <tool_name> [param=value ...] [options]`**: Executes a tool directly with parameters.
+    *   **Options:**
+        *   `--quiet` / `-q`: Suppress status messages, only output result.
+        *   `--json`: Output result in JSON format (implies --quiet).
+    *   **Example:**
+        ```bash
+        legate tool execute calculator operand1=5 operand2=3 operation=add --json
+        ```
+
+### 3.4. Session Management (`legate session`)
+
+*   **`legate session show <session_id>`**: Retrieves and displays the details and event history of a specific session from the configured `SessionService`.
+*   **`legate session list [APP_NAME] [USER_ID]`**: Lists all sessions, optionally filtered by `app_name` and/or `user_id`.
+*   **`legate session delete <session_id>`**: Deletes a specific session.
+
+### 3.5. Authentication (`legate auth`)
+
+Manages authentication schemes, credentials, and URL mappings. These commands interact with the same `Legate::Auth::Manager` used by the web UI.
+
+#### Status
+
+*   **`legate auth status`**: Shows an overview of the authentication system.
+    *   **Example Output:**
+        ```
+        Authentication System Status
+
+          Schemes:     6
+          Credentials: 2
+          Mappings:    1
+
+          Scheme types: api_key, http_bearer, oauth2
+          Credential types: api_key, oauth2
+        ```
+
+#### Scheme Management (`legate auth schemes`)
+
+*   **`legate auth schemes list`**: Lists all registered authentication schemes.
+*   **`legate auth schemes show <name>`**: Shows details for a specific scheme.
+*   **`legate auth schemes create <name> --type=<type> [options]`**: Creates a new scheme.
+    *   **Required Options:**
+        *   `--type`: Scheme type (`api_key`, `http_bearer`, `oauth2`, `oidc`, `service_account`, `google_service_account`)
+    *   **Type-specific Options (OAuth2/OIDC):**
+        *   `--authorization-url`: OAuth2 authorization endpoint
+        *   `--token-url`: OAuth2 token endpoint
+        *   `--userinfo-url`: OIDC userinfo endpoint
+        *   `--scopes`: Space-separated scopes
+        *   `--use-pkce`: Enable PKCE
+    *   **Example:**
+        ```bash
+        legate auth schemes create my_oauth --type=oauth2 \
+          --authorization-url="https://auth.example.com/authorize" \
+          --token-url="https://auth.example.com/token"
+        ```
+*   **`legate auth schemes delete <name> [--force]`**: Deletes a scheme.
+
+#### Credential Management (`legate auth credentials`)
+
+*   **`legate auth credentials list`**: Lists all credentials (sensitive values are masked).
+*   **`legate auth credentials show <name>`**: Shows credential details with masked values.
+*   **`legate auth credentials create <name> --type=<type> [options]`**: Creates a new credential.
+    *   **Required Options:**
+        *   `--type`: Credential type (`api_key`, `http_bearer`, `oauth2`, `oidc`, `service_account`, `google_service_account`, `basic`)
+    *   **Type-specific Options:**
+        *   `--api-key`: API key value (or `ENV:VAR_NAME` for environment variable)
+        *   `--bearer-token`: Bearer token value
+        *   `--client-id`: OAuth2/OIDC client ID
+        *   `--client-secret`: OAuth2/OIDC client secret
+        *   `--service-account-key`: Service account JSON key
+        *   `--service-account-key-file`: Path to service account key file
+        *   `--username`, `--password`: Basic auth credentials
+    *   **Example:**
+        ```bash
+        legate auth credentials create my_api_key --type=api_key --api-key="ENV:MY_API_KEY"
+        ```
+*   **`legate auth credentials delete <name> [--force]`**: Deletes a credential.
+*   **`legate auth credentials test <name> [--url=<url>]`**: Tests a credential's validity.
+
+#### URL Mapping (`legate auth mappings`)
+
+*   **`legate auth mappings list`**: Lists all URL-to-auth mappings.
+*   **`legate auth mappings create --pattern=<pattern> --scheme=<name> --credential=<name> [--regex]`**: Creates a mapping.
+    *   **Required Options:**
+        *   `--pattern`: URL pattern to match
+        *   `--scheme`: Name of the scheme to use
+        *   `--credential`: Name of the credential to use
+    *   **Optional:**
+        *   `--regex`: Treat pattern as a regular expression
+    *   **Example:**
+        ```bash
+        legate auth mappings create \
+          --pattern="https://api.example.com/*" \
+          --scheme=api_key \
+          --credential=my_api_key
+        ```
+*   **`legate auth mappings delete <index>`**: Deletes a mapping by its index.
+
+### 3.6. Deployment (`legate deployment`)
+
+Helps in generating assets for deploying your Legate application.
+
+#### `legate deployment generate [directory]`
+
+Generates deployment assets such as Dockerfiles, `.dockerignore` files, a `config.ru` for Rack applications, and cloud-specific configuration scripts. These assets are placed into a new directory (default name: `deployment`).
+
+**Arguments:**
+
+*   `[directory]` (Optional): The base path where the deployment assets directory will be created. If not specified, it defaults to the current directory (`.`). The actual assets will be placed in a subdirectory named according to the `--name` option.
+
+**Generic Options:**
+
+*   `--cloud <provider>` / `-c <provider>`: **(Required)** Specifies the target cloud provider for which to generate assets.
+    *   Allowed values: `gcp`, `aws`, `azure`, `none`.
+    *   Default: `none` (generates only generic Docker assets).
+*   `--entry-point <path>` / `-e <path>`: The path to your main application entry point script (e.g., `bin/web_server.rb`, `app.rb`, or a `config.ru`). This is required unless `--generate-sample-entrypoint` is used. The generated `config.ru` will reference this script to run your application.
+*   `--agent-entry-points <path1,path2,...>` / `-a <path1,path2,...>`: A comma-separated list of paths to entry point scripts for any standalone agent processes you want to deploy. A separate Dockerfile may be generated for each.
+*   `--name <name>` / `-n <name>`: The base name for the output directory where assets will be generated (e.g., if `my-app-deploy` is given, assets will be in `./my-app-deploy/`). This name may also be used as a prefix for generated cloud resources.
+    *   Default: `deployment`.
+*   `--base-image <image_name:tag>`: The base Ruby Docker image to use for the generated Dockerfile(s) (e.g., `ruby:3.3-slim`).
+    *   Default: `ruby:3.2-slim`.
+*   `--generate-sample-entrypoint`: If set, a sample web entrypoint script (default: `bin/legate_web_entrypoint.rb`) with a basic `/healthz` endpoint and an example `/echo` agent endpoint will be generated. This is useful if your Legate application doesn't have an existing web server entry point.
+    *   Default: `false`.
+
+**GCP Specific Options (applicable if `--cloud gcp` is used):**
+
+*   `--gcp-project-id <id>`: **(Required for GCP)** Your Google Cloud Project ID.
+*   `--gcp-region <region>`: The GCP region where resources will be deployed (e.g., `us-central1`).
+    *   Default: `us-central1`.
+*   `--gcp-service-name <name>`: The name for the main GCP Cloud Run service that will host your application.
+    *   Default: `legate-agent-service`.
+*   `--gcp-memory <size>`: The memory allocation for the main Cloud Run service (e.g., `512Mi`, `1Gi`).
+    *   Default: `512Mi`.
+*   `--gcp-cpu <count>`: The CPU allocation for the main Cloud Run service.
+    *   Default: `1`.
+
+**Example:**
+
+To generate deployment assets for GCP, targeting your project `my-gcp-project-123`, with the main application entry point at `bin/my_app_server.rb`, and outputting to a directory named `my_legate_prod_deployment`:
+
+```bash
+bundle exec legate deployment generate . --cloud gcp \
+  --gcp-project-id "my-gcp-project-123" \
+  --entry-point "bin/my_app_server.rb" \
+  --name "my_legate_prod_deployment" \
+  --gcp-region "us-east1"
+```
+
+This will create a directory `./my_legate_prod_deployment/` containing a `Dockerfile`, `.dockerignore`, `config.ru`, a `deploy-gcp.sh` script, a `cloudbuild.yaml` file, and a `README-GCP-DEPLOYMENT.md` guide.
+
+### 3.7. Help (`legate help`)
+
+*   **`legate help`**: Displays the main help message listing all available subcommands.
+*   **`legate help <subcommand>`**: Displays detailed help for a specific subcommand (e.g., `legate help agent`).
+
+## 4. Configuration
+
+The CLI relies on the same Legate configuration mechanisms as the library itself:
+
+*   It loads the application environment (often via `Bundler.setup` and `Dotenv.load`).
+*   It respects settings configured in `Legate.configure` blocks within your application's initialization code.
+*   It uses environment variables (e.g., `GOOGLE_API_KEY`, `LEGATE_LOG_LEVEL`).
+
+## Further Reading
+
+*   [`legate_configuration`](../core_concepts/legate_configuration)
+*   [`legate_definition_store`](../core_concepts/legate_definition_store)
+*   [`legate_web_ui`](../web_ui/legate_web_ui)
+*   [`legate_tools_and_registry`](../tools/legate_tools_and_registry)

data/public/docs/core_concepts/legate_agent_lifecycle.md

@@ -0,0 +1,124 @@
+# Legate Agent Lifecycle
+
+This document describes the lifecycle of an `Legate::Agent` instance, from its creation and initialization through starting, task execution, and stopping.
+
+## Lifecycle States & Transitions
+
+The following diagram illustrates the primary states of an agent instance and the methods or events that cause transitions between these states:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Initialized : "Legate Agent new"
+    Initialized --> Running : agent.start()
+    Running --> Running : agent.run_task()
+    Running --> Stopped : agent.stop()
+    Stopped --> Running : agent.start()
+    Stopped --> [*]
+    Initialized --> [*]
+
+    note right of Initialized : Agent object exists, planner initialized,
+    note right of Initialized : tool registry created, but not ready for tasks
+    note left of Running : Connected to MCP servers (if any),
+    note left of Running : selected MCP tools registered,
+    note left of Running : ready to execute tasks
+    note right of Stopped : Disconnected from MCP servers,
+    note right of Stopped : runtime resources released (if any)
+```
+
+## Quick path: `Agent#ask`
+
+For the common "just answer this" case you don't need to drive the lifecycle by
+hand. `Agent#ask` lazily starts the agent, creates (or reuses) a session on the
+agent's own session service, runs the task, and returns the final event:
+
+```ruby
+agent = Legate::Agent.new(definition: my_definition)
+
+puts agent.ask('What is 2 + 2?').answer          # => "4"
+agent.ask('Search for ruby') { |event| ... }      # optional block streams progress (see Streaming guide)
+agent.ask('Follow-up', session_id: existing_id)   # continue a conversation
+```
+
+The returned `Legate::Event` exposes `#answer`, `#success?`, `#error?`, and
+`#error_message`, so you rarely reach into `event.content` directly. `ask` does
+**not** auto-stop (stopping tears down MCP connections that are costly to
+re-establish); call `#stop` when done, or let process exit reclaim it.
+
+The phases below describe the explicit lifecycle `ask` automates — reach for them
+when you need fine control (long-lived hosts, custom session management, the
+workflow agent types).
+
+## Lifecycle Phases
+
+### 1. Initialization (`Legate::Agent.new`)
+
+*   **Trigger:** Calling `Legate::Agent.new(definition:, session_service: nil, planner_override: nil, sub_agents: nil)` where `definition` is an instance of `Legate::AgentDefinition`. This definition object would have been created programmatically (e.g., `Legate::AgentDefinition.new.define { ... }`) or loaded and deserialized (e.g., from a store, often involving `Legate::AgentDefinition.from_hash(hash_from_store)` if the store provides hashes). Optional parameters allow injecting a custom `session_service`, a `planner_override`, or pre-initialized `sub_agents`.
+*   **State:** Enters the **Initialized** state.
+*   **Actions:**
+    *   The `Legate::AgentDefinition` object provides all core static properties: `name`, `description`, `instruction`, `tool_names` (symbols of tools to use), `model_name`, `temperature`, `fallback_mode`, `mcp_servers` configuration, `sub_agent_names`, `output_key`, and webhook configurations.
+    *   The agent copies these properties from the provided `definition` object.
+    *   Creates an instance of `Legate::ToolRegistry` specific to this agent instance.
+    *   For each tool name specified in `definition.tool_names`, it resolves the corresponding tool class using `Legate::GlobalToolManager.find_class(tool_name)` and registers this class with the agent's local `ToolRegistry`.
+    *   Initializes the `Legate::Planner` (e.g., `Legate::Planner`), using the agent's effective model name (from definition or default).
+    *   If the `sub_agents:` parameter was provided to `Legate::Agent.new` with pre-initialized sub-agent instances, those are linked. Otherwise, if `definition.sub_agent_names` is populated, it attempts to instantiate these sub-agents by looking up their full `Legate::AgentDefinition` objects in `Legate::GlobalDefinitionRegistry` and then calling `Legate::Agent.new` for each.
+*   **Notes:** At this point, the agent object exists, but it hasn't connected to external systems like MCP servers (that happens in `start`). It cannot execute tasks until started.
+
+### 2. Starting (`agent.start`)
+
+*   **Trigger:** Calling the `start` method on an `Initialized` or `Stopped` agent instance.
+*   **State:** Transitions to the **Running** state.
+*   **Actions:**
+    *   Sets the agent's internal running status flag to `true`.
+    *   Iterates through the configured `mcp_servers` (if any):
+        *   Creates an `Legate::Mcp::Client` for each server.
+        *   Calls `client.connect` to establish the connection (STDIO process or SSE connection) and perform the MCP handshake.
+        *   If successful, calls `client.list_tools` to get available tools from the MCP server.
+        *   Compares the received tool names against the agent's `selected_tool_names`.
+        *   For each matching tool, creates an `Legate::Mcp::ToolWrapper` instance using the schema from the MCP server.
+        *   Registers the `ToolWrapper` instance with the agent's `ToolRegistry`.
+        *   Handles connection or handshake errors gracefully (usually logs an error and proceeds without that MCP server's tools).
+*   **Notes:** The agent is now fully operational and ready to accept tasks via `run_task`. It has registered both its native tools and the selected tools from any successfully connected MCP servers.
+
+### 3. Running Tasks (`agent.run_task`)
+
+*   **Trigger:** Calling the `run_task` method on a `Running` agent instance.
+*   **State:** Remains in the **Running** state, but performs work.
+*   **Actions (Simplified Flow):**
+    1.  **Session Handling:** Loads or creates the relevant session using the provided `session_id` and `session_service`.
+    2.  **Record Input:** Adds the `user_input` as an event to the session history.
+    3.  **Planning:** Calls `planner.plan(user_input, invocation_id)` with the user's input and the invocation ID for callback support.
+    4.  **Plan Execution:** Iterates through the steps returned by the planner.
+        *   For each step (typically a tool call):
+            *   Retrieves the tool instance (native or `ToolWrapper`) from the `ToolRegistry`.
+            *   Creates an `Legate::ToolContext` (containing session info).
+            *   Calls `tool.execute(params, context)`.
+            *   Adds the tool call event and the tool result event to the session history.
+            *   Handles tool errors (`Legate::ToolError`) by catching them, logging, and adding an error event to the history, potentially halting plan execution.
+    5.  **Response Generation:** May consult the LLM one last time to generate a final response based on the completed plan and tool results.
+    6.  **Record Output:** Adds the final agent response event to the session history.
+    7.  **Return:** Returns the final `Legate::Event` (usually the agent response or an error event).
+*   **Notes:** This is the primary work loop of the agent. It involves interaction with the planner, tool registry, session service, and potentially external tools via MCP wrappers.
+
+### 4. Stopping (`agent.stop`)
+
+*   **Trigger:** Calling the `stop` method on a `Running` agent instance.
+*   **State:** Transitions to the **Stopped** state.
+*   **Actions:**
+    *   Sets the agent's internal running status flag to `false`.
+    *   Iterates through any active `Legate::Mcp::Client` instances and calls `client.disconnect`.
+        *   This terminates STDIO processes or closes SSE connections associated with MCP servers.
+    *   Performs any other necessary cleanup (though typically minimal for the base agent).
+*   **Notes:** The agent is no longer ready to run tasks. It needs to be explicitly started again via `agent.start()`.
+
+## Relationship to Agent Definition
+
+The lifecycle described above pertains to an *instance* of `Legate::Agent`. Agent *definitions*, managed by the `DefinitionStore` or created programmatically (e.g. using `Legate::AgentDefinition.new.define`), represent the blueprint used to create these instances. Passing an `Legate::AgentDefinition` object to `Legate::Agent.new` is the first step (Initialization) in this lifecycle.
+
+## Further Reading
+
+*   [`legate_architecture_overview`](./legate_architecture_overview)
+*   [`legate_session_service`](./legate_session_service)
+*   [`legate_planner`](./legate_planner)
+*   [`legate_tools_and_registry`](../tools/legate_tools_and_registry)
+*   [`mcp_client_integration`](../guides/mcp_client_integration)
+*   [`legate_definition_store`](./legate_definition_store)

data/public/docs/core_concepts/legate_architecture_overview.md

@@ -0,0 +1,110 @@
+# Legate Architecture Overview
+
+This document provides a high-level overview of the Legate — AI Agent Framework for Ruby — library, its core components, and how they interact to enable the development and operation of AI agents.
+
+## Core Components Diagram
+
+The following diagram illustrates the main architectural components of the Legate:
+
+```mermaid
+graph TD
+    subgraph UserInteraction ["User Interaction"]
+        CLI[Legate CLI]
+        WebUI[Legate Web UI]
+    end
+
+    subgraph LegateCore ["Legate Core"]
+        Agent["Legate::Agent"]
+        Planner["Legate::Planner"]
+        ToolRegistry["Legate::ToolRegistry"]
+        SessionService["Legate::SessionService"]
+        DefinitionStore["Legate::DefinitionStore"]
+        GlobalToolMgr["Legate::GlobalToolManager"]
+    end
+
+    subgraph ToolsAndExecution ["Tools & Execution"]
+        GenericTool["Legate::Tool"]
+        LLM["Language Model (LLM)"]
+        ExternalServices["External APIs/Services"]
+    end
+
+    UserInteraction -- Manages/Interacts with --> Agent
+    UserInteraction -- Manages/Interacts with --> DefinitionStore
+
+    Agent -- Uses --> Planner
+    Agent -- Uses --> ToolRegistry
+    Agent -- Uses --> SessionService
+    Agent -- Loads Definition from --> DefinitionStore
+
+    Planner -- Uses --> ToolRegistry
+    Planner -- Communicates with --> LLM
+
+    ToolRegistry -- Contains/Manages --> GenericTool
+    ToolRegistry -- Populated by --> GlobalToolMgr
+    GlobalToolMgr -- Discovers --> GenericTool
+
+    Agent -- Executes --> GenericTool
+    GenericTool -- Can call --> ExternalServices
+    GenericTool -- Can interact with --> SessionService
+
+    style Agent fill:#ccf,stroke:#333,stroke-width:2px
+    style Planner fill:#cff,stroke:#333,stroke-width:2px
+    style ToolRegistry fill:#cfc,stroke:#333,stroke-width:2px
+    style GenericTool fill:#cfc,stroke:#333,stroke-width:2px
+    style SessionService fill:#fcc,stroke:#333,stroke-width:2px
+    style DefinitionStore fill:#fcc,stroke:#333,stroke-width:2px
+    style LLM fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+## Component Descriptions
+
+*   **User Interaction (CLI/Web UI):** Interfaces for users to create, manage, and interact with agents and their definitions.
+*   **`Legate::Agent`:** The central orchestrator. It manages the execution of tasks, interacts with the planner, tools, and session service based on its definition.
+*   **`Legate::Planner`:** Responsible for creating a sequence of steps (a plan) for the agent to follow to accomplish a given task. It uses the agent's instructions, available tools, and conversation history, often leveraging an LLM.
+*   **`Legate::ToolRegistry`:** An instance-specific collection of tools available to a particular agent. It provides tool metadata to the planner and tool instances to the agent for execution.
+*   **`Legate::GlobalToolManager`:** A global registry module (with `self.` class methods) where tool classes are registered. The `ToolRegistry` of an agent is typically populated from this manager.
+*   **`Legate::Tool`:** Represents a specific capability or action an agent can perform (e.g., calculator, web search, API call). Tools have defined metadata (name, description, parameters) and an execution method.
+*   **`Legate::SessionService`:** Manages the state of an agent's conversation over time, including history of prompts, tool calls, and responses. Uses in-memory storage via `InMemory`.
+*   **`Legate::DefinitionStore`:** A module namespace for storing and retrieving agent definitions (configurations like name, instructions, tools to use, model, etc.). Definitions are stored in-memory via `Legate::GlobalDefinitionRegistry`.
+*   **Language Model (LLM):** An external AI model (e.g., from OpenAI, Google) that the planner consults to generate plans and that the agent may use to generate final responses.
+*   **External APIs/Services:** Third-party services that `Legate::Tool`s might interact with to perform their actions.
+
+## Basic Workflow
+
+A typical agent task execution involves the following simplified flow:
+
+1.  **User Input:** A user provides a prompt or task to an `Legate::Agent` via a CLI or Web UI, usually associated with a `session_id`.
+2.  **Agent Activation:** The `Legate::Agent` loads its definition and retrieves the session history using the `Legate::SessionService`.
+3.  **Planning:** The agent invokes the `Legate::Planner`. The planner, using the agent's instructions, available tool metadata (from `Legate::ToolRegistry`), and conversation history, consults an LLM to create a plan (a sequence of tool calls).
+4.  **Tool Execution:** The agent iterates through the plan:
+    *   For each step, it retrieves the appropriate `Legate::Tool` from its `ToolRegistry`.
+    *   It executes the tool with the parameters specified in the plan.
+    *   The tool performs its action (potentially calling external APIs) and returns a result.
+    *   The agent records the tool call and its result in the session history via the `Legate::SessionService`.
+5.  **Response Generation:** After plan completion (or if no plan is needed), the agent may use an LLM to generate a final response based on the task and tool results.
+6.  **Output:** The agent returns the final response or result to the user, and this event is also saved to the session history.
+
+## Key Concepts
+
+*   **Agent Definition:** The configuration of an agent, specifying its behavior, instructions, and capabilities (tools, model).
+*   **Session:** A record of an interaction or conversation with an agent over time, identified by a `session_id`. It includes all events like user prompts, tool calls, and agent responses.
+*   **Tool Metadata:** The information that describes a tool to the planner and LLM, including its name, a description of what it does, and the parameters it accepts.
+*   **Plan:** A sequence of steps (primarily tool calls) generated by the planner for the agent to execute to achieve a goal.
+
+## Further Reading
+
+For more detailed information on specific components, refer to:
+
+*   [`legate_agent_lifecycle`](./legate_agent_lifecycle)
+*   [`legate_tools_and_registry`](../tools/legate_tools_and_registry)
+*   [`legate_session_service`](./legate_session_service)
+*   [`legate_planner`](./legate_planner)
+*   [`legate_configuration`](./legate_configuration)
+*   [`legate_definition_store`](./legate_definition_store)
+*   [`legate_cli_usage`](../cli/legate_cli_usage)
+*   [`http_client_usage`](../guides/http_client_usage)
+*   [`mcp_client_integration`](../guides/mcp_client_integration)
+*   [`mcp_server_exposure`](../guides/mcp_server_exposure)
+*   [`configuring_agent_webhooks`](../guides/configuring_agent_webhooks)
+*   [`sending_outbound_webhooks`](../guides/sending_outbound_webhooks)
+*   [`webhooks`](../guides/webhooks)