Open Agent Kernel (OAK) is the open-source runtime for scalable, compliant AI agents. Build agents in the framework you already use, and OAK runs them on AWS, Azure, GCP or Kubernetes, with sessions, guardrails, identity, tracing and messaging channels supplied by the platform.
Documentation · Quick start · Capabilities · Architecture · Deployment · Examples · Community · Contributing
Agent frameworks are good at defining an agent: its prompt, its tools and its handoffs. Putting that agent in front of users is a separate job. It needs an API, session state, authentication, guardrails, tracing, a deployment topology, and often a Slack or WhatsApp front end. Teams usually end up writing that layer themselves, then rewriting it when the framework or the cloud changes.
OAK is that layer. You keep writing agents in the framework you already use and register them with an OAK module. The runtime supplies the rest.
- Framework-agnostic. Agents built with OpenAI Agents SDK, LangGraph, CrewAI, Google ADK, Smolagents, Pydantic AI, Microsoft Agent Framework and Claude Agent SDK run on the same runtime, and agents from different frameworks can run side by side.
- Cloud-agnostic. The same agent code runs as a local CLI, a REST container, on AWS Lambda or ECS, Azure Container Apps, GCP Cloud Run, or any Kubernetes cluster.
- Configured, not coded. Session stores, guardrails, identity, secrets, tracing and sandboxing are switched on in
config.yamlor throughAK_environment variables. - Open. Apache 2.0 licensed, with MCP, A2A, AG-UI and A2UI support built in.
OAK is not a replacement for your agent framework, and it is not another heavy abstraction to learn. It is a thin adapter around the agents you already have.
You need Python 3.12 or 3.13 and uv. This example uses the OpenAI Agents SDK. The quick start guide has the same steps for every supported framework.
uv init --python 3.12 my-agent
cd my-agent
uv add "agentkernel[openai]"If you use pip, pip install "agentkernel[openai]" installs the same package.
Create my_agent.py:
from agents import Agent as OpenAIAgent
from agentkernel.cli import CLI
from agentkernel.openai import OpenAIModule
# Define agents with the framework's own API
general_agent = OpenAIAgent(
name="general",
handoff_description="Agent for general questions",
instructions="You provide assistance with general queries. Give short and direct answers.",
)
math_agent = OpenAIAgent(
name="math",
handoff_description="Specialist agent for math questions",
instructions="You provide help with math problems. Explain your reasoning.",
)
# Register them with OAK
OpenAIModule([general_agent, math_agent])
if __name__ == "__main__":
CLI.main()Run it:
export OPENAI_API_KEY=your-api-key-here
uv run python my_agent.pyThis opens an interactive CLI. Type a prompt to talk to the selected agent, !list to see the registered agents, !select math to switch, and !quit to exit.
To serve the same agents over HTTP, add the api extra with uv add "agentkernel[api]", import RESTAPI from agentkernel.api, and replace CLI.main() with RESTAPI.run(). The server listens on port 8000 by default:
curl -X POST http://localhost:8000/api/v1/chat \
-H "Content-Type: application/json" \
-d '{"agent": "general", "prompt": "Hello!"}'Every agent request passes through six stages, and each one is switched on with a few lines of configuration. The features page covers them in depth.
| Stage | What OAK provides | Docs |
|---|---|---|
| Build | Adapters for OpenAI Agents SDK, LangGraph, CrewAI, Google ADK, Smolagents, Pydantic AI, Microsoft Agent Framework and Claude Agent SDK, including several in one runtime. Tools written once and bound to any framework, pre and post execution hooks, multi-agent patterns, and image and file input | Frameworks, Tools, Hooks, Multi-agent, Multimodal |
| Connect | An interactive CLI, a REST API with SSE streaming and WebSocket delivery. An agent catalog, A2A cards and MCP tools built from one descriptor per agent. MCP and A2A servers, AG-UI event streaming and A2UI generative UI documents. Slack, WhatsApp, Microsoft Teams, Telegram, Gmail, Messenger and Instagram, plus LiveKit voice for OpenAI Agents SDK and Google ADK agents | REST API, MCP, A2A, AG-UI, A2UI, Integrations |
| Remember | Pluggable session stores, persistent conversation threads, and request-scoped and session-scoped caches. ChromaDB, Neo4j, Starburst Galaxy and Open Knowledge Format bundles behind one KnowledgeBase interface |
Sessions, Memory backends, Threads, Knowledge bases |
| Guard | Input and output guardrails, one identity provider for every surface, secret resolution from a managed store, runs that pause for a person's approval or answer, and sandboxed code execution | Guardrails, Identity, Secrets, Human in the loop, Sandbox |
| Scale | A queued pipeline for every chat request: in-process by default, and over SQS, Kafka, NATS JetStream, Google Cloud Pub/Sub or Azure Service Bus in distributed deployments. Serverless and containerized targets on AWS, Azure, GCP and Kubernetes, and deferred and recurring chats | Queue mode, Deployment, Scheduling |
| Observe | Tracing of agent runs, with LLM and tool calls where the framework supports it, in Langfuse, OpenLLMetry, Pydantic Logfire or AWS CloudWatch. A pytest-integrated test framework with score, LLM-judge and fallback comparison modes | Traceability, Testing |
Supported backends and providers
| Layer | Options |
|---|---|
| Session, memory and conversation thread stores | In-memory, Redis, Valkey, DynamoDB (AWS), Cosmos DB (Azure), Firestore (GCP) |
| Knowledge bases | ChromaDB (vector), Neo4j (graph), Starburst Galaxy (SQL analytics on Trino), Open Knowledge Format bundles (markdown from a local directory or S3), or your own KnowledgeBase adapter |
| Queue transports | In-process (default), SQS, Kafka, NATS JetStream, Google Cloud Pub/Sub, Azure Service Bus |
| Guardrails | OpenAI Guardrails, AWS Bedrock Guardrails, Walled AI |
| Identity providers | Any OIDC issuer (Auth0, Keycloak, Okta), Amazon Cognito, Microsoft Entra ID, Firebase, a static credential map, or your own class |
| Secret providers | Environment, AWS SSM Parameter Store, mounted Kubernetes Secrets, or your own provider |
| Sandbox providers | local_subprocess, docker, kubernetes, e2b, daytona, ec2_ssm, or your own via a dotted path |
| Scheduling | local in-process timers or AWS EventBridge Scheduler, with task records in memory, Redis, Valkey or DynamoDB |
| Test evaluators | DeepEval (default), Opik, JEV, or your own evaluator |
Human in the loop, scheduling and sandboxing
- Human in the loop. A run can stop to ask a person for an approval or an answer, then resume from their decision minutes or hours later, on any replica. OAK returns HTTP 202 with
status: "PAUSED"and the client answers with aresumeblock. OpenAI Agents SDK, LangGraph, Pydantic AI, Google ADK, Microsoft Agent Framework and Claude Agent SDK agents can pause, over REST, streaming, WebSocket and AG-UI, with Approve and Deny buttons in Slack and Telegram. - Deferred and recurring chats. A
scheduleblock in config turns on scheduling with no code change. A chat is deferred by ascheduleblock on the request (acknowledged with HTTP 202), by the agent's owncreate_scheduletool, or by a directScheduleManagercall. Tasks can be listed, amended, paused and cancelled over/api/v1/schedules. - Sandboxed code execution. Enabling the sandbox in config gives agents code, command and file tools that run in an isolated environment. Workload profiles set the sandbox lifetime (per call, per session or shared) and a permission policy that is enforced fail-closed: network egress, filesystem, CPU and memory, timeout, languages and package installs. Code can run under the invoking user's identity instead of one shared agent identity.
OAK sits between your agent logic and the surfaces that expose it. Requests arrive from a channel or an API, pass through the runtime, and reach your agent through a thin adapter for its framework. The same stack runs on a laptop and on every target in the bottom row.
flowchart TB
subgraph surfaces["Channels and APIs"]
direction TB
cli["CLI"]
http["REST, SSE, WebSocket"]
proto["MCP, A2A, AG-UI"]
chat["Slack, WhatsApp, Teams,<br/>Telegram, Gmail and more"]
end
subgraph oak["OAK runtime"]
direction TB
pipeline["Queue execution pipeline"]
state["Sessions, memory, threads"]
policy["Hooks, guardrails, identity"]
trace["Tracing"]
end
subgraph adapters["Framework adapters"]
direction TB
f1["OpenAI Agents SDK"] ~~~ f5["Smolagents"]
f2["LangGraph"] ~~~ f6["Pydantic AI"]
f3["CrewAI"] ~~~ f7["Microsoft Agent Framework"]
f4["Google ADK"] ~~~ f8["Claude Agent SDK"]
end
subgraph targets["Runs on"]
direction TB
aws["AWS<br/>Lambda, ECS Fargate"]
azure["Azure<br/>Container Apps"]
gcp["GCP<br/>Cloud Run"]
k8s["Kubernetes<br/>Helm chart"]
end
surfaces --> oak --> adapters
adapters ~~~ targets
style oak stroke:#FF5E32,stroke-width:2px
Every adapter exposes the same five abstractions: Agent, Runner, Session, Module and Runtime. The architecture overview describes each layer.
The same agent code runs on every target. Terraform modules cover AWS, Azure and GCP, and a Helm chart covers Kubernetes and on-prem clusters.
| Platform | Serverless | Containerized | Guides |
|---|---|---|---|
| AWS | Lambda | ECS Fargate | Serverless, Containerized |
| Azure | Not offered (Functions is retired, see #957) | Container Apps, in one container or split over Service Bus | Containerized |
| GCP | Cloud Run, scale to zero | Cloud Run, always on | Serverless, Containerized |
| Kubernetes and on-prem | Not applicable | Helm chart for bare metal and EKS, with Kafka or NATS queue mode and KEDA autoscaling | Kubernetes |
The Terraform modules are also published on the Terraform Registry. The deployment overview compares execution modes and protocol support across targets.
The chart is published as an OCI artifact at ghcr.io/yaalalabs/charts/agent-kernel. Install it with Helm (the docker pull command GitHub shows on the package page does not apply to charts):
helm pull oci://ghcr.io/yaalalabs/charts/agent-kernel --version 0.10.2 --untar # unpacks the flavor values files
helm install ak oci://ghcr.io/yaalalabs/charts/agent-kernel --version 0.10.2 \
-f agent-kernel/values-dev.yaml \
--set ioHandler.image.repository=<io image> \
--set agentRunner.image.repository=<runner image> --set image.tag=<tag>Flavors are values files over one set of templates: values-dev.yaml for a local cluster, values-baremetal.yaml for self-hosted clusters and values-eks.yaml for AWS EKS. Valkey and NATS ship as bundled dependencies, and every image the chart references is listed in the images.txt attached to each release for air-gapped mirroring.
OAK ships skills that teach a coding assistant (Claude Code, GitHub Copilot, Cursor, Windsurf, Codex or Aider) how to build on it, so the code it writes follows the real APIs. The ak CLI that installs them comes with the agentkernel package.
ak skill install # GitHub Copilot by default
ak skill install --assistant claude # or cursor, windsurf, codex, aiderSix skills cover the path from an empty directory to a deployed agent: ak-init scaffolds a project, ak-build adds tools, agents and handoffs, ak-add-capabilities wires in guardrails, tracing, sessions and the other platform features, ak-add-integration adds a messaging channel, ak-cloud-deploy generates the Terraform or Helm deployment, and ak-test sets up tests. The agent skills guide has the details, and use-cases/ holds complete agents built this way, each starting from a SPEC.md.
Full documentation lives at kernel.yaala.ai/docs. Good starting points are installation, core concepts, configuration, the framework guides and the deployment guides.
The site also has a guided tour for each kind of reader:
| If you are | Start with | What it covers |
|---|---|---|
| A business leader | The outcome | Where agents pay off, what OAK is in plain words, and what adopting it commits you to |
| A developer | The code | The route from an empty folder to an agent that is deployed and tested |
| An AI engineer | The runtime | How OAK compares, where it sits in a request, and the memory, hook and queue machinery |
Use cases shows what teams build with OAK, What's new lists the latest capabilities, and the blog covers each release in depth.
The examples/ directory holds runnable projects, grouped by how they run. The examples overview describes each one.
cli/: one project per framework, plus guardrails, knowledge bases, tracing and test evaluatorsapi/: REST, MCP, A2A, AG-UI, human in the loop, scheduling and each messaging channelaws-serverless/,aws-containerized/,azure-containerized/,gcp-serverless/,gcp-containerized/andk8s/: deployable projects for each targetmemory/,sandbox/andtransport/: session stores, sandbox providers and queue transports
Join the community on Discord for questions and discussion, and report bugs or request features through GitHub Issues. If OAK is useful to you, a star on GitHub helps other people find it.
OAK is a member of the Linux Foundation and the Agentic AI Foundation.
Contributions are welcome. CONTRIBUTING.md covers the workflow, commit format and pull request checklist, and DEVELOPER_GUIDE.md covers local setup. If you work with an AI coding agent, point it at AGENTS.md. Everyone taking part is expected to follow the Code of Conduct.
Please do not report security vulnerabilities through public GitHub issues. SECURITY.md explains how to report them privately and what to expect in response.
Unless otherwise specified, all content in this repository, including source and documentation files, is Copyright (c) 2025-2026 Yaala Labs and licensed under the Apache License, Version 2.0. See NOTICE for attribution.
SPDX-License-Identifier: Apache-2.0