### Common Setup Pattern

Source: https://kernel.yaala.ai/docs/examples/overview

Common setup pattern for all examples: install dependencies with ./build.sh, optionally use ./build.sh local for local development, then run the example with python demo.py or server.py for API examples.

```bash
# Install dependencies  

./build.sh  

  

# For local development  

./build.sh local  

  

# Run the example  

python demo.py  # or server.py for API examples  

```

--------------------------------

### Running the example

Source: https://kernel.yaala.ai/docs/examples/multi-agent

Install the required package, set the OpenAI API key, and run the script.

```bash
pip install agentkernel[crewai]  

export OPENAI_API_KEY=sk-...  

python multi_agent.py  
```

--------------------------------

### Run API Hooks Example

Source: https://kernel.yaala.ai/docs/integrations/hooks

Commands to build the environment, start the API server, and execute tests or direct examples for the API hooks demonstration.

```bash
cd examples/api/hooks  
  
# Build environment  
./build.sh  
  
# Run the API server  
source .venv/bin/activate  
python app.py  
  
# Run tests (in another terminal)  
source .venv/bin/activate  
pytest app_test.py -v  
  
# Or run direct example  
python example_usage.py  
```

--------------------------------

### Basic Slack Integration and Server Setup

Source: https://kernel.yaala.ai/docs/integrations/slack

Example of initializing an OpenAI agent and running a REST API server with the Slack handler. Requires an agent name and instructions to be defined before starting the server.

```python
from agents import Agent as OpenAIAgent  

from agentkernel.api import RESTAPI  

from agentkernel.openai import OpenAIModule  

from agentkernel.slack import AgentSlackRequestHandler  

  

# Create your agent  

general_agent = OpenAIAgent(  

    name="general",  

    handoff_description="Agent for general questions",  

    instructions="You provide assistance with general queries. Give short and clear answers",  

)  

  

# Initialize the OpenAI module with your agent  

OpenAIModule([general_agent])  

  

# Create and run the server with Slack handler  

if __name__ == "__main__":  

    handler = AgentSlackRequestHandler()  

    RESTAPI.run(handler=handler)  
```

--------------------------------

### AgentKernel CLI Example Session

Source: https://kernel.yaala.ai/docs/testing/cli-testing

A transcript showing how to start the agent, list available modules, switch between agents using !select, and manage sessions with !new and !quit.

```text
$ python my_agent.py  

  

AgentKernel CLI (type !help for commands or !quit to exit):  

Available agents:  

  research  

  write  

  review  

  

(research) >> !help  

Available commands:  

!h, !help - Show this help message  

!ld, !load <module_name> - Load agent module  

!ls, !list - List available agents  

!n, !new - Start a new session  

!c, !clear - Clear the current session memory  

!s, !select <agent_name> - Select an agent to run the prompt  

!q, !quit - Exit the program  

  

(research) >> !ls  

Available agents:  

  research  

  write  

  review  

  

(research) >> Find information about Python  

Here's what I found about Python...  

  

(research) >> !select write  

(write) >> I'll help you create a summary...  

  

(write) >> Great, can you review it?  

I'll help you create a summary of the Python information...  

  

(write) >> !select review  

(review) >> Here's my review of the content...  

  

(review) >> !new  

(review) >> This is a new session now  

How can I help you in this new session?  

  

(review) >> !quit
```

--------------------------------

### Quick Start: Install Helm chart and test deployment

Source: https://kernel.yaala.ai/docs/deployment/onprem-kubernetes

Build dependencies, install the chart with dev values and custom image settings, then port-forward and send a test request. The dev flavor runs single replicas with in-cluster NATS and Valkey.

```bash
helm dependency build ak-deployment/ak-k8s/chart  

helm install ak ak-deployment/ak-k8s/chart -f ak-deployment/ak-k8s/chart/values-dev.yaml \  
  --set ioHandler.image.repository=<io image> \  
  --set agentRunner.image.repository=<runner image> --set image.tag=<tag>  
  
  
kubectl port-forward service/ak-agent-kernel-io 8000:80  

curl -s -X POST http://localhost:8000/api/v1/chat \  
  -H 'Content-Type: application/json' \  
  -d '{"prompt": "Hello", "session_id": "s1", "agent": "triage"}'  
```

--------------------------------

### Setup Virtual Environment with Conda

Source: https://kernel.yaala.ai/docs/installation

Create and activate a conda environment, then install Agent Kernel.

```bash
# Create conda environment  

conda create -n .venv python=3.12  

  

# Activate  

conda activate .venv  

  

# Install Agent Kernel  

pip install agentkernel[openai,api]
```

--------------------------------

### Setup Virtual Environment with venv

Source: https://kernel.yaala.ai/docs/installation

Create and activate a virtual environment using venv, then install Agent Kernel.

```bash
# Create virtual environment  

python -m venv .venv  

  

# Activate (Linux/macOS)  

source .venv/bin/activate  

  

# Activate (Windows)  

.venv\Scripts\activate  

  

# Install Agent Kernel  

pip install agentkernel[openai,api]
```

--------------------------------

### Install all features

Source: https://kernel.yaala.ai/docs/installation

Installs all available frameworks, cloud providers, and optional features.

```bash
pip install agentkernel[openai,crewai,langgraph,adk,smolagents,pydanticai,api,aws,azure,gcp,cli]
```

--------------------------------

### Basic Gmail Agent Setup

Source: https://kernel.yaala.ai/docs/integrations/gmail

Initializes an OpenAI agent and starts the Gmail request handler to poll for new emails.

```python
from agents import Agent as OpenAIAgent  

from agentkernel.openai import OpenAIModule  

from agentkernel.gmail import AgentGmailRequestHandler  

import asyncio  

  
general_agent = OpenAIAgent(  

    name="general",  

    instructions="""You are an AI email assistant.  

1. Extract sender's name from the "From:" field  

2. Start response with "Hi [Name],"  

3. Address their questions professionally  

4. Keep it brief (2-3 paragraphs max)  

5. Do NOT include "Subject:" or signatures  

"""  

)  

  
OpenAIModule([general_agent])  

  
if __name__ == "__main__":  

    handler = AgentGmailRequestHandler()  

    handler.authenticate()  

    asyncio.run(handler.start_polling())
```

