agentkernel 0.8.0__tar.gz → 0.9.0__tar.gz

{agentkernel-0.8.0 → agentkernel-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentkernel
-Version: 0.8.0
+Version: 0.9.0
 Summary: Agent Kernel - Unified AI Agents Runtime
 Author: Yaala Labs
 Author-email: Yaala Labs <agentkernel@yaalalabs.com>
@@ -14,9 +14,11 @@ Requires-Dist: a2a-sdk[http-server]>=0.3.6 ; extra == 'a2a'
 Requires-Dist: google-adk>=1.14.1 ; extra == 'adk'
 Requires-Dist: litellm~=1.89.2 ; extra == 'adk'
 Requires-Dist: openinference-instrumentation-google-adk>=0.1.6 ; extra == 'adk'
+Requires-Dist: ag-ui-protocol>=0.1.16 ; extra == 'agui'
 Requires-Dist: fastapi>=0.118.0 ; extra == 'api'
 Requires-Dist: uvicorn>=0.37.0 ; extra == 'api'
 Requires-Dist: gunicorn>=23.0.0 ; extra == 'api'
+Requires-Dist: httpx>=0.27.0 ; extra == 'api'
 Requires-Dist: pyjwt>=2.13.0 ; extra == 'auth'
 Requires-Dist: boto3>=1.41.4 ; extra == 'aws'
 Requires-Dist: azure-functions>=1.24.0 ; extra == 'azure'
@@ -26,6 +28,7 @@ Requires-Dist: chromadb>=0.4.0 ; extra == 'chromadb'
 Requires-Dist: crewai>=1.15.0 ; extra == 'crewai'
 Requires-Dist: openinference-instrumentation-crewai>=0.1.16 ; extra == 'crewai'
 Requires-Dist: openinference-instrumentation-litellm>=0.1.28 ; extra == 'crewai'
+Requires-Dist: croniter>=3.0 ; extra == 'cron'
 Requires-Dist: daytona>=0.198.0,<0.199 ; extra == 'daytona'
 Requires-Dist: e2b-code-interpreter>=2.8.0 ; extra == 'e2b'
 Requires-Dist: google-cloud-firestore>=2.19.0 ; extra == 'gcp'
@@ -34,19 +37,23 @@ Requires-Dist: google-auth-oauthlib>=1.0.0 ; extra == 'gmail'
 Requires-Dist: google-auth-httplib2>=0.2.0 ; extra == 'gmail'
 Requires-Dist: google-api-python-client>=2.0.0 ; extra == 'gmail'
 Requires-Dist: httpx>=0.27.0 ; extra == 'instagram'
+Requires-Dist: confluent-kafka>=2.15.0 ; extra == 'kafka'
+Requires-Dist: kubernetes>=29.0.0 ; extra == 'kubernetes'
 Requires-Dist: langfuse>=4.2.0 ; extra == 'langfuse'
 Requires-Dist: nest-asyncio>=1.6.0 ; extra == 'langfuse'
-Requires-Dist: langgraph~=1.0.5 ; extra == 'langgraph'
-Requires-Dist: langchain~=1.2.3 ; extra == 'langgraph'
+Requires-Dist: langgraph~=1.2.10 ; 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.89.2 ; extra == 'langgraph'
 Requires-Dist: logfire>=3.0 ; extra == 'logfire'
-Requires-Dist: fastmcp>=2.14.2,<3.0.0 ; extra == 'mcp'
+Requires-Dist: fastmcp>=3.2.0,<4.0.0 ; extra == 'mcp'
 Requires-Dist: httpx>=0.27.0 ; extra == 'messenger'
 Requires-Dist: litellm>=1.74.9 ; extra == 'multimodal'
 Requires-Dist: python-multipart>=0.0.12 ; extra == 'multimodal'
+Requires-Dist: nats-py>=2.15.0 ; extra == 'nats'
 Requires-Dist: neo4j>=5.0.0 ; extra == 'neo4j'
-Requires-Dist: openai-agents>=0.6.5 ; extra == 'openai'
+Requires-Dist: openai-agents>=0.7.0 ; extra == 'openai'
 Requires-Dist: openinference-instrumentation-openai-agents>=1.4.0 ; extra == 'openai'
 Requires-Dist: openai-guardrails>=0.2.1 ; extra == 'openai'
 Requires-Dist: traceloop-sdk>=0.61.0 ; extra == 'openllmetry'
@@ -59,6 +66,7 @@ Requires-Dist: httpx>=0.27.0 ; extra == 'slack'
 Requires-Dist: smolagents>=1.0.0 ; extra == 'smolagents'
 Requires-Dist: botbuilder-core>=4.17.0 ; extra == 'teams'
 Requires-Dist: botbuilder-schema>=4.17.0 ; extra == 'teams'
+Requires-Dist: aiohttp>=3.9.0 ; extra == 'teams'
 Requires-Dist: msal>=1.31.1 ; extra == 'teams'
 Requires-Dist: httpx>=0.27.0 ; extra == 'teams'
 Requires-Dist: httpx>=0.27.0 ; extra == 'telegram'
@@ -67,11 +75,7 @@ Requires-Dist: pytest-asyncio>=1.2.0 ; extra == 'test'
 Requires-Dist: pytest-cov>=6.2.1 ; extra == 'test'
 Requires-Dist: pytest-html>=4.1.1 ; extra == 'test'
 Requires-Dist: pytest-order>=1.3.0 ; extra == 'test'
-Requires-Dist: rapidfuzz>=3.14.1 ; extra == 'test'
-Requires-Dist: ragas>=0.4.1 ; extra == 'test'
-Requires-Dist: langchain-community==0.4.1 ; extra == 'test'
-Requires-Dist: datasets>=2.14.0 ; extra == 'test'
-Requires-Dist: pandas>=2.0.0 ; extra == 'test'
+Requires-Dist: deepeval>=4.1.4 ; extra == 'test'
 Requires-Dist: litellm>=1.89.2 ; extra == 'test'
 Requires-Dist: litellm>=1.74.9 ; extra == 'thread'
 Requires-Dist: trino>=0.337.0 ; extra == 'trino'
@@ -81,6 +85,7 @@ Requires-Dist: httpx>=0.27.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
@@ -88,17 +93,21 @@ Provides-Extra: azure
 Provides-Extra: chromadb
 Provides-Extra: cli
 Provides-Extra: crewai
+Provides-Extra: cron
 Provides-Extra: daytona
 Provides-Extra: e2b
 Provides-Extra: gcp
 Provides-Extra: gmail
 Provides-Extra: instagram
+Provides-Extra: kafka
+Provides-Extra: kubernetes
 Provides-Extra: langfuse
 Provides-Extra: langgraph
 Provides-Extra: logfire
 Provides-Extra: mcp
 Provides-Extra: messenger
 Provides-Extra: multimodal
+Provides-Extra: nats
 Provides-Extra: neo4j
 Provides-Extra: openai
 Provides-Extra: openllmetry
@@ -130,11 +139,13 @@ Agent Kernel is a lightweight **AI agent runtime** and adapter layer for buildin
 - **Multi-Framework Support**: OpenAI Agents SDK, CrewAI, LangGraph, Google ADK, Smolagents, and Pydantic AI
 - **Session Management**: Built-in session abstraction with pluggable storage backends
 - **Knowledge Bases**: Unified `KnowledgeBase` interface with ChromaDB, Neo4j, and Starburst/Trino backends via `KnowledgeBuilder`
-- **Sandbox**: Execute agent-generated code and shell commands in an isolated, permission-bounded environment with pluggable providers (`local_subprocess`, `docker`, `e2b`, `daytona`, `ec2_ssm`), workload profiles, policy enforcement, and per-user identity
+- **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
+- **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
 - **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
 - **REST API**: Built-in REST API server for agent interaction
 - **Test Automation**: Built-in test suite for testing agents
 
@@ -158,16 +169,29 @@ For LLM-based thread naming with Conversation Thread Support:
 pip install "agentkernel[thread]"
 ```
 
+For the AG-UI server (`AGUIRequestHandler`):
+
+```bash
+pip install "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)
 ```
 
+For cron parsing with the Scheduling capability (the `eventbridge` provider rides the `aws` extra):
+
+```bash
+pip install "agentkernel[cron]"
+```
+
 **Requirements:**
 - Python 3.12+
 
@@ -419,6 +443,33 @@ if __name__ == "__main__":
 
 For full Terraform deployment configuration, see [`ak-deployment/ak-gcp/`](https://github.com/yaalalabs/agent-kernel/tree/develop/ak-deployment/ak-gcp) or the [GCP deployment docs](https://github.com/yaalalabs/agent-kernel/tree/develop/docs/docs/deployment/gcp-serverless.md).
 
+### On-Prem / Kubernetes Deployment
+
+Deploy the queue pipeline to any Kubernetes cluster with the official Helm chart: an
+io-handler Deployment (REST API + Response Handler), an agent-runner Deployment, and an
+optional WebSocket gateway, over Kafka or NATS JetStream (or SQS on EKS). Your image supplies
+one entry file per component:
+
+```python
+# app_io_handler.py
+from agentkernel.pipeline import IOHandler
+
+IOHandler.run()
+
+# app_agent_runner.py
+from agentkernel.openai import OpenAIModule
+from agentkernel.pipeline import AgentRunner
+
+OpenAIModule([...])
+AgentRunner.run()
+```
+
+The chart injects broker and store connections as `AK_*` environment variables. See
+[`ak-deployment/ak-k8s/`](https://github.com/yaalalabs/agent-kernel/tree/develop/ak-deployment/ak-k8s),
+the [On-Prem / Kubernetes docs](https://github.com/yaalalabs/agent-kernel/tree/develop/docs/docs/deployment/onprem-kubernetes.md),
+and the end-to-end example at
+[`examples/k8s/openai-queue-mode`](https://github.com/yaalalabs/agent-kernel/tree/develop/examples/k8s/openai-queue-mode).
+
 ## Configuration
 
 Agent Kernel can be configured via environment variables, `.env` files, or YAML/JSON configuration files.
@@ -518,10 +569,12 @@ available on AWS ElastiCache at a lower price point than the Redis OSS engine:
 
 #### Conversation Thread Support
 
-Adding a `thread` block to the configuration turns on persistent, named conversation threads keyed by
-`session_id`. Once enabled, `user_id` becomes required on every chat request, a thread is auto-created on a
-session's first request, and history becomes readable over REST (`GET /api/v1/threads` and
-`GET /api/v1/threads/{session_id}` — optionally protected by a pluggable `Authoriser`). Sending
+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
 `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
@@ -532,8 +585,8 @@ mode additionally require `multimodal.enabled: true` with a shared attachment st
 
 - **Field**: `thread.type`
 - **Type**: string
-- **Options**: `memory`, `redis`, `dynamodb` (AWS), `firestore` (GCP), `cosmosdb` (Azure)
-- **Default**: `memory`
+- **Options**: `in_memory`, `redis`, `valkey`, `dynamodb` (AWS), `firestore` (GCP), `cosmosdb` (Azure)
+- **Default**: `in_memory`
 - **Environment Variable**: `AK_THREAD__TYPE`
 
 - **Naming Model**
@@ -572,6 +625,28 @@ Required when `thread.type=redis`:
   - **Description**: Key prefix for Redis thread storage
   - **Environment Variable**: `AK_THREAD__REDIS__PREFIX`
 
+##### Valkey Thread Store
+
+Required when `thread.type=valkey`. Requires the `valkey` extra (`pip install "agentkernel[valkey]"`):
+
+- **URL**
+  - **Field**: `thread.valkey.url`
+  - **Default**: `valkey://localhost:6379`
+  - **Description**: Valkey connection URL. Use `valkeys://` for SSL
+  - **Environment Variable**: `AK_THREAD__VALKEY__URL`
+
+- **TTL (Time to Live)**
+  - **Field**: `thread.valkey.ttl`
+  - **Default**: `2592000` (30 days)
+  - **Description**: Thread TTL in seconds (0 disables)
+  - **Environment Variable**: `AK_THREAD__VALKEY__TTL`
+
+- **Key Prefix**
+  - **Field**: `thread.valkey.prefix`
+  - **Default**: `ak:thread:`
+  - **Description**: Key prefix for Valkey thread storage
+  - **Environment Variable**: `AK_THREAD__VALKEY__PREFIX`
+
 ##### DynamoDB Thread Store
 
 Used when `thread.type=dynamodb`:
@@ -629,6 +704,104 @@ Required when `thread.type=cosmosdb`:
   - **Description**: Cosmos DB table name for thread storage
   - **Environment Variable**: `AK_THREAD__COSMOSDB__TABLE_NAME`
 
+#### Scheduling
+
+The presence of a `schedule` block enables deferred and recurring chat execution: a chat request carrying a
+`schedule` block (`at` for one-time, `cron` for recurring, plus `timezone` and `session_mode`) is not run —
+it is registered as a scheduled task and acknowledged with HTTP 202. When an occurrence is due, the provider
+delivers the stored prompt into the input queue as a plain chat request, so scheduling requires the queue
+execution pipeline. The block also injects five agent tools (`create_schedule`, `list_schedules`,
+`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
+`local` provider and the `in_memory` store. See `examples/api/schedule-openai`.
+
+- **Provider Type**
+  - **Field**: `schedule.provider.type`
+  - **Type**: string
+  - **Default**: `local`
+  - **Options**: `local` (in-process scheduler thread; requires the `in_memory` transport and store),
+    `eventbridge` (AWS EventBridge Scheduler; requires the `sqs` transport and the `aws` extra), or a dotted
+    path to a `ScheduleProvider` subclass
+  - **Environment Variable**: `AK_SCHEDULE__PROVIDER__TYPE`
+
+- **Store Type**
+  - **Field**: `schedule.store.type`
+  - **Type**: string
+  - **Default**: `in_memory`
+  - **Options**: `in_memory`, `redis`, `valkey`, `dynamodb`, or a dotted path to a `ScheduleStore` subclass
+  - **Environment Variable**: `AK_SCHEDULE__STORE__TYPE`
+
+- **Tool Scoping**
+  - **Field**: `schedule.agents`
+  - **Type**: list of strings
+  - **Default**: `null` (all agents)
+  - **Description**: Agent names the schedule tools and system-prompt guidance attach to
+  - **Environment Variable**: `AK_SCHEDULE__AGENTS`
+
+##### EventBridge Scheduler Provider
+
+Required when `schedule.provider.type=eventbridge`. All three are supplied by the AWS Terraform modules
+when `enable_scheduling = true`; a missing one fails at startup with an `AKConfigError`.
+
+- **Group Name**
+  - **Field**: `schedule.provider.eventbridge.group_name`
+  - **Description**: EventBridge Scheduler schedule-group name the schedules are created in
+  - **Environment Variable**: `AK_SCHEDULE__PROVIDER__EVENTBRIDGE__GROUP_NAME`
+
+- **Role ARN**
+  - **Field**: `schedule.provider.eventbridge.role_arn`
+  - **Description**: Execution role ARN Scheduler assumes to deliver triggers to the input queue
+  - **Environment Variable**: `AK_SCHEDULE__PROVIDER__EVENTBRIDGE__ROLE_ARN`
+
+- **Queue ARN**
+  - **Field**: `schedule.provider.eventbridge.queue_arn`
+  - **Description**: Input queue ARN used as the schedule target
+  - **Environment Variable**: `AK_SCHEDULE__PROVIDER__EVENTBRIDGE__QUEUE_ARN`
+
+##### Redis / Valkey Schedule Store
+
+Required when `schedule.store.type=redis` (or `valkey`, with `schedule.store.valkey.*` / `AK_SCHEDULE__STORE__VALKEY__*`).
+
+- **URL**
+  - **Field**: `schedule.store.redis.url`
+  - **Default**: `redis://localhost:6379`
+  - **Description**: Redis connection URL. Use `rediss://` for SSL
+  - **Environment Variable**: `AK_SCHEDULE__STORE__REDIS__URL`
+
+- **Key Prefix**
+  - **Field**: `schedule.store.redis.prefix`
+  - **Default**: `ak:schedule:`
+  - **Description**: Key prefix for scheduled-task storage
+  - **Environment Variable**: `AK_SCHEDULE__STORE__REDIS__PREFIX`
+
+- **TTL (Time to Live)**
+  - **Field**: `schedule.store.redis.ttl`
+  - **Default**: `0` (disabled)
+  - **Description**: Scheduled task TTL in seconds. Unlike threads this defaults to 0 — a task that
+    silently expired would stop firing with no audit trail
+  - **Environment Variable**: `AK_SCHEDULE__STORE__REDIS__TTL`
+
+##### DynamoDB Schedule Store
+
+Required when `schedule.store.type=dynamodb`. The table needs a partition key named `task_id` (S) and no
+sort key; the AWS Terraform modules create it when `create_dynamodb_schedule_table = true`.
+
+- **Table Name**
+  - **Field**: `schedule.store.dynamodb.table_name`
+  - **Default**: `ak-agent-schedules`
+  - **Description**: DynamoDB table name for scheduled-task storage
+  - **Environment Variable**: `AK_SCHEDULE__STORE__DYNAMODB__TABLE_NAME`
+
+- **TTL (Time to Live)**
+  - **Field**: `schedule.store.dynamodb.ttl`
+  - **Default**: `0` (disabled)
+  - **Description**: DynamoDB item TTL in seconds
+  - **Environment Variable**: `AK_SCHEDULE__STORE__DYNAMODB__TTL`
+
 #### Execution Configuration
 
 Configure queue-backed and serverless execution behavior.
@@ -642,16 +815,25 @@ Configure queue-backed and serverless execution behavior.
 
 - **Queues**
   - **Field**: `execution.queues`
-  - **Description**: Queue settings used by serverless execution modes
+  - **Description**: Queue settings used by the queue execution pipeline (in-process by default, or serverless/containerized backends)
+
+  - **Transport Type**
+    - **Field**: `execution.queues.type`
+    - **Options**: `in_memory`, `sqs`, `kafka`, `nats`, or a dotted path to a `QueueTransport` subclass
+    - **Default**: none — **mandatory whenever an `execution.queues` block is declared**
+    - **Description**: Queue transport used by the pipeline, and the only thing that selects it: queue coordinates are injected per component by a deployment, so they are never used to infer the transport. Declaring the block without a `type` is a configuration error. Omitting the block entirely leaves `in_memory` — a zero-dependency, in-process transport for local development and single-process deployments.
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__TYPE`
 
   - **Input Queue URL**
     - **Field**: `execution.queues.input.url`
     - **Default**: `None`
+    - **Description**: Input queue URL (`sqs` transport only)
     - **Environment Variable**: `AK_EXECUTION__QUEUES__INPUT__URL`
 
   - **Output Queue URL**
     - **Field**: `execution.queues.output.url`
     - **Default**: `None`
+    - **Description**: Output queue URL (`sqs` transport only)
     - **Environment Variable**: `AK_EXECUTION__QUEUES__OUTPUT__URL`
 
   - **Input Queue Max Receive Count**
@@ -667,15 +849,150 @@ Configure queue-backed and serverless execution behavior.
   - **Input Queue Consumer Count**
     - **Field**: `execution.queues.input.no_of_consumers`
     - **Default**: `5`
-    - **Description**: Number of independent consumer threads that each poll the input queue in a continuous loop. Only used by containerized deployments — never set for serverless deployments, which have no consumer threads.
+    - **Description**: Number of independent consumer threads that each poll the input queue in a continuous loop. Used by the in-process pipeline (agent-runner worker threads) and by ECS containerized deployments; not used in serverless (Lambda) mode, which has no consumer threads.
     - **Environment Variable**: `AK_EXECUTION__QUEUES__INPUT__NO_OF_CONSUMERS`
 
   - **Output Queue Consumer Count**
     - **Field**: `execution.queues.output.no_of_consumers`
     - **Default**: `5`
-    - **Description**: Number of independent consumer threads that each poll the output queue in a continuous loop. Only used by containerized deployments — never set for serverless deployments, which have no consumer threads.
+    - **Description**: Number of independent consumer threads that each poll the output queue in a continuous loop. Used by the in-process pipeline (response-handler worker threads) and by ECS containerized deployments; not used in serverless (Lambda) mode, which has no consumer threads.
     - **Environment Variable**: `AK_EXECUTION__QUEUES__OUTPUT__NO_OF_CONSUMERS`
 
+  - **In-Memory Transport Ack Wait**
+    - **Field**: `execution.queues.in_memory.ack_wait`
+    - **Default**: `300.0`
+    - **Description**: Seconds an unacknowledged in-memory message stays invisible before redelivery. Redelivery rescues stuck worker threads; keep this above your longest expected agent run or a slow run will be executed again.
+
+  - **In-Memory Transport Dedup Window**
+    - **Field**: `execution.queues.in_memory.dedup_window`
+    - **Default**: `300.0`
+    - **Description**: Seconds within which a repeated `message_deduplication_id` is dropped
+
+  - **Kafka Bootstrap Servers**
+    - **Field**: `execution.queues.kafka.bootstrap_servers`
+    - **Default**: `localhost:9092`
+    - **Description**: Kafka bootstrap servers (host:port, comma-separated)
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__KAFKA__BOOTSTRAP_SERVERS`
+
+  - **Kafka Input Topic**
+    - **Field**: `execution.queues.kafka.input_topic`
+    - **Default**: `agent-input`
+    - **Description**: Topic carrying chat requests
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__KAFKA__INPUT_TOPIC`
+
+  - **Kafka Output Topic**
+    - **Field**: `execution.queues.kafka.output_topic`
+    - **Default**: `agent-output`
+    - **Description**: Topic carrying agent replies
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__KAFKA__OUTPUT_TOPIC`
+
+  - **Kafka Consumer Group Id**
+    - **Field**: `execution.queues.kafka.group_id`
+    - **Default**: `agent-kernel`
+    - **Description**: Consumer group id prefix; the input and output consumers append their queue name to it
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__KAFKA__GROUP_ID`
+
+  - **Kafka Dead-Letter Topic Suffix**
+    - **Field**: `execution.queues.kafka.dlq_suffix`
+    - **Default**: `.dlq`
+    - **Description**: Suffix appended to a topic name for its dead-letter topic, where permanently failed records are routed
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__KAFKA__DLQ_SUFFIX`
+
+  - **Kafka Retry Backoff**
+    - **Field**: `execution.queues.kafka.retry_backoff`
+    - **Default**: `2.0`
+    - **Description**: Seconds to wait before an in-process retry of a failed record
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__KAFKA__RETRY_BACKOFF`
+
+  - **Kafka Delivery Timeout**
+    - **Field**: `execution.queues.kafka.delivery_timeout`
+    - **Default**: `30.0`
+    - **Description**: Seconds to wait for the broker to confirm a produced message before failing the send
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__KAFKA__DELIVERY_TIMEOUT`
+
+  - **Kafka Metadata Timeout**
+    - **Field**: `execution.queues.kafka.metadata_timeout`
+    - **Default**: `5.0`
+    - **Description**: Seconds to wait for topic metadata during the startup partition-capacity check (the check is skipped on timeout)
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__KAFKA__METADATA_TIMEOUT`
+
+  - **Kafka Client Config**
+    - **Field**: `execution.queues.kafka.client_config`
+    - **Default**: `{}`
+    - **Description**: Passthrough settings merged into the `confluent-kafka` producer and consumer configs (SASL, TLS, tuning); set via `config.yaml`, not individually exported as environment variables
+
+  - **NATS Server URL**
+    - **Field**: `execution.queues.nats.url`
+    - **Default**: `nats://localhost:4222`
+    - **Description**: NATS server URL (comma-separated for a cluster)
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__NATS__URL`
+
+  - **NATS Input Stream**
+    - **Field**: `execution.queues.nats.input_stream`
+    - **Default**: `AGENT_REQUESTS`
+    - **Description**: JetStream stream carrying chat requests
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__NATS__INPUT_STREAM`
+
+  - **NATS Input Subject Prefix**
+    - **Field**: `execution.queues.nats.input_subject_prefix`
+    - **Default**: `chat.req`
+    - **Description**: Subject prefix for chat requests
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__NATS__INPUT_SUBJECT_PREFIX`
+
+  - **NATS Output Stream**
+    - **Field**: `execution.queues.nats.output_stream`
+    - **Default**: `AGENT_REPLIES`
+    - **Description**: JetStream stream carrying agent replies
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__NATS__OUTPUT_STREAM`
+
+  - **NATS Output Subject Prefix**
+    - **Field**: `execution.queues.nats.output_subject_prefix`
+    - **Default**: `chat.out`
+    - **Description**: Subject prefix for agent replies
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__NATS__OUTPUT_SUBJECT_PREFIX`
+
+  - **NATS Partitions**
+    - **Field**: `execution.queues.nats.partitions`
+    - **Default**: `32`
+    - **Description**: Number of partition subjects per stream, each served by its own durable consumer. Sessions hash to a partition, so this caps how many messages can be in flight at once: keep it at or above `no_of_consumers` x replicas. Changing it re-maps sessions, so size it up front (idle partitions cost almost nothing)
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__NATS__PARTITIONS`
+
+  - **NATS Ack Wait**
+    - **Field**: `execution.queues.nats.ack_wait`
+    - **Default**: `300.0`
+    - **Description**: Seconds the server waits for an acknowledgement before redelivering. Must exceed your longest agent turn: a turn that outlives it is redelivered and executed a second time
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__NATS__ACK_WAIT`
+
+  - **NATS Retry Backoff**
+    - **Field**: `execution.queues.nats.retry_backoff`
+    - **Default**: `2.0`
+    - **Description**: Seconds to delay a redelivery after a failed message (nak delay)
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__NATS__RETRY_BACKOFF`
+
+  - **NATS Duplicate Window**
+    - **Field**: `execution.queues.nats.duplicate_window`
+    - **Default**: `300.0`
+    - **Description**: Seconds within which a repeated dedup id is dropped by the stream (SQS parity)
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__NATS__DUPLICATE_WINDOW`
+
+  - **NATS Max Age**
+    - **Field**: `execution.queues.nats.max_age`
+    - **Default**: `86400.0`
+    - **Description**: Seconds before an unconsumed message is discarded. A safety net: work-queue messages are otherwise kept forever
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__NATS__MAX_AGE`
+
+  - **NATS Request Timeout**
+    - **Field**: `execution.queues.nats.request_timeout`
+    - **Default**: `10.0`
+    - **Description**: Seconds to wait for a NATS request (publish, ack, management call) to complete
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__NATS__REQUEST_TIMEOUT`
+
+  - **NATS Auto Provision**
+    - **Field**: `execution.queues.nats.auto_provision`
+    - **Default**: `false`
+    - **Description**: Create the streams and per-partition consumers at startup if missing. Convenient for local and dev clusters; leave false in production, where the objects are managed declaratively (NACK CRs) and a missing object should fail loudly instead of being created with defaults
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__NATS__AUTO_PROVISION`
+
   - **Queue Batch Size**
     - **Field**: `execution.queues.batch_size`
     - **Default**: `None`
@@ -688,7 +1005,8 @@ Configure queue-backed and serverless execution behavior.
 
   - **Type**
     - **Field**: `execution.response_store.type`
-    - **Description**: Response store backend selector configured in `config.yaml`; this value is not exported as an environment variable
+    - **Options**: `in_memory`, `redis`, `valkey`, `dynamodb`, or a dotted path to a `ResponseStore` subclass
+    - **Description**: Response store backend selector configured in `config.yaml`; this value is not exported as an environment variable. Defaults to an in-process `in_memory` store when unset and no other backend is configured.
 
   - **Retry Count**
     - **Field**: `execution.response_store.retry_count`
@@ -716,7 +1034,7 @@ Configure queue-backed and serverless execution behavior.
     - **Environment Variables**: `AK_EXECUTION__RESPONSE_STORE__DYNAMODB__TABLE_NAME`, `AK_EXECUTION__RESPONSE_STORE__DYNAMODB__TTL`
     - **Description**: DynamoDB-backed response storage with table name and TTL
 
-Use Redis, Valkey, or DynamoDB for the response store backend. The runtime accepts `BaseRunRequest` payloads directly, normalizes them internally when queueing is required, and uses `request_id` plus optional `user_id` as queue message attributes.
+Use the built-in `in_memory` response store for local development and single-process deployments (zero extra services required), or Redis, Valkey, or DynamoDB for distributed/serverless deployments. The runtime accepts `BaseRunRequest` payloads directly, normalizes them internally when queueing is required, and uses `request_id` plus optional `user_id` as queue message attributes.
 
 #### API Configuration
 
@@ -796,6 +1114,52 @@ Configure the REST API server (if using the API module).
   - The MCP server is always mounted at `/mcp` on the main API server.
   - Full URL: `http://{api.host}:{api.port}/mcp` — use `api.port` / `AK_API__PORT` to change the port.
 
+#### AG-UI Configuration
+
+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`.
+
+- **Agents**
+  - **Field**: `agui.agents`
+  - **Default**: unset (every streaming-capable agent is reachable)
+  - **Description**: Agent names reachable over AG-UI
+  - **Environment Variable**: `AK_AGUI__AGENTS` (comma-separated)
+
+- **Prefix**
+  - **Field**: `agui.prefix`
+  - **Default**: `/agui`
+  - **Description**: Route prefix for the AG-UI surface
+  - **Environment Variable**: `AK_AGUI__PREFIX`
+
+- **Default Agent**
+  - **Field**: `agui.default_agent`
+  - **Default**: unset
+  - **Description**: Agent served on the bare prefix route (`POST {prefix}`, in addition to `POST {prefix}/{agent_name}`); must be one of `agui.agents` when that list is set
+  - **Environment Variable**: `AK_AGUI__DEFAULT_AGENT`
+
+- **State Tools**
+  - **Field**: `agui.state.enabled`
+  - **Default**: `false`
+  - **Description**: Attach `get_agui_state` / `update_agui_state`, giving agents read/write access to AG-UI's shared JSON state (a `StateSnapshot` is streamed back only when the state actually changed)
+  - **Environment Variable**: `AK_AGUI__STATE__ENABLED`
+  - **Field**: `agui.state.agents`
+  - **Default**: unset (every agent gets the tools)
+  - **Environment Variable**: `AK_AGUI__STATE__AGENTS` (comma-separated)
+
+- **Client Context Tools**
+  - **Field**: `agui.client_context.enabled`
+  - **Default**: `false`
+  - **Description**: Attach the read-only `get_forwarded_props` / `get_agui_context` tools over a run's `forwardedProps` and `context` fields; never injected into the prompt automatically
+  - **Environment Variable**: `AK_AGUI__CLIENT_CONTEXT__ENABLED`
+  - **Field**: `agui.client_context.agents`
+  - **Default**: unset (every agent gets the tools)
+  - **Environment Variable**: `AK_AGUI__CLIENT_CONTEXT__AGENTS` (comma-separated)
+
 #### Trace (Observability) Configuration
 
 Configure tracing and observability for monitoring agent execution.
@@ -889,38 +1253,45 @@ Configure test comparison modes for automated testing. Test configuration is sep
 
 - **Mode**
   - **Field**: `mode`
-  - **Options**: `fuzzy`, `judge`, `fallback`
+  - **Options**: `score`, `llm`, `fallback`
   - **Default**: `fallback`
   - **Description**: Test comparison mode
   - **Environment Variable**: `AK_TEST__MODE`
 
-- **Judge Model**
-  - **Field**: `judge.model`
+- **Evaluator**
+  - **Field**: `evaluator`
+  - **Default**: `deepeval`
+  - **Description**: Built-in evaluator short name, or a dotted path to your own `AKEvaluator` subclass
+  - **Environment Variable**: `AK_TEST__EVALUATOR`
+
+- **Llm Model**
+  - **Field**: `llm.model`
   - **Default**: `gpt-4o-mini`
-  - **Description**: LLM model for judge evaluation
-  - **Environment Variable**: `AK_TEST__JUDGE__MODEL`
+  - **Description**: LLM model for llm evaluation
+  - **Environment Variable**: `AK_TEST__LLM__MODEL`
 
-- **Judge Provider**
-  - **Field**: `judge.provider`
+- **Llm Provider**
+  - **Field**: `llm.provider`
   - **Default**: `openai`
-  - **Description**: LLM provider for judge evaluation
-  - **Environment Variable**: `AK_TEST__JUDGE__PROVIDER`
+  - **Description**: LLM provider for llm evaluation
+  - **Environment Variable**: `AK_TEST__LLM__PROVIDER`
 
-- **Judge Embedding Model**
-  - **Field**: `judge.embedding_model`
+- **Llm Embedding Model**
+  - **Field**: `llm.embedding_model`
   - **Default**: `text-embedding-3-small`
-  - **Description**: Embedding model for similarity evaluation
-  - **Environment Variable**: `AK_TEST__JUDGE__EMBEDDING_MODEL`
+  - **Description**: Embedding model, unconsumed by any built-in v1 metric
+  - **Environment Variable**: `AK_TEST__LLM__EMBEDDING_MODEL`
 
 **Test Modes:**
-- `fuzzy`: Uses fuzzy string matching (RapidFuzz)
-- `judge`: Uses LLM-based evaluation (Ragas) for semantic similarity
-- `fallback`: Tries fuzzy first, falls back to judge if fuzzy fails
+- `score`: Deterministic, offline string-match scoring via the configured evaluator (built-in DeepEval evaluator: `Scorer.quasi_exact_match_score`)
+- `llm`: LLM-as-judge evaluation via the configured evaluator (built-in DeepEval evaluator: `GEval`) for semantic similarity
+- `fallback`: Tries score first, falls back to llm if score fails
 
 ```yaml
 # test-config.yaml (separate file — not config.yaml)
 mode: fallback
-judge:
+evaluator: deepeval
+llm:
   model: gpt-4o-mini
   provider: openai
   embedding_model: text-embedding-3-small
@@ -1147,7 +1518,7 @@ Key fields:
   user's identity.
 - **`broker.flavor`** — `thread` (default, for CLI/REST) or `embedded` (inline/synchronous).
 
-See the [Sandbox guide](https://kernel.yaala.ai/docs/next/advanced/sandbox) for the full
+See the [Sandbox guide](https://kernel.yaala.ai/docs/advanced/sandbox) for the full
 reference and the `examples/sandbox` and `examples/sandbox/identity` examples.
 
 #### Messaging Platform Integrations
@@ -1212,6 +1583,30 @@ Configure integrations with messaging platforms.
 - **Bot Token**, **Webhook Secret**, **API Version**
   - **Environment Variables**: `AK_TELEGRAM__BOT_TOKEN`, `AK_TELEGRAM__WEBHOOK_SECRET`, `AK_TELEGRAM__API_VERSION`
 
+##### Microsoft Teams
+
+- **Agent**
+  - **Field**: `teams.agent`
+  - **Default**: `""`
+  - **Description**: Default agent for Microsoft Teams interactions
+  - **Environment Variable**: `AK_TEAMS__AGENT`
+
+- **Agent Acknowledgement**
+  - **Field**: `teams.agent_acknowledgement`
+  - **Default**: `""`
+  - **Description**: Message sent as an acknowledgement when a Teams message is received
+  - **Environment Variable**: `AK_TEAMS__AGENT_ACKNOWLEDGEMENT`
+
+- **App ID**, **App Password**
+  - **Description**: Azure Bot / Entra ID application (client) ID and client secret. Both are required
+  - **Environment Variables**: `AK_TEAMS__APP_ID`, `AK_TEAMS__APP_PASSWORD`
+
+- **Tenant ID**
+  - **Field**: `teams.tenant_id`
+  - **Default**: `""`
+  - **Description**: Entra ID tenant that owns the bot's app registration. Required only for a single-tenant registration, whose channel tokens must be issued by its own tenant; leave empty for a multi-tenant bot. Also the fallback tenant for the app-only token used to download attachments whose URL is not pre-authenticated, when the incoming activity carries none
+  - **Environment Variable**: `AK_TEAMS__TENANT_ID`
+
 ##### Gmail
 
 - **Agent**
@@ -1250,10 +1645,11 @@ export AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
 # For Logfire:
 # export LOGFIRE_TOKEN=your-write-token
 # Test harness (loaded from the separate test-config.yaml — see Test Configuration)
-export AK_TEST__MODE=fallback  # Options: fuzzy, judge, fallback
-export AK_TEST__JUDGE__MODEL=gpt-4o-mini
-export AK_TEST__JUDGE__PROVIDER=openai
-export AK_TEST__JUDGE__EMBEDDING_MODEL=text-embedding-3-small
+export AK_TEST__MODE=fallback  # Options: score, llm, fallback
+export AK_TEST__EVALUATOR=deepeval  # Built-in short name, or a dotted path to your own AKEvaluator subclass
+export AK_TEST__LLM__MODEL=gpt-4o-mini
+export AK_TEST__LLM__PROVIDER=openai
+export AK_TEST__LLM__EMBEDDING_MODEL=text-embedding-3-small
 # Guardrails configuration
 export AK_GUARDRAIL__INPUT__ENABLED=false
 export AK_GUARDRAIL__INPUT__TYPE=openai
@@ -1314,7 +1710,7 @@ session:
     url: redis://localhost:6379
     ttl: 604800
     prefix: "ak:sessions:"
-thread: # optional — enables Conversation Thread Support (user_id becomes required on chat requests)
+thread: # optional; configures Conversation Thread Support (enabled by mounting AgentThreadRequestHandler)
   type: redis
   redis:
     url: redis://localhost:6379
@@ -1323,17 +1719,42 @@ thread: # optional — enables Conversation Thread Support (user_id becomes requ
 execution:
   mode: rest_sync
   queues:
+    type: sqs # in_memory | sqs | kafka | nats, or a dotted path to a QueueTransport subclass — mandatory whenever this block is declared
     input:
-      url: https://queue.example.com/<accountno>/<queuename>
+      url: https://queue.example.com/<accountno>/<queuename> # sqs transport only
       max_receive_count: 3
-      no_of_consumers: 5 # Containerized deployments only, ignored by serverless deployments
+      no_of_consumers: 5 # in-process pipeline + containerized deployments, ignored by serverless deployments
     output:
-      url: https://queue.example.com/<accountno>/<queuename>
+      url: https://queue.example.com/<accountno>/<queuename> # sqs transport only
       max_receive_count: 3
-      no_of_consumers: 5 # Containerized deployments only, ignored by serverless deployments
+      no_of_consumers: 5 # in-process pipeline + containerized deployments, ignored by serverless deployments
+    # in_memory: {ack_wait: 300.0, dedup_window: 300.0}  # in_memory transport settings, unused otherwise
+    # kafka:  # kafka transport settings, unused otherwise
+    #   bootstrap_servers: localhost:9092
+    #   input_topic: agent-input
+    #   output_topic: agent-output
+    #   group_id: agent-kernel
+    #   dlq_suffix: .dlq
+    #   retry_backoff: 2.0
+    #   delivery_timeout: 30.0
+    #   metadata_timeout: 5.0
+    #   client_config: {} # passthrough confluent-kafka producer/consumer settings (SASL, TLS, tuning)
+    # nats:  # nats transport settings, unused otherwise
+    #   url: nats://localhost:4222
+    #   input_stream: AGENT_REQUESTS
+    #   input_subject_prefix: chat.req
+    #   output_stream: AGENT_REPLIES
+    #   output_subject_prefix: chat.out
+    #   partitions: 32
+    #   ack_wait: 300.0
+    #   retry_backoff: 2.0
+    #   duplicate_window: 300.0
+    #   max_age: 86400.0
+    #   request_timeout: 10.0
+    #   auto_provision: false # true for local/dev; leave false where NACK CRs own the objects
     # batch_size is set by the deployment tooling — set via AK_EXECUTION__QUEUES__BATCH_SIZE, never here
   response_store:
-    type: redis
+    type: redis # in_memory | redis | valkey | dynamodb | dotted path — omit for the built-in in_memory store
     retry_count: 5
     delay: 5
     redis: # if this is given, then valkey/dynamodb response store parts cannot be given
@@ -1394,6 +1815,10 @@ instagram:
   agent: my-agent
 telegram:
   agent: my-agent
+teams:
+  agent: my-agent
+  app_id: "<azure-app-client-id>"
+  app_password: "<azure-app-client-secret>"
 gmail:
   agent: my-agent
   poll_interval: 30
@@ -1466,6 +1891,11 @@ gmail:
   "telegram": {
     "agent": "my-agent"
   },
+  "teams": {
+    "agent": "my-agent",
+    "app_id": "<azure-app-client-id>",
+    "app_password": "<azure-app-client-secret>"
+  },
   "gmail": {
     "agent": "my-agent",
     "poll_interval": 30,
@@ -1484,19 +1914,20 @@ gmail:
 
 ### Test Configuration (test-config.yaml)
 
-Test harness configuration (comparison mode and judge 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.
+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.
 
 **test-config.yaml:**
 
 ```yaml
 mode: fallback
-judge:
+evaluator: deepeval
+llm:
   model: gpt-4o-mini
   provider: openai
   embedding_model: text-embedding-3-small
 ```
 
-Note that the file is un-nested — there is no top-level `test:` key. If the file is missing, defaults apply silently (fuzzy and fallback tests need no configuration file at all).
+Note that the file is un-nested — there is no top-level `test:` key. If the file is missing, defaults apply silently (score and fallback tests need no configuration file at all).
 
 **Override the test config file path:**
 
@@ -1507,14 +1938,13 @@ export AK_TEST_CONFIG_PATH_OVERRIDE=/path/to/test-config.yaml
 **Environment variables** use the `AK_TEST__` prefix and override `test-config.yaml` values:
 
 ```bash
-export AK_TEST__MODE=fallback  # Options: fuzzy, judge, fallback
-export AK_TEST__JUDGE__MODEL=gpt-4o-mini
-export AK_TEST__JUDGE__PROVIDER=openai
-export AK_TEST__JUDGE__EMBEDDING_MODEL=text-embedding-3-small
+export AK_TEST__MODE=fallback  # Options: score, llm, fallback
+export AK_TEST__EVALUATOR=deepeval
+export AK_TEST__LLM__MODEL=gpt-4o-mini
+export AK_TEST__LLM__PROVIDER=openai
+export AK_TEST__LLM__EMBEDDING_MODEL=text-embedding-3-small
 ```
 
-> **Migration note:** Earlier versions read test configuration from a `test:` section in `config.yaml`. That section is now ignored — move its contents (un-nested, without the `test:` key) to a sibling `test-config.yaml`. The `AK_TEST__*` environment variables are unchanged, so CI pipelines that use them need no updates.
-
 ## Extensibility
 
 ### Custom Framework Adapters