agentkernel 0.9.4__tar.gz → 0.10.0__tar.gz

agentkernel-0.9.4/README.md → agentkernel-0.10.0/PKG-INFO

@@ -1,3 +1,160 @@
+Metadata-Version: 2.3
+Name: agentkernel
+Version: 0.10.0
+Summary: Agent Kernel - Unified AI Agents Runtime
+Author: Yaala Labs
+Author-email: Yaala Labs <agentkernel@yaalalabs.com>
+License: Apache-2.0
+Requires-Dist: pydantic>=2.11.7,<3.0.0
+Requires-Dist: pydantic-settings>=2.10.1,<3.0.0
+Requires-Dist: pyyaml>=6.0.2,<7.0.0
+Requires-Dist: singleton-type>=0.0.5,<0.1.0
+Requires-Dist: a2a-sdk[http-server]==1.2.3 ; extra == 'a2a'
+Requires-Dist: fastapi>=0.118.0,<0.142.0 ; extra == 'a2a'
+Requires-Dist: uvicorn>=0.37.0,<0.53.0 ; extra == 'a2a'
+Requires-Dist: google-adk>=2.7.0,<3.0.0 ; extra == 'adk'
+Requires-Dist: litellm>=1.95.0,<1.96 ; extra == 'adk'
+Requires-Dist: openinference-instrumentation-google-adk>=0.1.6,<0.2.0 ; extra == 'adk'
+Requires-Dist: ag-ui-protocol>=0.1.16,<0.2.0 ; extra == 'agui'
+Requires-Dist: fastapi>=0.118.0,<0.142.0 ; extra == 'api'
+Requires-Dist: uvicorn>=0.37.0,<0.53.0 ; extra == 'api'
+Requires-Dist: gunicorn>=23.0.0,<27.0.0 ; extra == 'api'
+Requires-Dist: httpx>=0.27.0,<0.29.0 ; extra == 'api'
+Requires-Dist: pyjwt>=2.15.0,<3.0.0 ; extra == 'auth'
+Requires-Dist: cryptography>=42.0,<51.0.0 ; extra == 'auth'
+Requires-Dist: httpx>=0.27.0,<0.29.0 ; extra == 'auth'
+Requires-Dist: boto3>=1.41.4,<2.0.0 ; extra == 'aws'
+Requires-Dist: azure-functions>=1.24.0,<3.0.0 ; extra == 'azure'
+Requires-Dist: azure-data-tables>=12.4.0,<13.0.0 ; extra == 'azure'
+Requires-Dist: azure-core>=1.26.0,<2.0.0 ; extra == 'azure'
+Requires-Dist: chromadb>=0.4.0,<2.0.0 ; extra == 'chromadb'
+Requires-Dist: claude-agent-sdk>=0.2.165,<0.3 ; extra == 'claude'
+Requires-Dist: openinference-instrumentation-claude-agent-sdk>=0.1.20,<0.2.0 ; extra == 'claude'
+Requires-Dist: opentelemetry-sdk>=1.30.0,<2.0.0 ; extra == 'cloudwatch'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30.0,<2.0.0 ; extra == 'cloudwatch'
+Requires-Dist: botocore>=1.41.4,<2.0.0 ; extra == 'cloudwatch'
+Requires-Dist: requests>=2.32.0,<3.0.0 ; extra == 'cloudwatch'
+Requires-Dist: crewai>=1.15.0,<2.0.0 ; extra == 'crewai'
+Requires-Dist: openinference-instrumentation-crewai>=0.1.16,<2.0.0 ; extra == 'crewai'
+Requires-Dist: openinference-instrumentation-litellm>=0.1.28,<0.2.0 ; extra == 'crewai'
+Requires-Dist: croniter>=3.0,<7.0.0 ; extra == 'cron'
+Requires-Dist: daytona>=0.198.0,<0.199 ; extra == 'daytona'
+Requires-Dist: e2b-code-interpreter>=2.8.0,<3.0.0 ; extra == 'e2b'
+Requires-Dist: google-cloud-firestore>=2.19.0,<3.0.0 ; extra == 'gcp'
+Requires-Dist: google-auth>=2.0.0,<3.0.0 ; extra == 'gmail'
+Requires-Dist: google-auth-oauthlib>=1.0.0,<2.0.0 ; extra == 'gmail'
+Requires-Dist: google-auth-httplib2>=0.2.0,<0.5.0 ; extra == 'gmail'
+Requires-Dist: google-api-python-client>=2.0.0,<3.0.0 ; extra == 'gmail'
+Requires-Dist: httpx>=0.27.0,<0.29.0 ; extra == 'instagram'
+Requires-Dist: fastapi>=0.118.0,<0.142.0 ; extra == 'instagram'
+Requires-Dist: typesafe-sdk>=0.7.2,<0.8 ; extra == 'jev'
+Requires-Dist: confluent-kafka>=2.15.0,<3.0.0 ; extra == 'kafka'
+Requires-Dist: kubernetes>=29.0.0,<37.0.0 ; extra == 'kubernetes'
+Requires-Dist: langfuse>=4.2.0,<5.0.0 ; extra == 'langfuse'
+Requires-Dist: nest-asyncio>=1.6.0,<2.0.0 ; extra == 'langfuse'
+Requires-Dist: langgraph>=1.2.14,<1.3 ; extra == 'langgraph'
+Requires-Dist: langgraph-prebuilt~=1.1.0 ; extra == 'langgraph'
+Requires-Dist: langchain~=1.3.10 ; extra == 'langgraph'
+Requires-Dist: langchain-community~=0.4.1 ; extra == 'langgraph'
+Requires-Dist: litellm>=1.95.0,<1.96 ; extra == 'langgraph'
+Requires-Dist: livekit-api>=0.4.0,<2.0.0 ; extra == 'livekit'
+Requires-Dist: livekit>=0.18.0,<2.0.0 ; extra == 'livekit'
+Requires-Dist: logfire>=4.31.0,<5.0.0 ; extra == 'logfire'
+Requires-Dist: httpx>=0.27.0,<0.29.0 ; extra == 'logfire'
+Requires-Dist: agent-framework-core>=1.20.0,<2 ; extra == 'maf'
+Requires-Dist: fastmcp>=3.4.10,<4.0.0 ; extra == 'mcp'
+Requires-Dist: httpx>=0.27.0,<0.29.0 ; extra == 'messenger'
+Requires-Dist: fastapi>=0.118.0,<0.142.0 ; extra == 'messenger'
+Requires-Dist: litellm>=1.95.0,<2.0.0 ; extra == 'multimodal'
+Requires-Dist: python-multipart>=0.0.12,<0.1.0 ; extra == 'multimodal'
+Requires-Dist: nats-py>=2.15.0,<3.0.0 ; extra == 'nats'
+Requires-Dist: neo4j>=5.0.0,<7.0.0 ; extra == 'neo4j'
+Requires-Dist: openai-agents>=0.20.0,<0.21 ; extra == 'openai'
+Requires-Dist: openinference-instrumentation-openai-agents>=1.4.0,<3.0.0 ; extra == 'openai'
+Requires-Dist: openai-guardrails>=0.2.1,<0.4.0 ; extra == 'openai'
+Requires-Dist: traceloop-sdk>=0.61.0,<0.63.0 ; extra == 'openllmetry'
+Requires-Dist: httpx>=0.27.0,<0.29.0 ; extra == 'openllmetry'
+Requires-Dist: opik>=1.7.0,<3.0.0 ; extra == 'opik'
+Requires-Dist: pydantic-ai-slim~=2.13.0 ; extra == 'pydanticai'
+Requires-Dist: openinference-instrumentation-pydantic-ai>=0.1.17,<0.2.0 ; extra == 'pydanticai'
+Requires-Dist: redis>=7.1.0,<9.0.0 ; extra == 'redis'
+Requires-Dist: docker>=7.0.0,<8.0.0 ; extra == 'sandbox-docker'
+Requires-Dist: slack-bolt==1.22.0 ; extra == 'slack'
+Requires-Dist: httpx>=0.27.0,<0.29.0 ; extra == 'slack'
+Requires-Dist: fastapi>=0.118.0,<0.142.0 ; extra == 'slack'
+Requires-Dist: aiohttp>=3.14.4,<4.0.0 ; extra == 'slack'
+Requires-Dist: smolagents>=1.26.0,<2.0.0 ; extra == 'smolagents'
+Requires-Dist: botbuilder-core>=4.17.0,<5.0.0 ; extra == 'teams'
+Requires-Dist: botbuilder-schema>=4.17.0,<5.0.0 ; extra == 'teams'
+Requires-Dist: aiohttp>=3.14.4,<4.0.0 ; extra == 'teams'
+Requires-Dist: msal>=1.31.1,<2.0.0 ; extra == 'teams'
+Requires-Dist: httpx>=0.27.0,<0.29.0 ; extra == 'teams'
+Requires-Dist: fastapi>=0.118.0,<0.142.0 ; extra == 'teams'
+Requires-Dist: httpx>=0.27.0,<0.29.0 ; extra == 'telegram'
+Requires-Dist: fastapi>=0.118.0,<0.142.0 ; extra == 'telegram'
+Requires-Dist: pytest>=8.4.1,<10.0.0 ; extra == 'test'
+Requires-Dist: pytest-asyncio>=1.2.0,<2.0.0 ; extra == 'test'
+Requires-Dist: pytest-cov>=6.2.1,<8.0.0 ; extra == 'test'
+Requires-Dist: pytest-html>=4.1.1,<5.0.0 ; extra == 'test'
+Requires-Dist: pytest-order>=1.3.0,<2.0.0 ; extra == 'test'
+Requires-Dist: deepeval>=4.1.4,<5.0.0 ; extra == 'test'
+Requires-Dist: litellm>=1.95.0,<2.0.0 ; extra == 'test'
+Requires-Dist: litellm>=1.95.0,<2.0.0 ; extra == 'thread'
+Requires-Dist: trino>=0.337.0,<0.340.0 ; extra == 'trino'
+Requires-Dist: valkey>=6.0.0,<7.0.0 ; extra == 'valkey'
+Requires-Dist: walledai>=4.9.3,<5.0.0 ; extra == 'walledai'
+Requires-Dist: httpx>=0.27.0,<0.29.0 ; extra == 'whatsapp'
+Requires-Dist: fastapi>=0.118.0,<0.142.0 ; extra == 'whatsapp'
+Requires-Python: >=3.12, <3.14
+Provides-Extra: a2a
+Provides-Extra: adk
+Provides-Extra: agui
+Provides-Extra: api
+Provides-Extra: auth
+Provides-Extra: aws
+Provides-Extra: azure
+Provides-Extra: chromadb
+Provides-Extra: claude
+Provides-Extra: cli
+Provides-Extra: cloudwatch
+Provides-Extra: crewai
+Provides-Extra: cron
+Provides-Extra: daytona
+Provides-Extra: e2b
+Provides-Extra: gcp
+Provides-Extra: gmail
+Provides-Extra: instagram
+Provides-Extra: jev
+Provides-Extra: kafka
+Provides-Extra: kubernetes
+Provides-Extra: langfuse
+Provides-Extra: langgraph
+Provides-Extra: livekit
+Provides-Extra: logfire
+Provides-Extra: maf
+Provides-Extra: mcp
+Provides-Extra: messenger
+Provides-Extra: multimodal
+Provides-Extra: nats
+Provides-Extra: neo4j
+Provides-Extra: openai
+Provides-Extra: openllmetry
+Provides-Extra: opik
+Provides-Extra: pydanticai
+Provides-Extra: redis
+Provides-Extra: sandbox-docker
+Provides-Extra: slack
+Provides-Extra: smolagents
+Provides-Extra: teams
+Provides-Extra: telegram
+Provides-Extra: test
+Provides-Extra: thread
+Provides-Extra: trino
+Provides-Extra: valkey
+Provides-Extra: walledai
+Provides-Extra: whatsapp
+Description-Content-Type: text/markdown
+
 # Agent Kernel
 
 [![PyPI version](https://badge.fury.io/py/agentkernel.svg)](https://badge.fury.io/py/agentkernel)
@@ -8,71 +165,75 @@ Agent Kernel is a lightweight **AI agent runtime** and adapter layer for buildin
 ## Features
 
 - **Unified API**: Common abstractions (Agent, Runner, Session, Module, Runtime) across frameworks
-- **Multi-Framework Support**: OpenAI Agents SDK, CrewAI, LangGraph, Google ADK, Smolagents, and Pydantic AI
+- **Multi-Framework Support**: OpenAI Agents SDK, CrewAI, LangGraph, Google ADK, Smolagents, Pydantic AI, Microsoft Agent Framework, and the Claude Agent SDK
 - **Session Management**: Built-in session abstraction with pluggable storage backends
 - **Knowledge Bases**: Unified, capability-declaring `KnowledgeBase` interface with ChromaDB, Neo4j, Starburst/Trino and Open Knowledge Format bundle (local directory or S3) backends via `KnowledgeBuilder`
 - **Sandbox**: Execute agent-generated code and shell commands in an isolated, permission-bounded environment with pluggable providers (`local_subprocess`, `docker`, `kubernetes`, `e2b`, `daytona`, `ec2_ssm`), workload profiles, policy enforcement, per-user identity, and a queue-decoupled broker for long-running executions
-- **Secret Resolution**: `SecretManager` resolves API keys and passwords environment-first, falling back to a pluggable provider (`env`, `aws_ssm` for AWS SSM Parameter Store, or your own) with a TTL'd process cache
+- **Identity and Access**: One configured identity provider (any OIDC issuer such as Auth0, Keycloak or Okta, Amazon Cognito, Microsoft Entra ID, Firebase, a static credential map, or your own by dotted path) authenticates every surface; tools, hooks, threads and scheduled tasks see the same `Principal`, and a role mapper derives roles from groups and claims
+- **Secret Resolution**: `SecretManager` resolves API keys and passwords environment-first, falling back to a pluggable provider (`env`, `aws_ssm` for AWS SSM Parameter Store, `kubernetes` for Kubernetes Secrets mounted into the pod, or your own) with a TTL'd process cache
 - **Scheduled Tasks**: Deferred and recurring chat execution (`schedule.at`/`schedule.cron`) with a management REST API, five agent-facing tools, and pluggable provider (`local`, `eventbridge`) and store (`in_memory`, `redis`, `valkey`, `dynamodb`) backends
-- **Human in the Loop**: Pause a run for a person's approval or answer and resume from their decision — `status: "PAUSED"` with HTTP 202, a `resume` block carrying `approved`/`denied`/`cancelled` decisions, supported on OpenAI Agents SDK, LangGraph, Pydantic AI and Google ADK over REST, streaming and AG-UI
+- **Human in the Loop**: Pause a run for a person's approval or answer and resume from their decision — `status: "PAUSED"` with HTTP 202, a `resume` block carrying `approved`/`denied`/`cancelled` decisions, supported on OpenAI Agents SDK, LangGraph, Pydantic AI, Google ADK and Microsoft Agent Framework over REST, streaming and AG-UI
 - **Flexible Deployment**: Interactive CLI, REST API, serverless, or containerized deployment — see the "Multi-Cloud Deployment" section below
 - **Pluggable Architecture**: Easy to extend with custom framework adapters
 - **MCP Server**: Built-in Model Context Protocol server for exposing agents as MCP tools and exposing any custom tool
 - **A2A Server**: Built-in Agent-to-Agent communication server for exposing agents with a simple configuration change
 - **AG-UI Server**: Built-in [AG-UI protocol](https://github.com/ag-ui-protocol/ag-ui) handler for driving any streaming-capable agent from an AG-UI frontend, with opt-in shared state and client-context tools
+- **A2UI**: Label a JSON reply as [A2UI](https://a2ui.org/) from two config keys, so a client receives a generative-UI document as an object with its format named rather than a string to parse twice
 - **REST API**: Built-in REST API server for agent interaction
 - **Test Automation**: Built-in test suite for testing agents
 
 ## Installation
 
 ```bash
-pip install agentkernel
+uv init --python 3.12 my-agent
+cd my-agent
+uv add agentkernel
 ```
 
 Install optional knowledge base extras as needed:
 
 ```bash
-pip install "agentkernel[chromadb]"
-pip install "agentkernel[neo4j]"
-pip install "agentkernel[trino]"
+uv add "agentkernel[chromadb]"
+uv add "agentkernel[neo4j]"
+uv add "agentkernel[trino]"
 ```
 
 Open Knowledge Format bundles need no extra - `pyyaml` is a core dependency. Serving a bundle from S3
-uses the `aws` extra: `pip install "agentkernel[aws]"`.
+uses the `aws` extra: `uv add "agentkernel[aws]"`.
 
 For LLM-based thread naming with Conversation Thread Support:
 
 ```bash
-pip install "agentkernel[thread]"
+uv add "agentkernel[thread]"
 ```
 
 For the AG-UI server (`AGUIRequestHandler`):
 
 ```bash
-pip install "agentkernel[agui]"
+uv add "agentkernel[agui]"
 ```
 
 For the sandbox providers (the `local_subprocess` provider needs no extra; `ec2_ssm` rides
 the `aws` extra):
 
 ```bash
-pip install "agentkernel[sandbox-docker]"   # docker provider
-pip install "agentkernel[kubernetes]"       # kubernetes provider (pod per sandbox)
-pip install "agentkernel[e2b]"              # e2b cloud provider
-pip install "agentkernel[daytona]"          # daytona cloud provider
-pip install "agentkernel[aws]"              # ec2_ssm provider (boto3)
+uv add "agentkernel[sandbox-docker]"   # docker provider
+uv add "agentkernel[kubernetes]"       # kubernetes provider (pod per sandbox)
+uv add "agentkernel[e2b]"              # e2b cloud provider
+uv add "agentkernel[daytona]"          # daytona cloud provider
+uv add "agentkernel[aws]"              # ec2_ssm provider (boto3)
 ```
 
 For the `aws_ssm` secret provider (AWS SSM Parameter Store):
 
 ```bash
-pip install "agentkernel[aws]"
+uv add "agentkernel[aws]"
 ```
 
 For cron parsing with the Scheduling capability (the `eventbridge` provider rides the `aws` extra):
 
 ```bash
-pip install "agentkernel[cron]"
+uv add "agentkernel[cron]"
 ```
 
 **Requirements:**
@@ -195,7 +356,7 @@ Agent Kernel includes an interactive CLI for local development and testing.
 **Usage:**
 
 ```bash
-python demo.py
+uv run python demo.py
 ```
 
 Then interact with your agents:
@@ -231,7 +392,7 @@ handler = Lambda.handler
 
 **Note that this is just the simple serverless version. A more advanced serverless deployment mode, which uses queues for scalability, is also available. For queue-backed execution modes and response-store configuration, see the [AWS Serverless Deployment](https://github.com/yaalalabs/agent-kernel/tree/develop/docs/docs/deployment/aws-serverless.md) guide.**
 
-The AWS serverless handler accepts both a direct `BaseRunRequest` payload and the normalized `BaseRequest` envelope. If a flat run payload is provided, Agent Kernel generates a `request_id` and normalizes it before processing. 
+The AWS serverless handler accepts both a direct `BaseRunRequest` payload and the normalized `BaseRequest` envelope. If a flat run payload is provided, Agent Kernel generates a `request_id` and normalizes it before processing. The caller is never named in the payload: the API Gateway authorizer (`handler = APIGatewayAuthorizer().handle`, configured by the `identity` block) establishes the principal and the handler puts it on the request; see [Identity and Access](https://kernel.yaala.ai/docs/advanced/identity-and-access).
 
 Accepted payloads:
 
@@ -246,7 +407,6 @@ Accepted payloads:
 ```json
 {
   "request_id": "req-123",
-  "user_id": "user-123",
   "body": {
     "prompt": "Hello agent",
     "agent": "assistant",
@@ -277,7 +437,6 @@ handler = AzureFunctions.handler
 ```json
 {
   "request_id": "req-123",
-  "user_id": "user-123",
   "body": {
     "prompt": "Hello agent",
     "agent": "assistant",
@@ -394,6 +553,55 @@ Supported formats: `.yaml`, `.yml`, `.json`
 - **Description**: System/root logger level (INFO, DEBUG, ERROR, WARNING, CRITICAL)
 - **Environment Variable**: `AK_LOGGING__SYSTEM__LEVEL`
 
+#### Identity
+
+The `identity` block selects the one identity provider every surface (REST, WebSocket, AG-UI, MCP, A2A,
+the CLI) authenticates through, and the role mapper that derives roles from what it asserts. Without the
+block every request runs as the anonymous principal. The thread, schedule and AG-UI handlers and the
+WebSocket modes refuse to start without it. Full reference: [Identity and Access](https://kernel.yaala.ai/docs/next/advanced/identity-and-access).
+
+Auth0 is an `oidc` configuration: the tenant's issuer with the trailing slash, the API identifier as
+the audience, and the namespaced claim an Auth0 Action sets as the groups path:
+
+```yaml
+identity:
+  provider:
+    type: oidc
+    issuer: https://<tenant>.<region>.auth0.com/   # or the custom domain; trailing slash included, as Auth0 issues it
+    audience: <the API identifier of your Auth0 API>
+    claims:
+      groups: https://<your namespace>/roles       # the namespaced claim an Auth0 Action sets; omit if you set none
+```
+
+- **Field**: `identity.provider.type`
+- **Type**: string
+- **Default**: `oidc`
+- **Description**: `oidc` (any OpenID Connect issuer: Auth0, Keycloak, Okta, ...), `cognito`, `entra`, `firebase`, `static`, or a dotted path to an `IdentityProvider` subclass. `oidc`, `cognito`, `entra` and `firebase` need the `auth` extra (`agentkernel[auth]`).
+- **Environment Variable**: `AK_IDENTITY__PROVIDER__TYPE`
+
+- **Field**: `identity.provider.issuer`, `identity.provider.audience`
+- **Type**: string
+- **Description**: The issuer URL and the audience a token must carry. Both are required by `oidc` (Auth0: `https://<tenant>.<region>.auth0.com/` with the trailing slash, and the API identifier); `cognito` and `entra` take the audience (the app client id, the application id) and derive the issuer; `firebase` derives both.
+- **Environment Variable**: `AK_IDENTITY__PROVIDER__ISSUER`, `AK_IDENTITY__PROVIDER__AUDIENCE`
+
+- **Field**: `identity.provider.jwks_uri`, `identity.provider.algorithms`, `identity.provider.leeway`, `identity.provider.required_claims`
+- **Description**: The JWK set URL (discovered from the issuer when omitted), the allowed signing algorithms (default `[RS256, ES256]`; an empty list, `none`, an unknown name or a symmetric one fails startup), the clock skew in seconds (default `30`) and extra claims a token must carry.
+
+- **Field**: `identity.provider.claims.subject`, `identity.provider.claims.groups`
+- **Type**: string (a claim name, a namespaced name such as `https://acme.com/roles`, or dotted segments such as `realm_access.roles`)
+- **Default**: `sub`, `groups`
+- **Description**: Where the provider reads the subject and the group list.
+
+- **Field**: `identity.provider.cognito` (`region`, `user_pool_id`, `token_use`), `identity.provider.entra` (`tenant_id`), `identity.provider.firebase` (`project_id`)
+- **Description**: The settings of the matching built-in provider. `token_use` is `access` (default) or `id`; any other value fails startup.
+
+- **Field**: `identity.provider.static.principals`
+- **Type**: mapping of secret key to principal (`subject`, `kind`, `groups`, `roles`, `claims`)
+- **Description**: The `static` provider's credentials. Each key names a secret resolved through the secret capability when the provider is built (the environment first), so no credential value is written in the file; a key with no secret, or an empty map, fails startup. An entry's `roles` are issued directly; a role mapper replaces them.
+
+- **Field**: `identity.role_mapper.type`, `identity.role_mapper.mapping`, `identity.role_mapper.claims`, `identity.role_mapper.pass_through`
+- **Description**: Optional. `mapping` (default) maps group names to roles, and the string or list values of the claim paths listed in `claims` (default `[]`: groups only, since a user sets many of their own claims), then appends the `pass_through` claim's value as roles; a dotted path selects a `RoleMapper` subclass, which reads settings of its own from `model_extra`. Without a mapper only a `static` entry's own roles exist. Nothing enforces roles yet.
+
 #### Session Store
 
 Configure where agent sessions are stored (supports multi-cloud storage backends).
@@ -455,9 +663,10 @@ available on AWS ElastiCache at a lower price point than the Redis OSS engine:
 Mounting `AgentThreadRequestHandler` (from `agentkernel.thread`) instead of the default REST handler
 enables persistent, named conversation threads keyed by `session_id`: it serves the standard chat routes
 with thread recording, plus the read routes (`GET /api/v1/threads` and
-`GET /api/v1/threads/{session_id}`, optionally protected by a pluggable `Authoriser`). The `thread`
-block in the configuration only selects the store backend and naming. On the thread handler's chat
-routes `user_id` is required, and a thread is auto-created on a session's first request. Sending
+`GET /api/v1/threads/{session_id}`). The handler requires an `identity` block: every thread belongs to the
+authenticated principal, an anonymous request is a 401, and the listing returns the caller's own threads
+(there is no `user_id` field or query parameter). The `thread` block in the configuration only selects
+the store backend and naming. A thread is auto-created on a session's first request. Sending
 `thread_name` on any chat request sets or renames the thread's display name and locks it against automatic
 naming. Threads created without an explicit `thread_name` are
 named by a pluggable naming strategy — by default an LLM call derives a concise title from the first prompt
@@ -476,7 +685,7 @@ mode additionally require `multimodal.enabled: true` with a shared attachment st
   - **Field**: `thread.naming.model`
   - **Type**: string
   - **Default**: `gpt-4o-mini`
-  - **Description**: LiteLLM model used to generate thread names (requires the `thread` extra — `pip install "agentkernel[thread]"` — and an API key in the environment; falls back to a truncated prompt prefix otherwise)
+  - **Description**: LiteLLM model used to generate thread names (requires the `thread` extra — `uv add "agentkernel[thread]"` — and an API key in the environment; falls back to a truncated prompt prefix otherwise)
   - **Environment Variable**: `AK_THREAD__NAMING__MODEL`
 
 - **Auto-name Max Length**
@@ -510,7 +719,7 @@ Required when `thread.type=redis`:
 
 ##### Valkey Thread Store
 
-Required when `thread.type=valkey`. Requires the `valkey` extra (`pip install "agentkernel[valkey]"`):
+Required when `thread.type=valkey`. Requires the `valkey` extra (`uv add "agentkernel[valkey]"`):
 
 - **URL**
   - **Field**: `thread.valkey.url`
@@ -597,9 +806,10 @@ execution pipeline. The block also injects five agent tools (`create_schedule`,
 `get_schedule`, `update_schedule`, `delete_schedule`). The management routes
 (`GET`/`PUT`/`DELETE /api/v1/schedules`) are not mounted from config: the application mounts
 `ScheduleRESTRequestHandler` itself — `IOHandler.run(handlers=[ScheduleRESTRequestHandler()])` —
-passing an optional pluggable `Authoriser` to the handler to protect them. Every scheduling request
-needs a `user_id`: it is the owner the task is stored under and the identity later reads and changes
-are checked against. A bare `schedule:` block works for local development — its defaults are the
+and the handler requires an `identity` block. Every scheduling request needs an authenticated principal:
+it is the owner the task is stored under and that later reads and changes are checked against (an
+anonymous management request is a 401, an anonymous chat request with a `schedule` block a 403; there is
+no `user_id` field). A bare `schedule:` block works for local development: its defaults are the
 `local` provider and the `in_memory` store. See `examples/api/schedule-openai`.
 
 - **Provider Type**
@@ -700,16 +910,27 @@ failure raises `SecretError` even with a `default`. The capability is always ava
   - **Type**: string
   - **Default**: `env`
   - **Options**: `env` (the process environment), `aws_ssm` (AWS SSM Parameter Store; requires
-    `secret.prefix` and the `aws` extra — `OPENAI_API_KEY` is read from `/ak/<prefix>/openai_api_key`), or a
-    dotted path to a `SecretProvider` subclass
+    `secret.prefix` and the `aws` extra — `OPENAI_API_KEY` is read from `/ak/<prefix>/openai_api_key`),
+    `kubernetes` (one file per key from Kubernetes Secrets mounted under
+    `secret.provider.kubernetes.mount_path`, standard library only, no API calls), or a dotted path to a
+    `SecretProvider` subclass
   - **Environment Variable**: `AK_SECRET__PROVIDER__TYPE`
 
+- **Kubernetes Mount Path**
+  - **Field**: `secret.provider.kubernetes.mount_path`
+  - **Type**: string (absolute path)
+  - **Default**: `/var/run/secrets/agentkernel`
+  - **Description**: Directory the Kubernetes Secrets are mounted under, one subdirectory per Secret
+    (`<mount_path>/<secret-name>/<KEY>`). The Helm chart's `secretStore` mounts under the default. Read only by
+    the `kubernetes` provider
+  - **Environment Variable**: `AK_SECRET__PROVIDER__KUBERNETES__MOUNT_PATH`
+
 - **Prefix**
   - **Field**: `secret.prefix`
   - **Type**: string
   - **Default**: `""`
   - **Description**: Deployment scope providers namespace secrets under; a single path segment. Required by
-    `aws_ssm`, ignored by `env`. Injected by the AWS Terraform modules when `ssm_enabled = true`
+    `aws_ssm`, ignored by `env` and `kubernetes`. Injected by the AWS Terraform modules when `ssm_enabled = true`
   - **Environment Variable**: `AK_SECRET__PREFIX`
 
 - **Cache TTL**
@@ -726,11 +947,27 @@ Configure queue-backed and serverless execution behavior.
 
 - **Execution Mode**
   - **Field**: `execution.mode`
-  - **Options**: `rest_sync`, `rest_async`, `stream`, `async`
-  - **Default**: `None`
-  - **Description**: Selects the execution mode used for queue-backed and serverless request handling
+  - **Options**: `rest_sync`, `rest_async`, `async`, `realtime`
+  - **Default**: `None` (runs as `rest_sync`)
+  - **Description**: How a request is invoked: `rest_sync` (REST, wait for the reply), `rest_async`
+    (REST, submit then poll), `async` (WebSocket only), `realtime` (persistent realtime sockets, e.g.
+    the LiveKit voice gateway). `stream` was removed and fails at config load with `AKConfigError`:
+    set `mode: rest_sync` with `message_type: delta` for SSE over REST, or `mode: async` with
+    `message_type: delta` for chunks over WebSocket
   - **Environment Variable**: `AK_EXECUTION__MODE`
 
+- **Message Type**
+  - **Field**: `execution.message_type`
+  - **Options**: `complete`, `delta`
+  - **Default**: `None` (resolves to `delta` for `realtime`, `complete` otherwise)
+  - **Description**: How much of the reply each delivered message carries. `complete` sends the whole
+    reply in one message (JSON under `rest_sync`, one `CHAT_RESPONSE` under `async`); `delta` sends one
+    message per chunk (SSE under `rest_sync`, one `STREAM_CHUNK` per chunk ending with `done: true`
+    under `async`). `rest_async` + `delta` and `realtime` + `complete` fail at config load. AWS
+    Lambda (REST router init) and the ECS queue-mode `ECSIOHandler` (startup) refuse `rest_sync` +
+    `delta`; use `async` + `delta` there
+  - **Environment Variable**: `AK_EXECUTION__MESSAGE_TYPE`
+
 - **Queues**
   - **Field**: `execution.queues`
   - **Description**: Queue settings used by the queue execution pipeline (in-process by default, or serverless/containerized backends)
@@ -1022,6 +1259,12 @@ Configure the REST API server (if using the API module).
   - **Description**: List of agent names to expose as MCP tools
   - **Environment Variable**: `AK_MCP__AGENTS` (comma-separated)
 
+- **URL**
+  - **Field**: `mcp.url`
+  - **Default**: `http://localhost:8000/mcp`
+  - **Description**: Public URL of the MCP endpoint. With an OpenID-family identity provider the 401 points at the RFC 9728 resource metadata the app serves at `<origin>/.well-known/oauth-protected-resource/mcp/`, naming this URL as the resource; set it to the address clients use (behind a proxy, the public one)
+  - **Environment Variable**: `AK_MCP__URL`
+
 - **Stateless HTTP**
   - **Field**: `mcp.stateless_http`
   - **Default**: `false`
@@ -1037,10 +1280,13 @@ Configure the REST API server (if using the API module).
 Mounting `AGUIRequestHandler` (from `agentkernel.agui`, requires the `agentkernel[agui]` extra — `pip
 install "agentkernel[agui]"`) is what enables the [AG-UI protocol](https://github.com/ag-ui-protocol/ag-ui)
 surface; the `agui` block only parameterizes it, and it never switches the surface on by itself.
-`AGUIRequestHandler` refuses to construct without an `Authoriser` or `AuthValidator` — AG-UI runs
-agents on a caller's behalf and has no anonymous mode. Only agents whose runner declares
-`supports_streaming = True` are reachable (currently OpenAI Agents SDK, LangGraph, Google ADK, and
-Pydantic AI — not CrewAI or Smolagents). See `examples/api/agui`.
+Mount `AGUIPipelineRequestHandler` through `IOHandler.run(handlers=[...])` instead to run the agent
+on the queue pipeline rather than inside the SSE request; same routes and events, and it refuses to
+start unless the configured stores can serve a run from the runner process.
+`AGUIRequestHandler` refuses to construct without an `identity` block and answers an anonymous request
+with a 401, since AG-UI runs agents on a caller's behalf and has no anonymous mode. Only agents whose runner declares
+`supports_streaming = True` are reachable (currently OpenAI Agents SDK, LangGraph, Google ADK, Pydantic AI
+and Microsoft Agent Framework — not CrewAI or Smolagents). See `examples/api/agui`.
 
 - **Agents**
   - **Field**: `agui.agents`
@@ -1078,6 +1324,27 @@ Pydantic AI — not CrewAI or Smolagents). See `examples/api/agui`.
   - **Default**: unset (every agent gets the tools)
   - **Environment Variable**: `AK_AGUI__CLIENT_CONTEXT__AGENTS` (comma-separated)
 
+#### A2UI Configuration
+
+Labels a JSON reply as [A2UI](https://a2ui.org/) so a client receives the document as an object with
+its format named, instead of a JSON string it has to parse a second time. Agent Kernel supplies the
+media type and nothing else — the component catalog belongs in your agent's instructions, because it
+has to match the components your frontend implements. The block does not reach a streamed run
+(`execution.message_type: delta`) or an agent configured with a framework `output_type`; both are told to
+write their own post-hook. See `examples/api/a2ui-openai`.
+
+- **Enabled**
+  - **Field**: `a2ui.enabled`
+  - **Default**: `false`
+  - **Description**: Master switch. When off, no hook runs and no reply is labelled
+  - **Environment Variable**: `AK_A2UI__ENABLED`
+
+- **Agents**
+  - **Field**: `a2ui.agents`
+  - **Default**: unset (every agent's JSON replies are labelled)
+  - **Description**: Agent names whose JSON replies are labelled `application/a2ui+json`. Naming an agent is the declaration that it emits A2UI; a reply from it that does not parse as JSON is left alone
+  - **Environment Variable**: `AK_A2UI__AGENTS` (comma-separated)
+
 #### Trace (Observability) Configuration
 
 Configure tracing and observability for monitoring agent execution.
@@ -1100,7 +1367,7 @@ Configure tracing and observability for monitoring agent execution.
 To use Langfuse for tracing, install the langfuse extra:
 
 ```bash
-pip install agentkernel[langfuse]
+uv add "agentkernel[langfuse]"
 ```
 
 Configure Langfuse credentials via environment variables:
@@ -1124,7 +1391,7 @@ trace:
 To use OpenLLMetry for tracing, install the openllmetry extra:
 
 ```bash
-pip install agentkernel[openllmetry]
+uv add "agentkernel[openllmetry]"
 ```
 
 Configure Traceloop credentials via environment variables:
@@ -1147,7 +1414,7 @@ trace:
 To use Logfire for tracing, install the logfire extra:
 
 ```bash
-pip install agentkernel[logfire]
+uv add "agentkernel[logfire]"
 ```
 
 Configure the Logfire write token via an environment variable (optional — without a token, Logfire
@@ -1170,7 +1437,7 @@ trace:
 To send traces to Amazon CloudWatch (via AWS X-Ray, searchable in Transaction Search), install the cloudwatch extra:
 
 ```bash
-pip install agentkernel[cloudwatch]
+uv add "agentkernel[cloudwatch]"
 ```
 
 Spans are exported over OTLP to the X-Ray endpoint of your region, signed with the standard AWS credential
@@ -1191,6 +1458,24 @@ trace:
   type: cloudwatch
 ```
 
+**Fetching spans back (trace evaluation):**
+
+Every built-in tracer can read recorded spans back through one provider-neutral filter, so production traces can be
+evaluated offline:
+
+```python
+from datetime import timedelta
+
+from agentkernel.trace import SpanKind, Trace
+
+tool_calls = Trace.get().fetch_spans(last=timedelta(hours=6), kinds=[SpanKind.TOOL])
+traces = Trace.get().fetch_traces(session_id="session-123", last=timedelta(hours=24))
+```
+
+Spans are returned oldest first as `FetchedSpan` objects. See the
+[Traceability docs](https://kernel.yaala.ai/docs/advanced/traceability) and the `examples/aws-serverless/openai-langfuse-trace-evaluation`
+example. Custom tracers that override `fetch_spans` can be checked with `agentkernel.trace.testing.TraceFetchContract`.
+
 #### Test Configuration
 
 Configure test comparison modes for automated testing. Test configuration is separate from the application configuration: it is **not** part of `config.yaml`. It lives in its own `test-config.yaml` file and is only loaded when the testing utilities (`agentkernel.test`) are used — see the [Test Configuration (test-config.yaml)](#test-configuration-test-configyaml) section for file resolution, environment variables, and migration notes.
@@ -1227,7 +1512,7 @@ Configure test comparison modes for automated testing. Test configuration is sep
   - **Environment Variable**: `AK_TEST__LLM__EMBEDDING_MODEL`
 
 **Test Modes:**
-- `score`: Deterministic, offline string-match scoring via the configured evaluator (built-in `deepeval`: `Scorer.quasi_exact_match_score`; built-in `opik`: `LevenshteinRatio`, requires `pip install "agentkernel[opik]"`; built-in `jev` has no score mode)
+- `score`: Deterministic, offline string-match scoring via the configured evaluator (built-in `deepeval`: `Scorer.quasi_exact_match_score`; built-in `opik`: `LevenshteinRatio`, requires `uv add "agentkernel[opik]"`; built-in `jev` has no score mode)
 - `llm`: LLM-as-judge evaluation via the configured evaluator (built-in `deepeval` or `opik`: `GEval`; built-in `jev`: a TypeSafe JEV yes/no Noul question) for semantic similarity
 - `fallback`: Tries score first, falls back to llm if score fails
 
@@ -1326,19 +1611,19 @@ Configure input and output guardrails to validate agent requests and responses f
 To use OpenAI guardrails, install the openai-guardrails package:
 
 ```bash
-pip install agentkernel[openai]
+uv add "agentkernel[openai]"
 ```
 
 To use AWS Bedrock guardrails, install the AWS package:
 
 ```bash
-pip install agentkernel[aws]
+uv add "agentkernel[aws]"
 ```
 
 To use Walled AI guardrails, install the Walled AI package:
 
 ```bash
-pip install agentkernel[walledai]
+uv add "agentkernel[walledai]"
 ```
 
 Create guardrail configuration:
@@ -1399,8 +1684,8 @@ guardrail:
 Enable the sandbox capability to let agents execute code and shell commands in an isolated,
 permission-bounded environment. When enabled, agents automatically gain sandbox tools
 (`run_code`, `run_command`, `write_sandbox_file`, `read_sandbox_file`, `check_sandbox_task`,
-`list_sandbox_sessions`, `new_sandbox_session`, `destroy_sandbox_session`) and the usage
-guidance is injected into their system prompt.
+`list_sandbox_sessions`, `new_sandbox_session`, `destroy_sandbox_session`, plus `install_packages`
+when a profile permits package installs) and the usage guidance is injected into their system prompt.
 
 Minimal single-backend form (a `default` profile is synthesized from `type` + its config block):
 
@@ -1438,6 +1723,9 @@ sandbox:
         memory_mb: 512
         timeout: 30.0           # per-execution wall-clock seconds (always enforced)
         strict: true            # fail closed when the provider can't enforce a policy dimension
+        languages: [python]     # run_code allowlist; omitted = provider-declared; [] = no run_code
+        package_install:        # omitted = installs denied; present = install_packages permitted
+          ecosystems: [python]
       docker:
         image: python:3.12-slim
 ```
@@ -1447,7 +1735,8 @@ Key fields:
 - **`enabled`** (`AK_SANDBOX__ENABLED`, default `false`) — master switch; inert when off.
 - **`agents`** — agent names the tools/prompt attach to; omit for all agents.
 - **`type`** (per profile) — `local_subprocess` (no isolation; dev/test), `docker`
-  (container isolation; `sandbox-docker` extra), `e2b` (managed micro-VMs; `e2b` extra),
+  (container isolation; `sandbox-docker` extra), `kubernetes` (pod per sandbox; `kubernetes`
+  extra), `e2b` (managed micro-VMs; `e2b` extra),
   `daytona` (cloud containers; `daytona` extra), `ec2_ssm` (attach to an existing EC2
   instance via SSM; `aws` extra), or a dotted path to your own `SandboxProvider`.
 - **`scope`** — `per_call` (fresh per execution), `per_session` (persists across turns),
@@ -1457,10 +1746,15 @@ Key fields:
   e.g. an EC2 instance via `ec2_ssm`; requires the provider's `attach_to` and is validated
   against the provider's lifecycle capabilities at startup).
 - **`policy`** — network egress, filesystem paths, cpu/memory, timeout; enforced per provider,
-  fail-closed under `strict`.
+  fail-closed under `strict`. Also the permissions: `languages` (which `run_code` languages are
+  allowed) and `package_install` (whether `install_packages` is allowed, and for which ecosystems).
+  A provider's `package_installers` sets the installer command per ecosystem (default `pip install`),
+  and on `docker`/`kubernetes`/`ec2_ssm` its `language_runtimes` sets the interpreter per language (default `python -c`; on `ec2_ssm` each argv reads the code from stdin, default `python3 -`).
 - **`identity.mode`** + **`principal_resolver`** — run code under the agent's or the invoking
-  user's identity.
-- **`broker.flavor`** — `thread` (default, for CLI/REST) or `embedded` (inline/synchronous).
+  user's identity; the default resolver reads the run's `Principal`, so `user` mode needs no custom
+  resolver once an `identity` block authenticates the caller.
+- **`broker.flavor`** — `thread` (default, for CLI/REST), `embedded` (inline/synchronous), or
+  `queue` (a separate `QueueBrokerWorker` fleet over a queue transport).
 
 See the [Sandbox guide](https://kernel.yaala.ai/docs/advanced/sandbox) for the full
 reference and the `examples/sandbox` and `examples/sandbox/identity` examples.
@@ -1864,7 +2158,7 @@ gmail:
 
 Test harness configuration (comparison mode, evaluator backend, llm models) is separate from the application configuration. It is not part of `config.yaml` — it lives in its own `test-config.yaml` file, resolved from the current working directory, and is only loaded when the testing utilities (`agentkernel.test`) are used. A legacy `test:` section in `config.yaml` is ignored. See [Test Configuration](#test-configuration) under Configuration Options for the full list of fields and defaults.
 
-The `evaluator` field accepts three built-in short names — `deepeval` (default, `pip install "agentkernel[test]"`) or `opik` (`pip install "agentkernel[opik]"`, [Opik](https://www.comet.com/docs/opik/) by Comet, runs entirely locally with `OPIK_TRACK_DISABLE` set so no Opik Cloud account or API key is needed) or `jev` (`pip install "agentkernel[jev]"`, hosted [TypeSafe JEV](https://docs.typesafe.ai) judge; `mode: llm` only, needs `TYPESAFE_API_KEY`, and sends the comparison text to `api.typesafe.ai`) — or a dotted path to your own `AKEvaluator` subclass.
+The `evaluator` field accepts three built-in short names — `deepeval` (default, `uv add "agentkernel[test]"`) or `opik` (`uv add "agentkernel[opik]"`, [Opik](https://www.comet.com/docs/opik/) by Comet, runs entirely locally with `OPIK_TRACK_DISABLE` set so no Opik Cloud account or API key is needed) or `jev` (`uv add "agentkernel[jev]"`, hosted [TypeSafe JEV](https://docs.typesafe.ai) judge; `mode: llm` only, needs `TYPESAFE_API_KEY`, and sends the comparison text to `api.typesafe.ai`) — or a dotted path to your own `AKEvaluator` subclass.
 
 **test-config.yaml:**
 
@@ -1937,6 +2231,8 @@ Sessions maintain state across agent interactions. Framework adapters manage the
 - `"openai"` — OpenAI Agents SDK session data
 - `"adk"` — Google ADK session data
 - `"pydanticai"` — Pydantic AI session data (message history)
+- `"maf"` — Microsoft Agent Framework session data (`AgentSession` snapshot)
+- `"claude"` — Claude Agent SDK session data (each agent's Claude session id and transcript)
 
 Access the session in your runner:
 
@@ -1956,14 +2252,14 @@ def run(self, agent, prompt, session):
 
 **Requirements:**
 - Python 3.12+
-- uv 0.8.0+ (recommended) or pip
+- uv 0.8.0+
 
 **Setup:**
 
 ```bash
 git clone https://github.com/yaalalabs/agent-kernel.git
 cd agent-kernel/ak-py
-uv sync  # or: pip install -e ".[dev]"
+uv sync
 ```
 
 **Run Tests:**