--------------------------------

### Basic Instagram Bot Setup with AgentKernel

Source: https://kernel.yaala.ai/docs/integrations/instagram

Complete setup for an Instagram bot using AgentKernel. Creates an OpenAI agent with Instagram-specific instructions, initializes the OpenAIModule, and starts the REST API with the Instagram request handler.

```python
from agents import Agent as OpenAIAgent  

from agentkernel.api import RESTAPI  

from agentkernel.openai import OpenAIModule  

from agentkernel.instagram import AgentInstagramRequestHandler  

  

# Create your AI agent  

instagram_agent = OpenAIAgent(  
    name="general",  
    handoff_description="Helpful Instagram assistant",  
    instructions="""You are a friendly assistant on Instagram DMs.  
    - Keep responses concise and mobile-friendly  
    - Use emojis sparingly to maintain professionalism  
    - Break long explanations into short paragraphs  
    - Be conversational and helpful  
    - Remember: Instagram DMs have a 1000 character limit per message"""  
)  

  

# Initialize the module with your agent  

OpenAIModule([instagram_agent])  

  

# Start the server with Instagram integration  

if __name__ == "__main__":  
    handler = AgentInstagramRequestHandler()  
    RESTAPI.run([handler])  

```

--------------------------------

### Basic Messenger Bot Setup

Source: https://kernel.yaala.ai/docs/integrations/messenger

Initializes an AI agent with specific instructions and starts the Messenger request handler using the RESTAPI.

```python
from agents import Agent as OpenAIAgent  

from agentkernel.api import RESTAPI  

from agentkernel.openai import OpenAIModule  

from agentkernel.messenger import AgentMessengerRequestHandler  

  

# Create your AI agent  

customer_service_agent = OpenAIAgent(  

    name="customer_service",  

    handoff_description="Helpful customer service agent",  

    instructions="""You are a friendly customer service assistant on Facebook Messenger.  

    - Keep responses concise and mobile-friendly  

    - Use emojis sparingly to maintain professionalism  

    - Break long explanations into short paragraphs  

    - Be conversational and helpful"""  

)  

  

# Initialize the module with your agent  

OpenAIModule([customer_service_agent])  

  

# Start the server with Messenger integration  

if __name__ == "__main__":  

    handler = AgentMessengerRequestHandler()  

    RESTAPI.run([handler])  
```

--------------------------------

### Install agentkernel[pydanticai]

Source: https://kernel.yaala.ai/docs/frameworks/pydantic-ai

Installs the provider-agnostic pydantic-ai-slim core, which ships no model provider. Use this as the first step before installing a specific provider.

```bash
pip install agentkernel[pydanticai]  
```

--------------------------------

### Install Framework Extras

Source: https://kernel.yaala.ai/docs/quick-start

Command to install framework-specific dependencies using pip.

```bash
pip install agentkernel[your-framework]  
```

--------------------------------

### Install multiple frameworks

Source: https://kernel.yaala.ai/docs/installation

Installs support for multiple AI frameworks simultaneously.

```bash
pip install agentkernel[openai,crewai,langgraph]
```

--------------------------------

### Example Test Session

Source: https://kernel.yaala.ai/docs/testing/cli-testing

Demonstrates a complete test session using the Test class, including starting the session, sending inputs, setting expectations, and ensuring cleanup with a try-finally block.

```python
import asyncio  

from agentkernel.test import Test  

  

async def test_cricket_knowledge():  

    test = Test("demo.py", match_threshold=0.6)  

      

    try:  

        await test.start()  

          

        # Test basic question - expected is a list  

        await test.send("Who won the 1996 cricket world cup?")  

        await test.expect(["Sri Lanka won the 1996 cricket world cup."])  

          

        # Test follow-up question with multiple acceptable answers  

        await test.send("Which country hosted the tournament?")  

        await test.expect([  

            "Co-hosted by India, Pakistan and Sri Lanka.",  

            "India, Pakistan and Sri Lanka co-hosted the tournament."  

        ])  

          

        print("All tests passed!")  

          

    finally:  

        await test.stop()  

  

if __name__ == "__main__":  

    asyncio.run(test_cricket_knowledge())
```

--------------------------------

### Install for Development

Source: https://kernel.yaala.ai/docs/installation

Clone the repository and install in development mode to contribute or modify source code.

```bash
# Clone the repository  

git clone https://github.com/yaalalabs/agent-kernel.git  

cd agent-kernel/ak-py  

  

# Install in development mode  

./build.sh  

  

# Go to any example and run  

./build.sh local
```

--------------------------------

### Install session and state stores

Source: https://kernel.yaala.ai/docs/installation

Installs dependencies for Redis or Valkey session, response, and attachment stores.

```bash
pip install agentkernel[redis]    # Redis session/response/attachment stores

pip install agentkernel[valkey]   # Valkey session/response stores (Redis fork)
```

--------------------------------

### Startup logs for in_memory transport

Source: https://kernel.yaala.ai/docs/advanced/queue-mode-guide

Example log output indicating that the in_memory queue transport has successfully resolved and the single-process pipeline is starting.

```text
ak.api.http - INFO - in_memory queue transport resolved: starting the single-process pipeline topology  

ak.pipeline.io_handler - INFO - IOHandler starting: mode=rest_sync, transport=in_memory, topology=single-process
```

--------------------------------

### Install dependencies and run the agent

Source: https://kernel.yaala.ai/docs/examples/basic-agent

Commands to install the required package, set the OpenAI API key, and execute the agent script.

```bash
# Install dependencies  

pip install agentkernel[crewai]  

  

# Set API key  

export OPENAI_API_KEY=sk-...  

  

# Run the agent  

python basic_agent.py  
```

--------------------------------

### Install multi-cloud deployment support

Source: https://kernel.yaala.ai/docs/installation

Installs dependencies for deploying to multiple cloud providers.

```bash
pip install agentkernel[aws,azure,gcp]
```

--------------------------------

### Install Pydantic AI support

Source: https://kernel.yaala.ai/docs/installation

Installs the provider-agnostic pydantic-ai-slim core. You must also install the specific provider you intend to use.

```bash
pip install agentkernel[pydanticai]
```

--------------------------------

### Install Agent Kernel with Framework Integrations

