LangGraph with AgentEngine Built-in Toolsets

This tutorial is distilled from a real, runnable demo. The outer LangGraph graph only does routing and context injection; the actual tool selection and invocation is delegated to a ReAct subgraph built with create_agent, which talks to KSADK built-in toolsets — Skill Space, Workspace, Sandbox, Knowledge Base, and Long-Term Memory.

It is not a "chat template". It demonstrates a transferable engineering pattern: the graph orchestrates, the model decides, the tools are hosted by AgentEngine.

Core design

The graph has four nodes:

1. route_turn — Inspects the latest user message, identifies a scenario (knowledge base / long-term memory / workspace / sandbox / skill space / graph structure / release review), and produces only a route dict. It calls no tools.
2. prepare_custom_context — Assembles custom_context from the routing hint, Skill Space IDs, and platform identity (agent_id / user_id / account_id / session_id), then injects it downstream.
3. run_specialist — Builds a ReAct subgraph with langchain.agents.create_agent, binds KSADK focused toolsets plus three custom business tools, prepends the context as a SystemMessage, and lets the model call tools autonomously.
4. finalize_answer — Walks back through the subgraph messages to find the last AIMessage and returns it as the final answer to AgentEngine.

workflow = StateGraph(AgentState)
workflow.add_node("route_turn", route_turn)
workflow.add_node("prepare_custom_context", prepare_custom_context)
workflow.add_node("run_specialist", run_specialist)
workflow.add_node("finalize_answer", finalize_answer)
workflow.add_edge(START, "route_turn")  
workflow.add_edge("route_turn", "prepare_custom_context")  
workflow.add_edge("prepare_custom_context", "run_specialist")  
workflow.add_edge("run_specialist", "finalize_answer")  
workflow.add_edge("finalize_answer", END)  

root_agent = workflow.compile()

Binding tools: focused + dispatcher

KSADK organizes built-in tools into groups. This demo directly binds only the high-frequency focused group plus agentengine_tool_dispatcher; lower-frequency or higher-risk tools (Skill, Sandbox, Knowledge Base, Long-Term Memory) are reached indirectly through the dispatcher.

FOCUSED_TOOLSETS = ["focused", "agentengine_tool_dispatcher"]  
AGENTENGINE_TOOL_DESCRIPTIONS = describe_agentengine_tools(include=FOCUSED_TOOLSETS)  

def _build_tools() -> list[BaseTool]:
    agentengine_tools = [
        tool_item
        for tool_item in get_agentengine_tools(include=FOCUSED_TOOLSETS)
        if _tool_name(tool_item) != "component_status"
    ]
    return [*agentengine_tools, graph_status, component_status, release_risk_matrix]

describe_agentengine_tools(include=...) fetches tool schemas before binding, so component_status can report "which groups are bound, which tool names each group contains" without actually invoking any tool. This is valuable for debugging and observability.

ReAct subgraph: let the model choose tools

run_specialist is the heart of the demo. It contains no if tool_name == ... branches. Instead it stuffs the routing result and context into a SystemMessage, hands the tool list to create_agent, and lets the model decide inside the ReAct loop.

def run_specialist(state: AgentState) -> dict[str, Any]:
    model = make_chat_model()
    specialist = create_agent(  
        model,
        TOOLS,
        system_prompt=SYSTEM_PROMPT,
        name="agentengine_toolsets_specialist",
    )
    route = state.get("route") or {}
    custom_context = state.get("custom_context") or {}
    messages = [  
        SystemMessage(
            content=(
                f"Outer LangGraph route: {route}. "
                f"Custom context: {custom_context}. "
                "Prefer tools from suggested_tools; when a tool is unavailable, "
                "state which environment variables are missing."
            )
        ),
        *state["messages"],
    ]
    result = specialist.invoke({"messages": messages})
    return {"specialist_messages": result.get("messages", [])}

Key pitfall: sandbox lifecycle

This is the single most valuable engineering lesson in this demo.

The correct approach is to merge "generate + read" into a single call:

• Simple operations: chain with && in run_command, e.g. python3 -c "..." && cat /home/user/outputs/x.html.
• Multi-step operations: write a script and run it once with run_code(language="bash").

This rule is written both into the system prompt and into the multi_step_hint returned by component_status, so the model can self-check before calling.

Key pitfall: e2b version vs. KSYUN UUID key

The KSYUN sandbox manager currently uses UUID-style E2B_API_KEY values. Upstream e2b>=2.25.0 enforces client-side that the key must have an e2b_ prefix, so a UUID key is rejected before any request is sent.

ksadk[langgraph,skills]>=0.6.8
# KSYUN sandbox manager currently uses UUID-style E2B_API_KEY values.
# Upstream e2b>=2.25.0 rejects those keys client-side before contacting E2B_API_URL.
e2b==2.24.0

Run steps

cd 0611agent-xiayu
uv venv
uv pip install -r requirements.txt

cp .env.example .env

uv run agentengine run -i .

uv run agentengine web .

What's the current component status? Which capabilities need extra config?
What skills are in the space?
Run python3 --version in the sandbox.
Generate /home/user/outputs/ksadk-intro.html in the sandbox and print its contents.
Search the knowledge base for deployment-related content.
Save a long-term memory: I prefer root cause before fix.

Project structure

agentengine.yaml declares the framework and entry point so AgentEngine can load root_agent:

name: 0611agent-xiayu
version: "1.0.0"
framework: langgraph
entry_point: 0611agent-xiayu/agent.py
agent_variable: root_agent

Adapting to a business agent

Further reading