ak-dev-architecture

Agent Kernel Architecture

Design Principles

1. Framework-agnostic core: All core abstractions (Session, Agent, Tool, Runner, Module, Runtime) are framework-independent. Framework-specific logic lives exclusively in adapter modules under ak-py/src/agentkernel/framework/.
2. Adapter pattern: Each supported agent framework (OpenAI Agents SDK, CrewAI, LangGraph, Google ADK, Smolagents, and Pydantic AI) implements Agent, Tool, Runner, and Module subclasses that wrap native framework objects.
3. Config-driven behavior: All runtime behavior is governed by AKConfig (Pydantic-based), loaded from YAML/JSON files and environment variables (AK_ prefix, __ for nesting).
4. Session lifecycle: Sessions are async context managers providing concurrency-safe state management. Session stores are pluggable (in-memory, Redis, Valkey, DynamoDB, Cosmos DB, Firestore). Session stores also provide the WebSocket gateway's WSConnectionStore on their backend via SessionStore.get_connection_store() (spec #495 §9): the ABC lives beside SessionStore in core/session/base.py, and each store file carries (or explicitly declines) its implementation, encapsulating its database operations over the shared drivers: InMemoryWSConnectionStore (in_memory.py, process-wide class-level state), RedisLikeWSConnectionStore (core/session/redis_like.py, client-library-agnostic; constructed by the redis/valkey stores with their own drivers), DynamoDBWSConnectionStore (dynamodb.py, over an existing table named by session.connection_store.table_name, same schema as the AWS adapters' connections table); cosmosdb/firestore raise actionably, as does the base default (so pre-method BYO stores keep working until a WS mode is enabled). Kafka's retry/dedup bookkeeping keeps its own session-type factory in pipeline/transport/bookkeeping.py (Q5).
5. Plugin architecture: Tools, hooks, guardrails, tracing providers, session stores, knowledge base backends, sandbox providers, and messaging integrations are all pluggable via well-defined interfaces. Backend-selection factories (guardrail, trace, session/thread/multimodal stores, sandbox provider) share one shape via core/util/factory.py (resolve_dotted, require_extra, AKConfigError): built-ins resolved by if/elif + real imports, with a dotted-path "bring your own" branch on every surface.
6. Minimal coupling: Integrations (Slack, WhatsApp, etc.), deployment adapters (AWS Lambda, Azure Functions, Google Cloud Run), and API layers (REST, MCP, A2A) depend on the core but the core never depends on them. The queue pipeline (pipeline/) imports only core and api; deployment/ imports pipeline; modules relocated into pipeline/ leave re-export shims at their old paths that must preserve existing patch targets (see the Queue Execution Pipeline section).
7. Queue-pipeline execution (#495): chat execution on server surfaces runs through one five-component pipeline: Request Handler → Input Queue → Agent Runner → Output Queue → Response Handler: with the queue transport (execution.queues.type: in_memory default, sqs, kafka, nats) and process topology selected by configuration.