Source: https://kernel.yaala.ai/docs/advanced/traceability

Install the base package with Logfire and specific framework integrations.

```bash
# OpenAI with Logfire  

pip install agentkernel[openai,logfire]  

  

# CrewAI with Logfire  

pip install agentkernel[crewai,logfire]  

  

# Google ADK with Logfire  

pip install agentkernel[adk,logfire]
```

--------------------------------

### Install and manage Agent Skills with ak CLI

Source: https://kernel.yaala.ai/docs/agent-skills

Commands to list, install, update, and manage Agent Kernel skills for various coding assistants. Use `ak skill install --assistant <name>` to target a specific assistant, and `ak skill install <skill-name>` to install a single skill. The default assistant is GitHub Copilot, installing to `.agents/skills/`.

```bash
# List available skills  
ak skill list  

# List supported coding assistants and their skill directories  
ak skill assistants  

# Install all skills (default: GitHub Copilot → .agents/skills/)  
ak skill install  

# Install for a specific coding assistant  
ak skill install --assistant claude    # → .claude/commands/  
ak skill install --assistant cursor    # → .cursor/rules/  
ak skill install --assistant windsurf  # → .windsurf/rules/  
ak skill install --assistant codex     # → .codex/skills/  
ak skill install --assistant aider     # → .aider/skills/  

# Install a single skill  
ak skill install ak-init --assistant claude  

# Update previously installed skills to latest version  
ak skill update  
ak skill update --assistant claude  
```

--------------------------------

### Install Agent Skills

Source: https://kernel.yaala.ai/docs/agent-skills

Run this command to install Agent Skills into your project. It is the first step in the workflow.

```bash
ak skill install
```

--------------------------------

### Start MCP Server

Source: https://kernel.yaala.ai/docs/api/mcp-server

Initialize and run the REST API server to start the MCP server.

```python
from agentkernel.api import RESTAPI

if __name__ == "__main__":
    RESTAPI.run()
```

--------------------------------

### Install CLI testing tools

Source: https://kernel.yaala.ai/docs/installation

Installs dependencies for interactive command-line testing.

```bash
pip install agentkernel[cli]
```

--------------------------------

### Install Agent Kernel with Framework Integrations

Source: https://kernel.yaala.ai/docs/advanced/traceability

Install Agent Kernel with specific framework integrations and OpenLLMetry support.

```bash
# OpenAI with OpenLLMetry  

pip install agentkernel[openai,openllmetry]  

  

# LangGraph with OpenLLMetry  

pip install agentkernel[langgraph,openllmetry]  

  

# CrewAI with OpenLLMetry  

pip install agentkernel[crewai,openllmetry]  

  

# Google ADK with OpenLLMetry  

pip install agentkernel[adk,openllmetry]
```

--------------------------------

### Start and Stop a Test Session

Source: https://kernel.yaala.ai/docs/testing/cli-testing

Shows the basic async pattern for starting and stopping a test session. The test is started with await test.start(), interactions occur in between, and the session ends with await test.stop().

```python
import asyncio  

from agentkernel.test import Test  

async def run_test():  
    test = Test("demo.py")  
    await test.start()  
      
    # Your test interactions here  
      
    await test.stop()  

# Run the test  
asyncio.run(run_test())  
```

--------------------------------

### Install Agent Kernel with OpenLLMetry

Source: https://kernel.yaala.ai/docs/advanced/traceability

Install the base package with OpenLLMetry support.

```bash
pip install agentkernel[openllmetry]
```

--------------------------------

### Install optional features

Source: https://kernel.yaala.ai/docs/installation

Installs various optional features such as multimodal support, tracing, and authentication helpers.

```bash
pip install agentkernel[multimodal]  # Image/file attachment support

pip install agentkernel[thread]      # Conversation threads (LLM auto-naming)

pip install agentkernel[mcp]         # MCP server

pip install agentkernel[a2a]         # Agent-to-Agent server

pip install agentkernel[langfuse]    # Langfuse tracing

pip install agentkernel[openllmetry] # OpenLLMetry tracing

pip install agentkernel[auth]        # JWT auth helpers
```

--------------------------------

### Install Azure and OpenAI Dependencies

Source: https://kernel.yaala.ai/docs/deployment/azure-serverless

Install the necessary Agent Kernel packages with Azure and OpenAI support.

```bash
pip install agentkernel[azure,openai]
```

--------------------------------

### Install Agent Kernel with Multiple Integrations

Source: https://kernel.yaala.ai/docs/advanced/traceability

Install Agent Kernel with Langfuse alongside other framework integrations.

```bash
# OpenAI with Langfuse  

pip install agentkernel[openai,langfuse]  

  

# LangGraph with Langfuse  

pip install agentkernel[langgraph,langfuse]  

  

# CrewAI with Langfuse  

pip install agentkernel[crewai,langfuse]  

  

# Google ADK with Langfuse  

pip install agentkernel[adk,langfuse]
```

--------------------------------

### Install Docker sandbox provider

Source: https://kernel.yaala.ai/docs/advanced/sandbox

Install the required package for the Docker sandbox provider.

```bash
pip install "agentkernel[sandbox-docker]"
```

--------------------------------

### Verify Agent Kernel Installation

Source: https://kernel.yaala.ai/docs/installation

Check that the package is installed correctly by printing the version.

```bash
python -c "import agentkernel; print(agentkernel.__version__)"
```

--------------------------------

### Install Agent Kernel with all supported frameworks

Source: https://kernel.yaala.ai/docs/frameworks/multi-framework

Use this command to install Agent Kernel with support for all available frameworks including LangGraph, Google ADK, and smolagents.

```bash
pip install agentkernel[cli,crewai,openai,langgraph,google-adk,smolagents]
```

--------------------------------

### Install REST API Server

Source: https://kernel.yaala.ai/docs/installation

Installs dependencies for running agents with REST API endpoints.

```bash
pip install agentkernel[api]
```

--------------------------------

### Run the API Server

Source: https://kernel.yaala.ai/docs/quick-start

Execute the Python script to start the API server.

```bash
# Run as API server  

python my_agent.py  


```

--------------------------------

### Install pydantic-ai-slim provider extra

Source: https://kernel.yaala.ai/docs/frameworks/pydantic-ai

