Frameworks

KsADK supports common Python agent framework families through runtime adapters. The public contract is simple: expose an agent object, declare the framework, and run the project through agentengine.

Supported Families

Framework Runtime Architecture

KsADK treats every framework adapter as a small boundary around the user's native agent object. The local server, Web UI, session store, and OpenAI-compatible endpoints do not call framework-specific APIs directly. They call the runner contract, and the runner owns the framework details.

The important design point is that framework detection is static while runner loading is executable. Detection reads config files and source text; loading imports the configured module and validates the exported object. That keeps diagnostics clear: a project that cannot be detected has a packaging/config problem, while a project that detects correctly but fails to load has an import, dependency, or exported-object problem.

Google ADK

KsADK keeps the ADK programming model intact. The application still exports a Google ADK Agent; KsADK detects the project, imports the configured object, wraps it in the local runner, and exposes the same local CLI, Web UI, and HTTP protocols used by other framework families.

from google.adk.agents import Agent

def hello(name: str) -> dict:
    return {"message": f"Hello, {name}!"}

root_agent = Agent(
    name="hello_agent",
    description="Minimal ADK example",
    instruction="You are a helpful assistant.",
    tools=[hello],
)

Project config:

name: hello-agent
framework: adk
entry_point: agent.py
agent_variable: root_agent

Recommended setup:

python -m venv .venv
source .venv/bin/activate
pip install -U "ksadk[adk]"
agentengine run . -i
agentengine web . --no-open

Common ADK loading failures:

LangGraph

from langgraph.graph import END, StateGraph

class State(TypedDict):
    messages: Annotated[list, operator.add]

llm = ChatOpenAI(model="my-model", base_url="https://api.example.com/v1", api_key="sk-test")

def chat(state: State):
    return {"messages": [llm.invoke(state["messages"])]}

graph = StateGraph(State)
graph.add_node("chat", chat)
graph.set_entry_point("chat")
graph.add_edge("chat", END)

root_agent = graph.compile()

Project config:

name: langgraph-agent
framework: langgraph
entry_point: agent.py
agent_variable: root_agent

LangChain

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="my-model", base_url="https://api.example.com/v1", api_key="sk-test")
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant."),
    ("human", "{input}"),
])

root_agent = prompt | llm | StrOutputParser()

Project config:

name: langchain-agent
framework: langchain
entry_point: agent.py
agent_variable: root_agent

DeepAgents

llm = ChatOpenAI(model="my-model", base_url="https://api.example.com/v1", api_key="sk-test")
root_agent = create_deep_agent(model=llm)

Project config:

name: deep-agent
framework: deepagents
entry_point: agent.py
agent_variable: root_agent

Detection Order

KsADK first checks explicit project configuration. If no config file exists, it tries common project shapes:

• a package with agent.py, main.py, or app.py
• a package __init__.py that exports common agent variables
• a script-style project with agent.py, main.py, or app.py

Detection Details

Detection is a static step. It reads configuration files and source text, but it does not execute the user agent module. That keeps framework detection separate from framework loading.

The detection result carries these values into the runner factory:

If a configured entry file exists but does not export the configured variable, fix the export or the agent_variable setting. Do not work around this by adding import side effects that create global state indirectly.

Detection To Runner Pipeline

Explicit configuration is the recommended path for public examples, but the detector also supports convention-based projects. The pipeline below is useful when reviewing examples or debugging why a project was loaded as the wrong framework.

The runner factory applies a small LangChain compatibility patch, then creates one of the concrete runners. This is intentionally a narrow switch instead of a plugin registry: the public contract is easier to audit, and new framework families can be reviewed as explicit additions.

Runner Loading Behavior

Each runner keeps the framework's native execution model:

The adapters normalize the result into {"output": ...} for non-streaming calls and semantic chunks for streaming calls. They do not rewrite the user's agent into a different framework.

Runner Responsibilities

All framework adapters implement the same public responsibilities:

This keeps the HTTP server and Web UI independent from framework-specific objects. Framework-specific behavior belongs in the adapter or in the application's own hook functions.

Custom Input Hooks

LangGraph and LangChain applications often use custom state shapes. Add a hook in the configured entry module when the default mapping is not enough:

def ksadk_prepare_state(payload: dict, session_context: dict) -> dict:
    return {
        "messages": payload.get("input_messages", []),
        "question": payload.get("input", ""),
        "knowledge": session_context.get("kb_context"),
        "memory": session_context.get("memory_context"),
    }

def ksadk_prepare_input(payload: dict, session_context: dict) -> dict:
    return {
        "question": payload.get("input", ""),
        "history": session_context.get("history", []),
        "attachments": payload.get("attachment_results", []),
    }

Hooks make examples easier to test because business code receives a stable, explicit dictionary instead of reading local UI events or session internals.

Model Overrides

Requests can provide a model override through the CLI or HTTP payload. KsADK normalizes the requested model and calls the runner before execution. The effect depends on the framework:

For deterministic examples, set a default model in .env or your provider configuration, then use request-level overrides only when you need to test model selection.

Session Continuity

Frameworks differ in how much native session state they expose. KsADK describes that capability through runner session adapters:

Transcript replay is the portable baseline. Native checkpoint or session paths are useful when the framework supports them, but examples should still behave reasonably when only transcript replay is available.

Local Invocation

All framework examples should support the same local commands:

agentengine run . -i
agentengine web . --no-open