agentkernel 0.6.0__tar.gz → 0.7.0__tar.gz

{agentkernel-0.6.0 → agentkernel-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentkernel
-Version: 0.6.0
+Version: 0.7.0
 Summary: Agent Kernel - Unified AI Agents Runtime
 Author: Yaala Labs
 Author-email: Yaala Labs <agentkernel@yaalalabs.com>
@@ -12,18 +12,18 @@ Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: singleton-type>=0.0.5
 Requires-Dist: a2a-sdk[http-server]>=0.3.6 ; extra == 'a2a'
 Requires-Dist: google-adk>=1.14.1 ; extra == 'adk'
-Requires-Dist: litellm~=1.74.3 ; extra == 'adk'
+Requires-Dist: litellm~=1.89.2 ; extra == 'adk'
 Requires-Dist: openinference-instrumentation-google-adk>=0.1.6 ; extra == 'adk'
 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: pyjwt>=2.0.0 ; extra == 'auth'
+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'
 Requires-Dist: azure-data-tables>=12.4.0 ; extra == 'azure'
 Requires-Dist: azure-core>=1.26.0 ; extra == 'azure'
 Requires-Dist: chromadb>=0.4.0 ; extra == 'chromadb'
-Requires-Dist: crewai>=0.150.0 ; extra == 'crewai'
+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: google-cloud-firestore>=2.19.0 ; extra == 'gcp'
@@ -36,16 +36,22 @@ 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: langchain-community~=0.4.1 ; extra == 'langgraph'
-Requires-Dist: litellm~=1.74.9 ; 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: 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: neo4j>=5.0.0 ; extra == 'neo4j'
 Requires-Dist: openai-agents>=0.6.5 ; 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.48.0 ; extra == 'openllmetry'
+Requires-Dist: traceloop-sdk>=0.61.0 ; extra == 'openllmetry'
+Requires-Dist: pydantic-ai-slim~=2.13.0 ; extra == 'pydanticai'
+Requires-Dist: openinference-instrumentation-pydantic-ai>=0.1.17 ; extra == 'pydanticai'
 Requires-Dist: redis>=7.1.0 ; extra == 'redis'
+Requires-Dist: docker>=7.0.0 ; extra == 'sandbox-docker'
 Requires-Dist: slack-bolt==1.22.0 ; extra == 'slack'
 Requires-Dist: httpx>=0.27.0 ; extra == 'slack'
 Requires-Dist: smolagents>=1.0.0 ; extra == 'smolagents'
@@ -61,10 +67,13 @@ 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: litellm>=1.74.9 ; 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'
+Requires-Dist: valkey>=6.0.0 ; extra == 'valkey'
 Requires-Dist: walledai>=4.9.3 ; extra == 'walledai'
 Requires-Dist: httpx>=0.27.0 ; extra == 'whatsapp'
 Requires-Python: >=3.12, <3.14
@@ -82,18 +91,24 @@ Provides-Extra: gmail
 Provides-Extra: instagram
 Provides-Extra: langfuse
 Provides-Extra: langgraph
+Provides-Extra: logfire
 Provides-Extra: mcp
 Provides-Extra: messenger
+Provides-Extra: multimodal
 Provides-Extra: neo4j
 Provides-Extra: openai
 Provides-Extra: openllmetry
+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
@@ -103,19 +118,17 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://badge.fury.io/py/agentkernel.svg)](https://badge.fury.io/py/agentkernel)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 
-Agent Kernel is a lightweight **multi-cloud AI agent runtime** and adapter layer for building and running AI agents across multiple frameworks and cloud providers. Deploy the same agent code to **AWS, Azure, or GCP** without modification. Migrate your existing agents to Agent Kernel and instantly utilize pre-built execution and testing capabilities.
-
-**Supported Cloud Platforms:** AWS, Azure, GCP
+Agent Kernel is a lightweight **AI agent runtime** and adapter layer for building and running AI agents across multiple frameworks. Migrate your existing agents to Agent Kernel and instantly utilize pre-built execution and testing capabilities. Deploy the same agent code without modification — see the "Multi-Cloud Deployment" section below for supported platforms.
 
 ## Features
 
 - **Unified API**: Common abstractions (Agent, Runner, Session, Module, Runtime) across frameworks
-- **Multi-Framework Support**: OpenAI Agents SDK, CrewAI, LangGraph, Google ADK, and Smolagents
-- **Multi-Cloud Deployment**: Deploy to AWS (Lambda, ECS/Fargate), Azure (Functions, Container Apps), or GCP (Cloud Run serverless/containerized) with the same code
-- **Session Management**: Built-in session abstraction with multi-cloud storage (Redis, DynamoDB, Cosmos DB, Firestore)
+- **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`
-- **Flexible Deployment**: Interactive CLI, REST API, serverless (AWS Lambda, Azure Functions, GCP Cloud Run), containerized (AWS ECS, Azure Container Apps, GCP Cloud Run)
-- **Pluggable Architecture**: Easy to extend with custom framework adapters and cloud providers
+- **Sandbox**: Execute agent-generated code and shell commands in an isolated, permission-bounded environment with pluggable providers (`local_subprocess`, `docker`), workload profiles, policy enforcement, and per-user identity
+- **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
 - **REST API**: Built-in REST API server for agent interaction
@@ -135,6 +148,18 @@ pip install "agentkernel[neo4j]"
 pip install "agentkernel[trino]"
 ```
 
+For LLM-based thread naming with Conversation Thread Support:
+
+```bash
+pip install "agentkernel[thread]"
+```
+
+For the Docker sandbox provider (the `local_subprocess` provider needs no extra):
+
+```bash
+pip install "agentkernel[sandbox-docker]"
+```
+
 **Requirements:**
 - Python 3.12+
 
@@ -268,7 +293,9 @@ Then interact with your agents:
 
 ## Multi-Cloud Deployment
 
-Deploy your agents to AWS or Azure using the built-in cloud deployment handlers.
+**Supported Cloud Platforms:** AWS, Azure, GCP
+
+Deploy your agents to AWS, Azure, or GCP using the built-in cloud deployment handlers.
 
 ### AWS Lambda Deployment
 
@@ -431,7 +458,7 @@ Configure where agent sessions are stored (supports multi-cloud storage backends
 
 - **Field**: `session.type`
 - **Type**: string
-- **Options**: `in_memory`, `redis`, `dynamodb` (AWS), `cosmosdb` (Azure), `firestore` (GCP)
+- **Options**: `in_memory`, `redis`, `valkey` (AWS), `dynamodb` (AWS), `cosmosdb` (Azure), `firestore` (GCP)
 - **Default**: `in_memory`
 - **Environment Variable**: `AK_SESSION__TYPE`
 
@@ -457,6 +484,143 @@ Required when `session.type=redis`:
   - **Description**: Key prefix for session storage
   - **Environment Variable**: `AK_SESSION__REDIS__PREFIX`
 
+##### Valkey Configuration
+
+Required when `session.type=valkey` (requires the `agentkernel[valkey]` extra). [Valkey](https://valkey.io/)
+is the open-source, Linux Foundation-governed fork of Redis — wire-compatible with Redis and
+available on AWS ElastiCache at a lower price point than the Redis OSS engine:
+
+- **URL**
+  - **Field**: `session.valkey.url`
+  - **Default**: `valkey://localhost:6379`
+  - **Description**: Valkey connection URL. Use `valkeys://` for SSL
+  - **Environment Variable**: `AK_SESSION__VALKEY__URL`
+
+- **TTL (Time to Live)**
+  - **Field**: `session.valkey.ttl`
+  - **Default**: `604800` (7 days)
+  - **Description**: Session TTL in seconds
+  - **Environment Variable**: `AK_SESSION__VALKEY__TTL`
+
+- **Key Prefix**
+  - **Field**: `session.valkey.prefix`
+  - **Default**: `ak:sessions:`
+  - **Description**: Key prefix for session storage
+  - **Environment Variable**: `AK_SESSION__VALKEY__PREFIX`
+
+#### 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
+`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
+(falling back to a prefix of the prompt when `litellm` or an API key is unavailable). Attachments in thread
+mode additionally require `multimodal.enabled: true` with a shared attachment store (`in_memory`, `redis`, or
+`dynamodb` — `session_cache` is rejected). See `examples/api/thread-openai` and
+`examples/api/multimodal/thread-openai`.
+
+- **Field**: `thread.type`
+- **Type**: string
+- **Options**: `memory`, `redis`, `dynamodb` (AWS), `firestore` (GCP), `cosmosdb` (Azure)
+- **Default**: `memory`
+- **Environment Variable**: `AK_THREAD__TYPE`
+
+- **Naming Model**
+  - **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)
+  - **Environment Variable**: `AK_THREAD__NAMING__MODEL`
+
+- **Auto-name Max Length**
+  - **Field**: `thread.naming.max_length`
+  - **Type**: integer
+  - **Default**: `80`
+  - **Description**: Maximum length of an auto-generated thread name
+  - **Environment Variable**: `AK_THREAD__NAMING__MAX_LENGTH`
+
+##### Redis Thread Store
+
+Required when `thread.type=redis`:
+
+- **URL**
+  - **Field**: `thread.redis.url`
+  - **Default**: `redis://localhost:6379`
+  - **Description**: Redis connection URL. Use `rediss://` for SSL
+  - **Environment Variable**: `AK_THREAD__REDIS__URL`
+
+- **TTL (Time to Live)**
+  - **Field**: `thread.redis.ttl`
+  - **Default**: `2592000` (30 days)
+  - **Description**: Thread TTL in seconds (0 disables)
+  - **Environment Variable**: `AK_THREAD__REDIS__TTL`
+
+- **Key Prefix**
+  - **Field**: `thread.redis.prefix`
+  - **Default**: `ak:thread:`
+  - **Description**: Key prefix for Redis thread storage
+  - **Environment Variable**: `AK_THREAD__REDIS__PREFIX`
+
+##### DynamoDB Thread Store
+
+Used when `thread.type=dynamodb`:
+
+- **Table Name**
+  - **Field**: `thread.dynamodb.table_name`
+  - **Default**: `ak-agent-threads`
+  - **Description**: DynamoDB table name. The table must have a partition key named `session_id` (S) and a sort key named `sk` (S)
+  - **Environment Variable**: `AK_THREAD__DYNAMODB__TABLE_NAME`
+
+- **TTL (Time to Live)**
+  - **Field**: `thread.dynamodb.ttl`
+  - **Default**: `0` (disabled)
+  - **Description**: DynamoDB item TTL in seconds
+  - **Environment Variable**: `AK_THREAD__DYNAMODB__TTL`
+
+##### Firestore Thread Store
+
+Used when `thread.type=firestore`:
+
+- **Collection Name**
+  - **Field**: `thread.firestore.collection_name`
+  - **Default**: `ak-agent-threads`
+  - **Description**: Firestore collection name; each document ID is a `session_id`
+  - **Environment Variable**: `AK_THREAD__FIRESTORE__COLLECTION_NAME`
+
+- **Project ID**
+  - **Field**: `thread.firestore.project_id`
+  - **Default**: `null` (inferred from Application Default Credentials)
+  - **Environment Variable**: `AK_THREAD__FIRESTORE__PROJECT_ID`
+
+- **Database ID**
+  - **Field**: `thread.firestore.database_id`
+  - **Default**: `null` (the `(default)` database)
+  - **Environment Variable**: `AK_THREAD__FIRESTORE__DATABASE_ID`
+
+- **TTL (Time to Live)**
+  - **Field**: `thread.firestore.ttl`
+  - **Default**: `0` (disabled)
+  - **Description**: Thread TTL in seconds
+  - **Environment Variable**: `AK_THREAD__FIRESTORE__TTL`
+
+##### Cosmos DB Thread Store
+
+Required when `thread.type=cosmosdb`:
+
+- **Connection String**
+  - **Field**: `thread.cosmosdb.connection_string`
+  - **Description**: Cosmos DB connection string (Azure Portal → Keys). Uses the Table API; entities are partitioned by `session_id`. No TTL support
+  - **Environment Variable**: `AK_THREAD__COSMOSDB__CONNECTION_STRING`
+
+- **Table Name**
+  - **Field**: `thread.cosmosdb.table_name`
+  - **Default**: `akagentthreads`
+  - **Description**: Cosmos DB table name for thread storage
+  - **Environment Variable**: `AK_THREAD__COSMOSDB__TABLE_NAME`
+
 #### Execution Configuration
 
 Configure queue-backed and serverless execution behavior.
@@ -465,7 +629,7 @@ Configure queue-backed and serverless execution behavior.
   - **Field**: `execution.mode`
   - **Options**: `rest_sync`, `rest_async`, `stream`, `async`
   - **Default**: `None`
-  - **Description**: Selects the Lambda execution mode
+  - **Description**: Selects the execution mode used for queue-backed and serverless request handling
   - **Environment Variable**: `AK_EXECUTION__MODE`
 
 - **Queues**
@@ -492,6 +656,24 @@ Configure queue-backed and serverless execution behavior.
     - **Default**: `3`
     - **Environment Variable**: `AK_EXECUTION__QUEUES__OUTPUT__MAX_RECEIVE_COUNT`
 
+  - **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.
+    - **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.
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__OUTPUT__NO_OF_CONSUMERS`
+
+  - **Queue Batch Size**
+    - **Field**: `execution.queues.batch_size`
+    - **Default**: `None`
+    - **Description**: Max number of messages fetched per receive call, shared by the input and output queues. Only used by containerized deployments — never set for serverless deployments, which control batch size differently. Controlled by the deployment tooling via env var `AK_EXECUTION__QUEUES__BATCH_SIZE` — do not set in `config.yaml`.
+    - **Environment Variable**: `AK_EXECUTION__QUEUES__BATCH_SIZE`
+
 - **Response Store**
   - **Field**: `execution.response_store`
   - **Description**: Response persistence settings used by the serverless response handler
@@ -516,12 +698,17 @@ Configure queue-backed and serverless execution behavior.
     - **Field**: `execution.response_store.redis`
     - **Environment Variables**: `AK_EXECUTION__RESPONSE_STORE__REDIS__URL`, `AK_EXECUTION__RESPONSE_STORE__REDIS__PREFIX`, `AK_EXECUTION__RESPONSE_STORE__REDIS__TTL`
 
+  - **Valkey Backend**
+    - **Field**: `execution.response_store.valkey`
+    - **Environment Variables**: `AK_EXECUTION__RESPONSE_STORE__VALKEY__URL`, `AK_EXECUTION__RESPONSE_STORE__VALKEY__PREFIX`, `AK_EXECUTION__RESPONSE_STORE__VALKEY__TTL`
+    - **Description**: Valkey-backed response storage (requires the `agentkernel[valkey]` extra)
+
   - **DynamoDB Backend**
     - **Field**: `execution.response_store.dynamodb`
     - **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 either Redis 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 SQS message attributes.
+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.
 
 #### API Configuration
 
@@ -613,7 +800,7 @@ Configure tracing and observability for monitoring agent execution.
 
 - **Type**
   - **Field**: `trace.type`
-  - **Options**: `langfuse`, `openllmetry`
+  - **Options**: `langfuse`, `openllmetry`, `logfire`
   - **Default**: `langfuse`
   - **Description**: Type of tracing provider to use
   - **Environment Variable**: `AK_TRACE__TYPE`
@@ -665,31 +852,54 @@ trace:
   type: openllmetry
 ```
 
+**Pydantic Logfire Setup:**
+
+To use Logfire for tracing, install the logfire extra:
+
+```bash
+pip install agentkernel[logfire]
+```
+
+Configure the Logfire write token via an environment variable (optional — without a token, Logfire
+runs locally and does not ship traces):
+
+```bash
+export LOGFIRE_TOKEN=your-write-token
+```
+
+Enable tracing in your configuration:
+
+```yaml
+trace:
+  enabled: true
+  type: logfire
+```
+
 #### Test Configuration
 
-Configure test comparison modes for automated testing.
+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.
 
 - **Mode**
-  - **Field**: `test.mode`
+  - **Field**: `mode`
   - **Options**: `fuzzy`, `judge`, `fallback`
   - **Default**: `fallback`
   - **Description**: Test comparison mode
   - **Environment Variable**: `AK_TEST__MODE`
 
 - **Judge Model**
-  - **Field**: `test.judge.model`
+  - **Field**: `judge.model`
   - **Default**: `gpt-4o-mini`
   - **Description**: LLM model for judge evaluation
   - **Environment Variable**: `AK_TEST__JUDGE__MODEL`
 
 - **Judge Provider**
-  - **Field**: `test.judge.provider`
+  - **Field**: `judge.provider`
   - **Default**: `openai`
   - **Description**: LLM provider for judge evaluation
   - **Environment Variable**: `AK_TEST__JUDGE__PROVIDER`
 
 - **Judge Embedding Model**
-  - **Field**: `test.judge.embedding_model`
+  - **Field**: `judge.embedding_model`
   - **Default**: `text-embedding-3-small`
   - **Description**: Embedding model for similarity evaluation
   - **Environment Variable**: `AK_TEST__JUDGE__EMBEDDING_MODEL`
@@ -700,12 +910,12 @@ Configure test comparison modes for automated testing.
 - `fallback`: Tries fuzzy first, falls back to judge if fuzzy fails
 
 ```yaml
-test:
-  mode: fallback
-  judge:
-    model: gpt-4o-mini
-    provider: openai
-    embedding_model: text-embedding-3-small
+# test-config.yaml (separate file — not config.yaml)
+mode: fallback
+judge:
+  model: gpt-4o-mini
+  provider: openai
+  embedding_model: text-embedding-3-small
 ```
 
 #### Guardrails Configuration
@@ -861,6 +1071,71 @@ guardrail:
     pii: true
 ```
 
+#### Sandbox Configuration
+
+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.
+
+Minimal single-backend form (a `default` profile is synthesized from `type` + its config block):
+
+```yaml
+sandbox:
+  enabled: true
+  type: local_subprocess        # provider short name, or a dotted path to a SandboxProvider subclass
+  local_subprocess: {}
+  broker:
+    flavor: thread              # thread (local default) | embedded
+```
+
+Full form with explicit workload profiles (provider + lifetime + policy + identity):
+
+```yaml
+sandbox:
+  enabled: true
+  agents: [coder]               # optional: attach tools/prompt only to these agents; omit = all
+  default_profile: workspace
+  principal_resolver: null      # optional dotted path to a PrincipalResolver; null = agent identity
+  tool_output_max_chars: 8000
+  broker:
+    flavor: thread
+    wait_timeout: 60.0          # seconds before a sync wait promotes to a background task (0 = always)
+  profiles:
+    workspace:
+      type: docker              # container-isolated; needs the sandbox-docker extra + a Docker daemon
+      scope: per_session        # per_call | per_session | per_runtime
+      idle_timeout: 1800        # seconds of inactivity before the sandbox is reset on next touch
+      identity:
+        mode: agent             # agent | user
+      policy:
+        network_egress: deny    # allow | deny | allowlist
+        cpu: 1.0
+        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
+      docker:
+        image: python:3.12-slim
+```
+
+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), or a dotted path to your own `SandboxProvider`.
+- **`scope`** — `per_call` (fresh per execution), `per_session` (persists across turns),
+  `per_runtime` (one shared sandbox per profile).
+- **`policy`** — network egress, filesystem paths, cpu/memory, timeout; enforced per provider,
+  fail-closed under `strict`.
+- **`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).
+
+See the [Sandbox guide](https://kernel.yaala.ai/docs/next/advanced/sandbox) for the full
+reference and the `examples/sandbox` and `examples/sandbox/identity` examples.
+
 #### Messaging Platform Integrations
 
 Configure integrations with messaging platforms.
@@ -951,13 +1226,16 @@ export AK_API__PORT=8000
 export AK_A2A__ENABLED=true
 export AK_MCP__ENABLED=false
 export AK_TRACE__ENABLED=true
-export AK_TRACE__TYPE=langfuse  # or openllmetry
+export AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
 # For Langfuse:
 # export LANGFUSE_PUBLIC_KEY=pk-lf-...
 # export LANGFUSE_SECRET_KEY=sk-lf-...
 # export LANGFUSE_HOST=https://cloud.langfuse.com
 # For OpenLLMetry:
 # export TRACELOOP_API_KEY=your-api-key
+# 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
@@ -1002,13 +1280,15 @@ AK_API__PORT=8080
 AK_A2A__ENABLED=true
 AK_A2A__URL=http://localhost:8080/a2a
 AK_TRACE__ENABLED=true
-AK_TRACE__TYPE=langfuse  # or openllmetry
+AK_TRACE__TYPE=langfuse  # or openllmetry, logfire
 # Langfuse credentials (if using langfuse):
 # LANGFUSE_PUBLIC_KEY=pk-lf-...
 # LANGFUSE_SECRET_KEY=sk-lf-...
 # LANGFUSE_HOST=https://cloud.langfuse.com
 # OpenLLMetry credentials (if using openllmetry):
 # TRACELOOP_API_KEY=your-api-key
+# Logfire credentials (if using logfire):
+# LOGFIRE_TOKEN=your-write-token
 ```
 
 #### config.yaml
@@ -1020,24 +1300,37 @@ session:
     url: redis://localhost:6379
     ttl: 604800
     prefix: "ak:sessions:"
+thread: # optional — enables Conversation Thread Support (user_id becomes required on chat requests)
+  type: redis
+  redis:
+    url: redis://localhost:6379
+    ttl: 2592000
+    prefix: "ak:thread:"
 execution:
   mode: rest_sync
   queues:
     input:
-      url: https://sqs.<region>.amazonaws.com/<accountno>/<queuename>
+      url: https://queue.example.com/<accountno>/<queuename>
       max_receive_count: 3
+      no_of_consumers: 5 # Containerized deployments only, ignored by serverless deployments
     output:
-      url: https://sqs.<region>.amazonaws.com/<accountno>/<queuename>
+      url: https://queue.example.com/<accountno>/<queuename>
       max_receive_count: 3
+      no_of_consumers: 5 # Containerized deployments only, ignored by serverless deployments
+    # batch_size is set by the deployment tooling — set via AK_EXECUTION__QUEUES__BATCH_SIZE, never here
   response_store:
     type: redis
     retry_count: 5
     delay: 5
-    redis: # if this is given, then dynamodb response store part cannot be given
+    redis: # if this is given, then valkey/dynamodb response store parts cannot be given
       url: redis://localhost:6379
       prefix: "ak:responses:"
       ttl: 3600
-    dynamodb: # if this is given, then redis response store part cannot be given
+    valkey: # if this is given, then redis/dynamodb response store parts cannot be given (requires the `valkey` extra)
+      url: valkey://localhost:6379
+      prefix: "ak:responses:"
+      ttl: 3600
+    dynamodb: # if this is given, then redis/valkey response store parts cannot be given
       table_name: table-name
       table_arn: table-arn
       ttl: 3600
@@ -1058,12 +1351,8 @@ mcp:
 trace:
   enabled: true
   type: langfuse
-test:
-  mode: fallback
-  judge:
-    model: gpt-4o-mini
-    provider: openai
-    embedding_model: text-embedding-3-small
+# Note: test configuration is no longer set here — it lives in a separate
+# test-config.yaml file (see the Test Configuration section)
 guardrail:
   input:
     enabled: false
@@ -1132,14 +1421,6 @@ gmail:
     "enabled": true,
     "type": "langfuse"
   },
-  "test": {
-    "mode": "fallback",
-    "judge": {
-      "model": "gpt-4o-mini",
-      "provider": "openai",
-      "embedding_model": "text-embedding-3-small"
-    }
-  },
   "guardrail": {
     "input": {
       "enabled": false,
@@ -1187,6 +1468,39 @@ gmail:
 - Configuration file values override built-in defaults
 - Nested fields use underscore (`_`) delimiter in environment variables
 
+### 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-config.yaml:**
+
+```yaml
+mode: fallback
+judge:
+  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).
+
+**Override the test config file path:**
+
+```bash
+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
+```
+
+> **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
@@ -1228,6 +1542,7 @@ Sessions maintain state across agent interactions. Framework adapters manage the
 - `"langgraph"` — LangGraph session data
 - `"openai"` — OpenAI Agents SDK session data
 - `"adk"` — Google ADK session data
+- `"pydanticai"` — Pydantic AI session data (message history)
 
 Access the session in your runner:
 
@@ -1293,3 +1608,4 @@ SPDX-License-Identifier: Apache-2.0
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
+