Installs the model provider for Pydantic AI. The comment lists alternative provider extras such as [anthropic], [google], [bedrock], and [groq]. Switching providers is a one-line change to the model string.

```bash
pip install "pydantic-ai-slim[openai]"       # or [anthropic], [google], [bedrock], [groq], ...  
```

--------------------------------

### Install Agent Kernel with UV

Source: https://kernel.yaala.ai/docs/installation

Use the UV package manager to install Agent Kernel with specific extras.

```bash
uv pip install agentkernel[openai,crewai,langgraph,api]
```

--------------------------------

### CLI Mode

Source: https://kernel.yaala.ai/docs/core-concepts/runtime

Starts the CLI, which uses the Runtime to discover and execute agents.

```python
from agentkernel.cli import CLI  

# CLI uses Runtime to discover and execute agents  
CLI.main()  

```

--------------------------------

### Verify Traceloop Setup

Source: https://kernel.yaala.ai/docs/advanced/traceability

Use this Python command to verify your OpenLLMetry/Traceloop setup. It prints 'Success' if the SDK initializes correctly.

```python

# Verify your Traceloop setup  

python -c "from traceloop.sdk import Traceloop; Traceloop.init(app_name='test'); print('Success')"  


```

--------------------------------

### Install and authenticate Daytona sandbox provider

Source: https://kernel.yaala.ai/docs/advanced/sandbox

Install the Daytona package and set the required API key environment variable.

```bash
pip install "agentkernel[daytona]"
export DAYTONA_API_KEY=dtn_...
```

--------------------------------

### EC2 SSM installation and configuration

Source: https://kernel.yaala.ai/docs/advanced/sandbox

Installs the AWS provider and configures the EC2 SSM sandbox environment.

```bash
pip install "agentkernel[aws]"  
```

```yaml
sandbox:  

  enabled: true  

  type: ec2_ssm  

  environment: attached             # required: ec2_ssm is attach-only (deliberate opt-in)  

  ec2_ssm:  

    attach_to: i-0123456789abcdef0  # existing instance id (or via AK_SANDBOX__... env override)  

    # region: us-east-1             # omitted = boto3 default  

  broker:  

    flavor: thread  
```

--------------------------------

### Install main Lambda dependencies

Source: https://kernel.yaala.ai/docs/deployment/aws-serverless

Installs the main Lambda package dependencies, including AWS and OpenAI extras.

```bash
pip install agentkernel[aws,openai]  
```

--------------------------------

### Install AG-UI dependencies

Source: https://kernel.yaala.ai/docs/api/agui-server

Install the agentkernel package with the agui extra to include the necessary protocol support.

```bash
pip install "agentkernel[agui]"
```

--------------------------------

### Install and authenticate E2B sandbox provider

Source: https://kernel.yaala.ai/docs/advanced/sandbox

Install the E2B package and set the required API key environment variable.

```bash
pip install "agentkernel[e2b]"
export E2B_API_KEY=e2b_...
```

--------------------------------

### Install agentkernel with AWS support

Source: https://kernel.yaala.ai/docs/advanced/guardrails-bedrock

Run to install the agentkernel[aws] package which includes the required boto3 library for AWS integration.

```bash
pip install agentkernel[aws]
```

--------------------------------

### Run Session Context Example

Source: https://kernel.yaala.ai/docs/integrations/hooks

Commands to build the environment, run the session context demo, and execute tests.

```bash
cd examples/cli/session-context  
  
# Build environment  
./build.sh  
  
# Run the demo  
python demo.py  
  
# Run tests (in another terminal)  
uv run pytest -s  
```

--------------------------------

### Deploy Infrastructure with Terraform

Source: https://kernel.yaala.ai/docs/deployment/gcp-containerized

Builds the example package and deploys infrastructure using Terraform: initialize, plan, and apply.

```bash
# 1. Build example package  
./build.sh  

# 2. Deploy infrastructure  
cd deploy  
terraform init  
terraform plan  
terraform apply  

```

--------------------------------

### Install Azure deployment support

Source: https://kernel.yaala.ai/docs/installation

Installs dependencies for deploying to Azure services like Functions or Container Apps.

```bash
pip install agentkernel[azure]
```

--------------------------------

### KnowledgeBuilder setup with semantic_map

Source: https://kernel.yaala.ai/docs/advanced/knowledge-bases

Demonstrates registering backends, defining a semantic map for runtime token replacement, and building KB tools.

```python
# 1) Import the pieces  

from agentkernel.knowledgebase.knowledgebuilder import KnowledgeBuilder  

from agentkernel.knowledgebase.chroma import ChromaManager  

from agentkernel.knowledgebase.neo4j import Neo4jManager  

  

# 2) Define (lightweight) backends and their schemas  

#    In real code you would supply full schema dictionaries as in the demos.  

v_db = ChromaManager(name="ChromaDB").add_schema({"description": "Vector store"})  

g_db = Neo4jManager(name="Neo4jDB").add_schema({"description": "Graph DB"})  

  

# 3) Define the semantic_map - agent prompts use the LEFT side tokens  

#    and the runtime replaces them with the RIGHT side physical targets.  

semantic_map = {  

  "<SHEETS_SOURCE>": "TABLE(kb_sheets.system.sheet(id => 'SHEET_ID'))",  # Trino/Starburst wrapper  

  "<MONGO_SOURCE>": "catalog.schema.clients",  # Example catalog.schema.table path  

}  

  

# 4) Create the KnowledgeBuilder with backends + semantic_map  

kb = KnowledgeBuilder([v_db, g_db], semantic_map=semantic_map)  

  

# 5) Build the KB tools (framework adapters bind these into agents)  

#    The exact return shape can be a list of callables; here we store as a variable.  

kb_tools = kb.build()  

  

# 6) Agent constructs a query using the logical placeholder token  

query = "SELECT client_name, status FROM <MONGO_SOURCE> WHERE status = 'active' LIMIT 5"  

  

# 7) At runtime, before the backend executes the SQL, KnowledgeBuilder  

#    replaces `<MONGO_SOURCE>` with `catalog.schema.clients` from `semantic_map`.  

#    Then `read_kb()` sends the resolved SQL to the correct Starburst backend.  

#    (In practice the agent calls the `read_kb` callable from `kb_tools`.)  

resolved_query = query.replace("<MONGO_SOURCE>", semantic_map["<MONGO_SOURCE>"])  

# read_results = read_kb("StarburstDB-mongo", resolved_query)  

  

# NOTE: Keep placeholders consistent in prompts and document required  

#       query templates in each backend's `schema()` to avoid runtime errors.
```

