kagenti · jjeliga · Apr 2, 2026 · Mar 31, 2026 · Apr 1, 2026 · Apr 1, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,6 +7,23 @@ our success.
 
 ## Development Setup
 
+### Agentic Development
+
+For a seamless development experience where an AI coding agent (Claude Code,
+Cursor, etc.) manages the full dev lifecycle — running tests, starting/stopping
+the platform, executing migrations — you'll want to grant it broad permissions
+over Mise tasks. Before doing so, consider running the agent inside a sandbox.
+
+This repo is configured for [locki](https://github.com/JanPokorny/locki) — it
+uses the project's own MicroShift VM image (via `locki.toml`). To start a
+sandboxed Claude Code session:
+
+```sh
+locki claude my-sandbox
+```
+
+Install locki with `mise use -g pipx:locki` or `uv tool install locki`.
+
 ### Installation
 
 This project uses [Mise-en-place](https://mise.jdx.dev/) as a manager of tool versions (`python`, `uv`, `nodejs`, `pnpm`

diff --git a/apps/adk-cli/src/kagenti_cli/commands/connector.py b/apps/adk-cli/src/kagenti_cli/commands/connector.py
@@ -248,7 +248,7 @@ async def disconnect(
     ] = "",
     yes: typing.Annotated[bool, typer.Option("--yes", "-y", help="Skip confirmation prompts.")] = False,
     all: typing.Annotated[
-        bool, typer.Option("--all", "-a", help="Deisconnect all connectors without selection.")
+        bool, typer.Option("--all", "-a", help="Disconnect all connectors without selection.")
     ] = False,
 ) -> None:
     """Disconnect one or more connectors."""

diff --git a/apps/adk-cli/src/kagenti_cli/commands/platform.py b/apps/adk-cli/src/kagenti_cli/commands/platform.py
@@ -240,6 +240,7 @@ async def start_cmd(
             "--set",
             help="Set Helm chart values. Prefix with chart name: --set kagenti:key=val, --set kagenti-deps:key=val. Unprefixed applies to kagenti-adk.",
             default_factory=list,
+            show_default=False,
         ),
     ],
     image_pull_mode: typing.Annotated[

diff --git a/docs/development/agent-integration/env-variables.mdx b/docs/development/agent-integration/env-variables.mdx
@@ -70,12 +70,8 @@ Import the necessary components from the Kagenti ADK.
 Add an `EnvVar` list to the `variables` field in your `AgentDetail` configuration.
 </Step>
 
-<Step title="Deploy your agent to the Kagenti ADK">
-Use `kagenti-adk add` command to [deploy your agent in Kagenti ADK](../deploy-agents/deploy-your-agents)
-</Step>
-
-<Step title="Configure the variables via CLI">
-Configure environment variables for your agent using `kagenti-adk env add "Name or ID of your Agent" KEY=VALUE`.
+<Step title="Deploy your agent and pass the variables">
+Pass environment variables when deploying your agent using `kagenti-adk add --env KEY=VALUE` or via an env file with `--env-file .env`. See [Deploy Your Agents](../deploy-agents/deploy-your-agents) for details.
 </Step>
 
 
@@ -84,38 +80,26 @@ Use `os.getenv()` to access the environment variables in your agent code.
 </Step>
 </Steps>
 
-## Managing Environment Variables
+## Providing Environment Variables
 
-Once your agent is deployed to Kagenti ADK, you need to provide the environment variables it requires. You can manage these variables using the `kagenti-adk env` CLI commands.
+When deploying your agent to Kagenti ADK, you supply environment variables at the time of deployment using the `--env` flag on `kagenti-adk add`. You can pass multiple variables and also load them from a file.
 
-### Adding Environment Variables
+### Adding Environment Variables at Deploy Time
 
-To provide environment variables to your agent, use the `kagenti-adk env add` command:
+Use one or more `--env KEY=VALUE` flags when adding your agent:
 
 ```bash
-kagenti-adk env add "Name or ID of the agent" FIRST_VAR=VALUE SECOND_VAR=VALUE ...
+# Pass individual variables
+kagenti-adk add <image> --env FIRST_VAR=VALUE --env SECOND_VAR=VALUE
+
+# Or use an env file (KEY=VALUE per line)
+kagenti-adk add <image> --env-file path/to/.env
 ```
 
 <Tip>
-You can add multiple variables at once by including them all in a single command.
+You can combine `--env` and `--env-file`. Individual `--env` entries take precedence over the file.
 </Tip>
 
-### Listing Environment Variables
-
-To view the environment variables configured for an agent:
-
-```bash
-kagenti-adk env list "Name or ID of the agent"
-```
-
-### Removing Environment Variables
-
-To remove an environment variable from an agent:
-
-```bash
-kagenti-adk env remove "Name or ID of the agent" VARIABLE_NAME
-```
-
 ### Checking Missing Variables
 
-When a required variable hasn't been provided, you can see this in the agent list. Use `kagenti-adk list` to view all agents - the `INFO` column shows which variables still need to be configured.
+If a required variable is missing, your agent will likely fail to start. Run `kagenti-adk list` — an agent in `error` state will show the error message in the `Info` column, which may indicate the missing variable.
diff --git a/docs/development/agent-integration/observability.mdx b/docs/development/agent-integration/observability.mdx
@@ -3,41 +3,39 @@ title: Monitoring & Observability
 description: Monitor traces, logs, and metrics from your agents and platform
 ---
 
-Kagenti ADK provides built-in observability through [OpenTelemetry (OTLP)](https://opentelemetry.io/). This allows you to monitor agent health, performance metrics, and execution traces in real-time. By default, the stack integrates with [Arize Phoenix](https://docs.arize.com/phoenix) for local visualization, but it can be routed to any OTLP-compliant backend.
+Kagenti ADK provides built-in observability through [OpenTelemetry (OTLP)](https://opentelemetry.io/). This allows you to monitor agent health, performance metrics, and execution traces in real-time. The stack can integrate with [Arize Phoenix](https://docs.arize.com/phoenix) for local visualization or be routed to any OTLP-compliant backend such as [Langfuse](https://langfuse.com/).
 
 
 ```mermaid
 graph LR
     %% Sources
-    Kagenti ADK[Kagenti ADK Server] 
+    Kagenti ADK[Kagenti ADK Server]
     Agent[Agent Providers]
-    
+
     %% Collector
     OTLP[OpenTelemetry<br/>Collector<br/>:4318]
-    
+
     %% Destinations
-    Phoenix[Phoenix<br/>:6006<br/>✓ Built-in]
-    Langfuse[Langfuse<br/>Cloud<br/>⚙ Config Required]
-    Custom[Custom<br/>Backend<br/>⚙ Config Required]
-    
+    Phoenix[Phoenix<br/>:6006<br/>⚙ Opt-in]
+    Langfuse[Langfuse<br/>Cloud<br/>⚙ Opt-in]
+    Custom[Custom<br/>Backend<br/>⚙ Opt-in]
+
     %% Data flows
     Kagenti ADK -->|traces/metrics| OTLP
     Agent -->|traces/metrics| OTLP
-    
+
     OTLP --> Phoenix
     OTLP --> Langfuse
     OTLP --> Custom
-    
+
     %% Simple styling
     classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px,color:#000
     classDef collector fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000
-    classDef builtin fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#000
     classDef optional fill:#fff3e0,stroke:#f57c00,stroke-width:2px,stroke-dasharray: 5 5,color:#000
 
-    
+
     class OTLP collector
-    class Phoenix builtin
-    class Langfuse,Custom optional
+    class Phoenix,Langfuse,Custom optional
 ```
 
 For telemetry to flow successfully, it must be enabled at three levels:
@@ -47,17 +45,17 @@ For telemetry to flow successfully, it must be enabled at three levels:
    </Step>
 
    <Step title="The Python SDK">
-  The server must be configured to export that data by setting `configure_telemetry=True`.
+  The server must be configured to export telemetry data by setting `configure_telemetry=True`.
    </Step>
 
    <Step title="The Kagenti ADK Platform">
-  The infrastructure must be running a collector and a backend (like Arize Phoenix) to receive and display the data.
+  The infrastructure must be running a collector and a backend (like Arize Phoenix or Langfuse) to receive and display the data. The OTel collector and Phoenix are disabled by default and must be explicitly enabled.
    </Step>
 
 </Steps>
 
 ## Agent SDK Configuration
-Before configuring an observability platform, your agent code must be "telemetry-aware." This configuration applies to all implementations, whether you are using local Phoenix or a cloud provider like Langfuse.
+Before configuring an observability platform, your agent code must be "telemetry-aware." This configuration applies to all backends, whether you are using local Phoenix or a cloud provider like Langfuse.
 
 You must initialize instrumentation at the agent logic level and enable the export flag in the Kagenti ADK:
 
@@ -72,38 +70,22 @@ from kagenti_adk.server import Server
 server = Server()
 
 @server.agent()
-async def my_agent(): 
+async def my_agent():
     ...
 
 # 2. SDK Level: Enable the bridge to the platform collector
 server.run(configure_telemetry=True)
 ```
 
+By default, the SDK sends telemetry to `http://otel-collector.localtest.me:8080`. You can override this by setting the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable.
+
 <Tip>
   For an enhanced user experience and richer trace detail, consider instrumenting agents using the [OpenInference](https://github.com/Arize-ai/openinference/) standard for custom instrumentation.
 </Tip>
 
-## Simple Monitoring: Agent Logs
-
-The quickest way to see what your agent is doing is by streaming its logs directly to your terminal. This is ideal for debugging container lifecycle events and immediate request errors.
-
-```bash
-kagenti-adk logs
-```
-
-What you'll see:
-- Agent startup and initialization
-- Request processing steps
-- Error messages and stack traces
-- Container lifecycle events
-
-<Note>
-  Logs are only available for managed (containerized) agents that are currently running on Kagenti ADK.
-</Note>
-
 ## Advanced Observability: Traces & Metrics
 
-By default, Kagenti ADK integrates with [Arize Phoenix](https://phoenix.arize.com/) for local visualization of agent traces. For cloud-based observability and production monitoring, you can easily integrate [Langfuse](https://langfuse.com/).
+The OTel collector and Phoenix are **disabled by default** in the Kagenti ADK platform. You can enable them to visualize agent traces locally, or route telemetry to a cloud provider like [Langfuse](https://langfuse.com/).
 
 Telemetry details include:
 - Platform version and runtime details
@@ -116,43 +98,39 @@ Telemetry details include:
   </Warning>
 
 <Steps>
-   <Step title="Install and Enable">
+   <Step title="Enable OTel and Phoenix">
 
-Phoenix is included by default as part of the kagenti observability stack (OTel collector + Phoenix). Simply start the platform:
+Start the platform with the OTel collector and Phoenix enabled:
 ```sh
-kagenti-adk platform start
+kagenti-adk platform start --set kagenti-deps:components.otel.enabled=true
 ```
 
-To disable Phoenix and the OTel collector, pass:
+To disable them again later, omit the flag or pass:
 ```sh
 kagenti-adk platform start --set kagenti-deps:components.otel.enabled=false
 ```
 
   </Step>
 
-  <Step title="Verify Initialization">
-Spinning up the Phoenix container can take a moment, even after the CLI reports success. Go to [http://phoenix.localtest.me:8080](http://phoenix.localtest.me:8080) and check if it's running. If not, please wait a few moments.
+   <Step title="Run an Agent">
 
-   </Step>
-
-   <Step title="Run and View">
-
-Execute an agent to generate data:
+Execute an agent to generate telemetry data:
 ```sh
-kagenti-adk run chat "Hello"
+kagenti-adk run <agent-name> "Hello"
 ```
 
    </Step>
    <Step title="View Traces in Phoenix">
 
-Open [http://localhost:6006](http://localhost:6006) in your browser and navigate to the **default** project to explore the collected traces.
+Open [http://phoenix.localtest.me:8080](http://phoenix.localtest.me:8080) in your browser and navigate to the **default** project to explore the collected traces.
 
    </Step>
 </Steps>
 
 
 ### Enable Langfuse Observability
-To route traces to Langfuse, provide a custom OTLP configuration:
+
+To route traces to [Langfuse](https://langfuse.com/), you need to enable the OTel collector and provide Langfuse-specific configuration via a values file.
 
 <Steps>
 
@@ -162,33 +140,34 @@ To route traces to Langfuse, provide a custom OTLP configuration:
 3. Encode your keys: `echo -n "public_key:secret_key" | base64`
 </Step>
 
-<Step title="Create a configuration file (config.yaml):">
+<Step title="Create a values file">
+Create a `values.yaml` with chart-scoped sections to enable the OTel collector and configure the Langfuse exporter:
+
 ```yaml
-collector:
-  exporters:
-    otlphttp/langfuse:
-      endpoint: "https://cloud.langfuse.com/api/public/otel" # EU data region
-      headers:
-        Authorization: "Basic <auth-string>"
-  pipelines:
-    traces:
-      receivers: [ otlp ]
-      processors: [ memory_limiter, filter/phoenix, batch ]
-      exporters: [ otlphttp/langfuse ]
+kagenti-deps:
+  components:
+    otel:
+      enabled: true
+  # Consult the kagenti-deps chart documentation for available
+  # OTel collector configuration options to route traces to Langfuse.
 ```
+
+<Tip>
+  The OTel collector configuration (exporters, processors, pipelines) is managed by the `kagenti-deps` Helm chart. Refer to its documentation for the full list of available configuration options.
+</Tip>
 </Step>
 
 <Step title="Start the platform with the configuration">
 ```bash
-kagenti-adk platform start -f config.yaml
+kagenti-adk platform start -f values.yaml
 ```
 </Step>
 
 <Step title="Run and View">
 
 Execute an agent to generate data:
 ```sh
-kagenti-adk run chat "Hello"
+kagenti-adk run <agent-name> "Hello"
 ```
 Check your Langfuse project dashboard for incoming traces and metrics.
 </Step>
@@ -200,5 +179,3 @@ Check your Langfuse project dashboard for incoming traces and metrics.
 - **OpenTelemetry Docs**: https://opentelemetry.io/docs/
 - **Langfuse Docs**: https://langfuse.com/docs
 - **Phoenix Docs**: https://docs.arize.com/phoenix
-- **Prometheus Docs**: https://prometheus.io/docs/
-- **Grafana Docs**: https://grafana.com/docs/
diff --git a/docs/development/agent-integration/rag.mdx b/docs/development/agent-integration/rag.mdx
@@ -123,7 +123,7 @@ from kagenti_adk.a2a.extensions import (
 )
 from kagenti_adk.a2a.types import AgentMessage
 from kagenti_adk.server.context import RunContext
-from kagenti_adk.util.file import PlatformFileUrl
+from kagenti_adk.platform import PlatformFileUrl
 
 # File formats supported by the text-extraction service (docling)
 default_input_modes = [

diff --git a/docs/development/community/contribute.mdx b/docs/development/community/contribute.mdx
@@ -35,12 +35,12 @@ You don’t need to be an AI expert to help. Here’s how you can make impact to
 Not sure where to begin?
 - Start with our [Contributing Guide](https://github.com/kagenti/adk/blob/main/CONTRIBUTING.md)
 - Browse [Good first issues](https://github.com/kagenti/adk/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) to find approachable tasks to get your feet wet
-- Join the conversation on [Discord](https://discord.gg/NradeA6ZNF) - questions, ideas, and curiosity welcome
+- Join the conversation on [Discord](https://discord.gg/aJ92dNDzqB) - questions, ideas, and curiosity welcome
 
 Don't hesitate to reach out - we’re here to help you get started.
 
 ## Thanks for Being Here
 
 We’re grateful for your time, your ideas, and your effort to help make Kagenti ADK better.
 
-If you get stuck, feel free to [open an issue](https://github.com/kagenti/adk/issues) or reach out to the team on [Discord](https://discord.gg/NradeA6ZNF)!
+If you get stuck, feel free to [open an issue](https://github.com/kagenti/adk/issues) or reach out to the team on [Discord](https://discord.gg/aJ92dNDzqB)!
diff --git a/docs/development/custom-ui/a2a-client.mdx b/docs/development/custom-ui/a2a-client.mdx
@@ -11,7 +11,7 @@ If you only need the fast path, start with **[Getting Started](./getting-started
 
 - **Packages installed**: `@kagenti/adk` and `@a2a-js/sdk`
 - **Platform base URL** and **provider ID**
-- **CORS enabled on the server** for your frontend origin when running in a browser (or use a same-origin proxy). See **[Cross-Origin Resource Sharing Configuration](../deploy-agent-stack/deployment-guide#cross-origin-resource-sharing-configuration)**.
+- **CORS enabled on the server** for your frontend origin when running in a browser (or use a same-origin proxy). See **[Cross-Origin Resource Sharing Configuration](../deploy-adk/deployment-guide#cross-origin-resource-sharing-configuration)**.
 - **User access token** (for platform API calls)
 - **Context token** (for A2A requests)
 
@@ -65,6 +65,12 @@ const agentMetadata = await resolveMetadata(fulfillments);
 
 See **[Agent Requirements](./agent-requirements)** for the available service and UI extension helpers.
 
+<Warning>
+  **State value compatibility**
+
+  The Kagenti ADK SDK uses uppercase state constants (e.g., `TASK_STATE_AUTH_REQUIRED`, `TASK_STATE_INPUT_REQUIRED`) internally, while `@a2a-js/sdk` emits lowercase states (e.g., `auth-required`, `input-required`). The `handleTaskStatusUpdate` helper handles this mapping for you, but if you write custom state checks, use the lowercase values from `@a2a-js/sdk` events directly.
+</Warning>
+
 ### 2. Send the initial message stream
 
 Start a task by sending the user prompt that triggers the project brief flow.

diff --git a/docs/development/custom-ui/getting-started.mdx b/docs/development/custom-ui/getting-started.mdx
@@ -39,7 +39,7 @@ Use the user access token from your identity provider (OIDC/OAuth) for UI side A
 <Note>
   **Browser clients require CORS**
 
-  If your custom UI runs on a different origin than your Kagenti ADK server, enable CORS on the server for your frontend origin. See **[Cross-Origin Resource Sharing Configuration](../deploy-agent-stack/deployment-guide#cross-origin-resource-sharing-configuration)**.
+  If your custom UI runs on a different origin than your Kagenti ADK server, enable CORS on the server for your frontend origin. See **[Cross-Origin Resource Sharing Configuration](../deploy-adk/deployment-guide#cross-origin-resource-sharing-configuration)**.
   If allowing origins directly is not possible, route calls through a same-origin frontend proxy.
 </Note>
 
@@ -172,6 +172,7 @@ The SDK is split into focused entrypoints:
 2. `@kagenti/adk/api` for platform API client, schemas, and types
 3. `@kagenti/adk/core` for extension helpers and A2A interaction utilities
 4. `@kagenti/adk/extensions` for A2A extension definitions and types
+5. `@kagenti/adk/experimental/server` for experimental server-side features
 
 ## Protocol Types and Schemas