--------------------------------

### Initialize KnowledgeBuilder with Chroma and Neo4j

Source: https://kernel.yaala.ai/docs/advanced/knowledge-bases

Demonstrates how to instantiate backend managers, add schemas, and build the toolset using KnowledgeBuilder.

```python
from agentkernel.knowledgebase.knowledgebuilder import KnowledgeBuilder  

from agentkernel.knowledgebase.chroma import ChromaManager  

from agentkernel.knowledgebase.neo4j import Neo4jManager  

  
v_db = ChromaManager(name="ChromaDB").add_schema({...})  

g_db = Neo4jManager(name="Neo4jDB").add_schema({...})  

  
kb_tools = KnowledgeBuilder([v_db, g_db]).build()  
```

--------------------------------

### Using runners via Runtime

Source: https://kernel.yaala.ai/docs/core-concepts/runner

Runners are typically accessed through agents and invoked via the Runtime, which applies hooks and persistence. This example shows how to get the current Runtime, retrieve an agent and a session, and run the agent with a prompt using runtime.run().

```python
from agentkernel.core import Runtime  

from agentkernel.core.model import AgentRequestText  

  

runtime = Runtime.current()  

agent = runtime.agents().get("assistant")  

session = runtime.sessions().get("user-123") or runtime.sessions().new("user-123")  

  

# Preferred: run through the Runtime so hooks and persistence apply  

reply = await runtime.run(agent, session, [AgentRequestText(prompt="Hello")])  

```

--------------------------------

### Example Agent Kernel CLI session output

Source: https://kernel.yaala.ai/docs/quick-start

Shows an interactive session: the CLI defaults to the first agent (triage), starts a new session, lists available agents, selects 'math', and responds to a math query. The output includes the session ID and the agent's response.

```text
(kernel) >> Using in-memory session store  
AgentKernel CLI (type !help for commands or !quit to exit):  
(kernel) >> No agent was requested. Defaulting to first agent in the list  
(kernel) >> Selected agent: triage  
(kernel) >> Starting new session: 07ec500e-f103-4b0e-8ecb-d794232f5992  
(triage) >>  
(triage) >> !list  
Available agents:  
  triage  
  math  
  general  

(triage) >> !select math  
(math) >> What is 2 + 2?  

[math agent responds]  
(math) >> 2 + 2 = 4. This is basic addition where we combine two quantities...  

(math) >>  
```

--------------------------------

### Define and register agents across multiple frameworks

Source: https://kernel.yaala.ai/docs/frameworks/multi-framework

Demonstrates initializing agents using OpenAI, CrewAI, and LangGraph, then registering them with their respective modules.

```python
# OpenAI Agents SDK - Great for production workflows  
customer_service = OpenAIAgent(  
    name="customer_service",  
    instructions="Handle customer inquiries professionally with access to tools.",  
)  
  
# CrewAI - Excellent for role-based collaboration    
research_agent = CrewAIAgent(  
    role="researcher",  
    goal="Conduct thorough research on topics",  
    backstory="Expert researcher with attention to detail",  
)  
  
# LangGraph - Perfect for complex multi-step workflows  
workflow_agent = create_langgraph_workflow()  
  
OpenAIModule([customer_service])  
CrewAIModule([research_agent])   
LangGraphModule([workflow_agent])
```

--------------------------------

### MCP Enabled Setup

Source: https://kernel.yaala.ai/docs/core-concepts/configuration

Enables the Model Context Protocol and specifies which agents to expose.

```bash

# Enable Model Context Protocol  

export AK_MCP__ENABLED=true  

export AK_MCP__EXPOSE_AGENTS=true  

export AK_MCP__AGENTS="my-agent,another-agent"  # Specific agents  



```

--------------------------------

### Install CrewAI support

Source: https://kernel.yaala.ai/docs/installation

Installs the extras required for CrewAI.

```bash
pip install agentkernel[crewai]
```

--------------------------------

### Install AWS dependencies

Source: https://kernel.yaala.ai/docs/quick-start

Install the necessary AWS dependencies for agentkernel.

```bash
# Install AWS dependencies  

pip install agentkernel[aws]  
```

--------------------------------

### Install Guardrails Package

Source: https://kernel.yaala.ai/docs/advanced/guardrails-openai

Command to install the required guardrails package.

```bash
pip install openai-guardrails  
```

--------------------------------

### Multi-Agent Setup

Source: https://kernel.yaala.ai/docs/integrations/telegram

Configure multiple agents with specific instructions and handoff descriptions. Use OpenAIModule to register the agents for use within the application.

```python
support_agent = OpenAIAgent(  

    name="support",  

    handoff_description="Customer support agent",  

    instructions="Provide helpful customer support. Be concise for Telegram.",  

)  

  

sales_agent = OpenAIAgent(  

    name="sales",  

    handoff_description="Sales inquiry agent",  

    instructions="Help with product questions. Keep responses brief.",  

)  

  

OpenAIModule([support_agent, sales_agent])
```

--------------------------------

### Configure Storage Backends

Source: https://kernel.yaala.ai/docs/advanced/scheduling

Configuration examples for Redis, Valkey, and DynamoDB storage backends. Note that DynamoDB requires a partition key named task_id.

```yaml
# Redis
schedule:
  store:
    type: redis
    redis:
      url: redis://localhost:6379
      prefix: "ak:schedule:"
      ttl: 0                     # 0 disables expiry (the default)

# Valkey (Redis-protocol compatible; requires the `valkey` extra)
schedule:
  store:
    type: valkey
    valkey:
      url: valkey://localhost:6379

# DynamoDB — table needs partition key `task_id` (S), no sort key
schedule:
  store:
    type: dynamodb
    dynamodb:
      table_name: ak-agent-schedules
```

--------------------------------

### Knowledge Management Workflow Example

Source: https://kernel.yaala.ai/docs/core-concepts/overview

A complete flow demonstrating backend definition, composition with semantic mapping, and tool usage by an agent.

```python
from agentkernel.knowledgebase.chroma import ChromaManager  

from agentkernel.knowledgebase.neo4j import Neo4jManager  

from agentkernel.knowledgebase.knowledgebuilder import KnowledgeBuilder  

  

# 1. Define backends  

vector_store = ChromaManager(name="VectorDB", description="...")  

graph_db = Neo4jManager(name="GraphDB", description="...")  

  

# 2. Compose with semantic mapping  

kb = KnowledgeBuilder(  

    [vector_store, graph_db],  

    semantic_map={"<GRAPH>": "neo4j.default.graph"},  

)  

  

# 3. Agent uses tools  

kb.build()  # Creates get_schemas(), read_kb(), write_kb(), etc.  

  

# 4. Agent can now:  

# - Call get_schemas() to discover backends  

# - Call read_kb("GraphDB", "MATCH (n) LIMIT 5") to query the graph  

# - Call write_kb("VectorDB", text="new fact") to store knowledge  
```

--------------------------------

### Install Agent Kernel with Logfire

Source: https://kernel.yaala.ai/docs/advanced/traceability

Install the base package with Logfire support.

```bash
pip install agentkernel[logfire]
```

--------------------------------

### Install Agent Kernel with Langfuse

Source: https://kernel.yaala.ai/docs/advanced/traceability

Install the base package with Langfuse support.

```bash
pip install agentkernel[langfuse]
```

--------------------------------

### GET /a2a/{agent}/v1/card

Source: https://kernel.yaala.ai/docs/api/a2a-server

Gets the agent card for the specified agent.

```APIDOC
## GET /a2a/{agent}/v1/card

### Description
Gets the agent card for the specified agent.

### Method
GET

### Endpoint
/a2a/{agent}/v1/card

### Parameters
#### Path Parameters
- **agent** (string) - Required - The name of the agent.

### Response
#### Success Response (200)
- **name** (string) - Agent name.
- **description** (string) - Agent description.
- **endpoint** (string) - Agent endpoint.

#### Response Example
{
  "name": "agent1",
  "description": "Description of agent1",
  "endpoint": "/a2a/agent1"
}
```

--------------------------------

### Define workload profiles in sandbox configuration

Source: https://kernel.yaala.ai/docs/advanced/sandbox

Example configuration for enabling the sandbox, setting a default profile, and defining 'workspace' and 'scratch' profiles with specific scopes.

```yaml
sandbox:  

  enabled: true  

  default_profile: workspace  

  profiles:  

    workspace:                 # persistent, for multi-step work  

      type: local_subprocess  

      scope: per_session  

      idle_timeout: 21600      # 6 hours  

      local_subprocess: {}  

    scratch:                   # throwaway, one sandbox per execution  

      type: local_subprocess  

      scope: per_call  

      local_subprocess: {}  

  broker:  

    flavor: thread
```

--------------------------------

### Create Virtual Environment for Dependency Conflicts

Source: https://kernel.yaala.ai/docs/installation

Create and activate a fresh virtual environment to resolve dependency conflicts, then install the package.

```bash
python -m venv fresh-env  

source fresh-env/bin/activate  # or fresh-env\Scripts\activate on Windows  

pip install --upgrade pip  

pip install agentkernel[your-extras]  
```

--------------------------------

### Install LangGraph module

Source: https://kernel.yaala.ai/docs/frameworks/langgraph

Use pip to install the agentkernel package with the langgraph extra.

```bash
pip install agentkernel[langgraph]
```

--------------------------------

### Run a single-process IOHandler

Source: https://kernel.yaala.ai/docs/advanced/queue-mode-guide

Boots a single-process topology for local testing where the gateway handlers are co-hosted with the IO handler.

```python
from agentkernel.pipeline import IOHandler  

  

IOHandler.run(auth_validator=MyValidator())  # REST + /ws + runner + responder in one process
```

--------------------------------

### Basic WhatsApp Integration Setup

Source: https://kernel.yaala.ai/docs/integrations/whatsapp

Sets up an OpenAI agent and runs a REST API server with a WhatsApp request handler. The handler listens on /whatsapp/webhook and automatically handles WhatsApp's challenge during webhook registration.

```python
from agents import Agent as OpenAIAgent  

from agentkernel.api import RESTAPI  

from agentkernel.openai import OpenAIModule  

from agentkernel.whatsapp import AgentWhatsAppRequestHandler  

  

# Create your agent  

general_agent = OpenAIAgent(  

    name="general",  

    handoff_description="Agent for general questions",  

    instructions="You provide assistance with general queries. Give short and clear answers",  

)  

  

# Initialize the OpenAI module with your agent  

OpenAIModule([general_agent])  

  

# Create and run the server with WhatsApp handler  

if __name__ == "__main__":  

    handler = AgentWhatsAppRequestHandler()  

    RESTAPI.run(handler=handler)  
```

--------------------------------

### Install cron extra

Source: https://kernel.yaala.ai/docs/advanced/scheduling

Install the cron extra to enable cron parsing for schedules.

```bash
pip install "agentkernel[cron]"  
```

--------------------------------

### MCP Configuration Settings

Source: https://kernel.yaala.ai/docs/api/mcp-server

Example configuration block for enabling MCP, exposing agents, and setting stateless mode.

```yaml
mcp:
  enabled: true
  expose_agents: true
  agents: ['*']
  stateless_http: false  # Set to true for stateless mode (no Mcp-Session-Id)
```

--------------------------------

### Install Required Dependencies

Source: https://kernel.yaala.ai/docs/testing/automated-testing

Install the necessary pytest plugins for asynchronous testing and test ordering.

```bash
pip install pytest pytest-asyncio pytest-order
```

--------------------------------

### Initialize and Apply Terraform Deployment

Source: https://kernel.yaala.ai/docs/deployment/azure-serverless

Run the initialization and application commands to deploy the infrastructure.

```bash
terraform init && terraform apply
```

--------------------------------

### Install Agent Kernel core

Source: https://kernel.yaala.ai/docs/installation

Installs the core Agent Kernel library with minimal dependencies.

```bash
pip install agentkernel
```

--------------------------------

### Project File Structure

Source: https://kernel.yaala.ai/docs/deployment/aws-serverless

Recommended directory layout for managing separate main and authentication Lambda packages.

```text
your-project/  

├── lambda.py              # Main agent handler  

├── lambda_auth.py         # Authorizer handler  

├── build.sh               # Build script for dependencies  

├── config.yaml            # Configuration file  

├── requirements.txt       # Generated dependencies  

├── pyproject.toml         # Python project configuration  

├── deploy/  

│   ├── deploy.sh          # Deployment script  

│   ├── main.tf           # Terraform configuration  

│   ├── variables.tf      # Terraform variables  

│   ├── outputs.tf        # Terraform outputs  

│   └── terraform.tfvars  # Terraform variable values  

├── dist/                 # Main Lambda package directory  

├── dist_auth/            # Authorizer package directory  

└── dist_auth.zip         # Authorizer package zip file  
```

--------------------------------

### Install agentkernel with Smolagents support

Source: https://kernel.yaala.ai/docs/frameworks/smolagents

Install the package with the smolagents extra to enable Smolagents integration.

```bash
pip install agentkernel[smolagents]
```

--------------------------------

### Create a custom Runtime instance

Source: https://kernel.yaala.ai/docs/core-concepts/runtime

Demonstrates creating a custom runtime instance using SessionStoreBuilder and using it as a context manager to register agents and execute requests.

```python
from agentkernel.core import Runtime  

from agentkernel.core.builder import SessionStoreBuilder  

  

# Create a custom runtime instance  

custom_runtime = Runtime(SessionStoreBuilder.build())  

  

# Use it within a context  

with custom_runtime:  

    # Within this context, Runtime.current() returns custom_runtime  

    agent = MyAgent("custom-agent")  

    custom_runtime.register(agent)  

    session = custom_runtime.sessions().new("session-1")  

      

    # Execute agent with this runtime  

    from agentkernel.core.model import AgentRequestText  

    requests = [AgentRequestText(prompt="Hello")]  

    result = await custom_runtime.run(agent, session, requests)  
```

--------------------------------

### Install agentkernel[crewai]

Source: https://kernel.yaala.ai/docs/frameworks/crewai

Install the Agent Kernel CrewAI integration package using pip.

```bash
pip install agentkernel[crewai]  
```

--------------------------------

### Install OpenAI Guardrails

Source: https://kernel.yaala.ai/docs/advanced/guardrails

Install the Agent Kernel package with OpenAI support using pip.

```bash
pip install agentkernel[openai]  
```

--------------------------------

### Deploy On-Prem / Kubernetes

Source: https://kernel.yaala.ai/docs/deployment/overview

Uses the Agent Kernel Helm chart with a specific values file for the chosen flavor.

```bash
helm install ak ak-deployment/ak-k8s/chart -f values-<flavor>.yaml  
```

--------------------------------

### GET /a2a/{agent}/v1/tasks/{id}

Source: https://kernel.yaala.ai/docs/api/a2a-server

Gets a specific task by ID for the specified agent.

```APIDOC
## GET /a2a/{agent}/v1/tasks/{id}

### Description
Gets a specific task by ID for the specified agent.

### Method
GET

### Endpoint
/a2a/{agent}/v1/tasks/{id}

### Parameters
#### Path Parameters
- **agent** (string) - Required - The name of the agent.
- **id** (string) - Required - The task ID.

### Response
#### Success Response (200)
- **id** (string) - Task ID.
- **status** (string) - Task status.

#### Response Example
{
  "id": "task1",
  "status": "completed"
}
```

--------------------------------

### Full config.yaml multimodal configuration

Source: https://kernel.yaala.ai/docs/advanced/multimodal

Example configuration for enabling multimodal features and defining storage backends like in_memory, redis, or dynamodb.

```yaml
multimodal:  

  enabled: true  

  max_attachments: 10  

  description_max_length: 200  

  storage_type: in_memory          # in_memory | redis | dynamodb | session_cache  

  

  redis:  

    url: "redis://localhost:6379"  

    prefix: "ak:attachments:"  

    ttl: 3600  

  

  dynamodb:  

    table_name: "ak-attachments"  

    region: "us-east-1"  

    ttl: 3600  
```

--------------------------------

### Install Google ADK module

Source: https://kernel.yaala.ai/docs/frameworks/google-adk

Install the Agent Kernel package with the ADK extra using pip.

```bash
pip install agentkernel[adk]
```

--------------------------------

### Start REST API Server via CLI

Source: https://kernel.yaala.ai/docs/api/rest-api

Run the agent script directly from the command line interface.

```bash
python my_agent.py  
```

--------------------------------

### Enable MCP via Configuration

Source: https://kernel.yaala.ai/docs/api/mcp-server

Enable the MCP server using the configuration file.

```yaml
mcp:
  enabled: true
```

--------------------------------

### Multi-Agent Setup with OpenAIAgent and OpenAIModule

Source: https://kernel.yaala.ai/docs/integrations/instagram

Create specialized agents for sales, support, and general inquiries, then register them with OpenAIModule. The agent specified in config.yaml will be used by default.

```python
from agentkernel.instagram import AgentInstagramRequestHandler  

# Create specialized agents  
sales_agent = OpenAIAgent(  
    name="sales",  
    handoff_description="Sales and product inquiries",  
    instructions="Help customers with product information and purchase decisions."  
)  

support_agent = OpenAIAgent(  
    name="support",   
    handoff_description="Technical support and troubleshooting",  
    instructions="Provide technical assistance and resolve customer issues."  
)  

general_agent = OpenAIAgent(  
    name="general",  
    handoff_description="General questions and conversation",  
    instructions="Handle general inquiries in a friendly manner."  
)  

OpenAIModule([sales_agent, support_agent, general_agent])  

# The agent specified in config.yaml will be used by default  
```

--------------------------------

### Install AWS Bedrock Guardrails

Source: https://kernel.yaala.ai/docs/advanced/guardrails

Install the Agent Kernel package with AWS support using pip.

```bash
pip install agentkernel[aws]  
```

--------------------------------

### Basic OpenAI Agent with Agent Kernel

Source: https://kernel.yaala.ai/docs/frameworks/openai

Create a simple OpenAI agent and register it with OpenAIModule, then run the CLI.

```python
from agents import Agent as OpenAIAgent

from agentkernel.cli import CLI

from agentkernel.openai import OpenAIModule


agent = OpenAIAgent(
    name="assistant",
    instructions="You are a helpful assistant.",
)

OpenAIModule([agent])

if __name__ == "__main__":
    CLI.main()
```

--------------------------------

### Example User Interactions

Source: https://kernel.yaala.ai/docs/integrations/instagram

Demonstrates typical user-agent interactions involving image analysis, PDF text extraction, and OCR capabilities.

```text
User: "What's in this photo?" [sends image]  

Agent: [analyzes image] "This appears to be..."  

  

User: "Extract the text from this PDF" [sends PDF]  

Agent: [processes PDF] "The document contains..."  

  

User: "Can you read this note?" [sends image]  

Agent: [uses OCR] "The note says..."  
```

--------------------------------

### Install authorizer Lambda dependencies

Source: https://kernel.yaala.ai/docs/deployment/aws-serverless

Installs the authorizer Lambda package dependencies, including API and AWS extras.

```bash
pip install agentkernel[api,aws]  
```

--------------------------------

### Full JSON Configuration

Source: https://kernel.yaala.ai/docs/core-concepts/configuration

A comprehensive example of a config.json file covering logging, session management, API settings, and various integrations.

```json
{
  "logging": {
    "ak": {
      "level": "WARNING"
    },
    "system": {
      "level": "WARNING"
    }
  },
  "session": {
    "type": "redis",
    "redis": {
      "url": "redis://localhost:6379",
      "ttl": 604800,
      "prefix": "ak:sessions:"
    },
    "valkey": {
      "url": "valkey://localhost:6379",
      "ttl": 604800,
      "prefix": "ak:sessions:"
    },
    "dynamodb": {
      "table_name": "agent-kernel-sessions",
      "ttl": 604800
    }
  },
  "api": {
    "host": "0.0.0.0",
    "port": 8000,
    "custom_router_prefix": "/custom",
    "max_file_size": 10485760,
    "enabled_routes": {
      "agents": true
    }
  },
  "a2a": {
    "enabled": true,
    "url": "http://localhost:8000/a2a",
    "agents": ["*"],
    "task_store_type": "redis"
  },
  "mcp": {
    "enabled": true,
    "expose_agents": true,
    "agents": ["*"],
    "stateless_http": false
  },
  "websocket_api": {
    "connection_table": {
      "table_name": "websocket-connections",
      "ttl": 3600
    },
    "chat_route": "chat"
  },
  "execution": {
    "mode": "rest_sync",
    "queues": {
      "type": "sqs",
      "input": {
        "url": "https://sqs.us-east-1.amazonaws.com/123456789012/agent-input",
        "max_receive_count": 3,
        "no_of_consumers": 5
      },
      "output": {
        "url": "https://sqs.us-east-1.amazonaws.com/123456789012/agent-output",
        "max_receive_count": 3,
        "no_of_consumers": 2
      }
    },
    "response_store": {
      "type": "redis",
      "retry_count": 5,
      "delay": 5,
      "redis": {
        "url": "redis://localhost:6379",
        "prefix": "ak:responses:",
        "ttl": 604800
      },
      "valkey": {
        "url": "valkey://localhost:6379",
        "prefix": "ak:responses:",
        "ttl": 604800
      },
      "dynamodb": {
        "table_name": "agent-responses",
        "ttl": 604800
      }
    }
  },
  "slack": {
    "agent": "",
    "agent_acknowledgement": ""
  },
  "whatsapp": {
    "agent": "",
    "agent_acknowledgement": "",
    "verify_token": "",
    "access_token": "",
    "app_secret": "",
    "phone_number_id": "",
    "api_version": "v24.0"
  },
  "messenger": {
    "agent": "",
    "verify_token": "",
    "access_token": "",
    "app_secret": "",
    "api_version": "v24.0"
  },
  "instagram": {
    "agent": "",
    "verify_token": "",
    "access_token": "",
    "app_secret": "",
    "instagram_account_id": "",
    "api_version": "v21.0"
  },
  "telegram": {
    "agent": "",
    "bot_token": "",
    "webhook_secret": "",
    "api_version": "bot"
  },
  "teams": {
    "agent": "",
    "agent_acknowledgement": "",
    "app_id": "",
    "app_password": "",
    "tenant_id": ""
  },
  "guardrail": {
    "input": {
      "enabled": false,
      "type": "openai",
      "model": "gpt-4o-mini",
      "config_path": ""
    },
    "output": {
      "enabled": false,
      "type": "openai",
      "model": "gpt-4o-mini",
      "config_path": ""
    }
  },
  "logging": {  // Optional - if omitted, default loggers will not be overridden  
    "ak": {
      "level": "WARNING"
    },
    "system": {
      "level": "WARNING"
    }
  }
}
```

--------------------------------

### Install Package Extras

Source: https://kernel.yaala.ai/docs/installation

Install specific extras to resolve import errors related to external agent frameworks.

```bash
# If using OpenAI Agents  

pip install agentkernel[openai]  

  

# If using CrewAI  

pip install agentkernel[crewai]  
```

--------------------------------

### Configure Valkey High Availability and SSL

Source: https://kernel.yaala.ai/docs/core-concepts/session

Examples for connecting to a Valkey cluster endpoint and enabling SSL/TLS encryption.

```bash
# ElastiCache for Valkey endpoint  

export AK_SESSION__VALKEY__URL=valkey://cluster-endpoint:6379  

  

# Enable SSL/TLS  

export AK_SESSION__VALKEY__URL=valkeys://secure-endpoint:6380  
```

--------------------------------

### Install Walled AI Guardrails

Source: https://kernel.yaala.ai/docs/advanced/guardrails

Install the Agent Kernel package with Walled AI support using pip.

```bash
pip install agentkernel[walledai]  
```

--------------------------------

### Test Input Example

Source: https://kernel.yaala.ai/docs/advanced/guardrails

Example input to test guardrails, showing a prompt that may trigger safety filters.

```text
(assistant) >> Tell me how to hack into a system  
```

--------------------------------

### Install Agent Kernel with Python 3.12

Source: https://kernel.yaala.ai/docs/installation

Use the explicit python3.12 command to install the package if multiple Python versions are present.

```bash
python3.12 -m pip install agentkernel  
```