Developer docs / AI Fabric tutorials

Sandboxed LangGraph agent

  • Sandbox
  • GPU
  • LangGraph
  • Web endpoint

Once a coding agent grows past a single if-statement, you want the control flow to be explicit rather than buried in a for loop. LangGraph gives you that: you describe the agent as a small state machine (nodes that do work, edges that decide what happens next) and let the framework drive it.

In this tutorial you'll build a LangGraph StateGraph agent whose only tool is a disposable AI Fabric sandbox. The graph loops generate → execute → retry: the LLM runs on a GPU and writes code, that code runs in a throwaway gVisor sandbox, and a failure routes back to generate. Untrusted code never touches the agent process.

Before you start

Make sure the AI Fabric CLI is installed and authenticated (blade setup). The agent runs the LLM on a single RTX A4500. Two images are built for you: the agent runs on fabric/torch plus LangGraph, and the generated code runs in a small debian_slim sandbox image.

Set up the app and two images

Create sandbox_langgraph.py. As with any sandboxed agent, you keep two environments apart: a heavy one for the LLM and LangGraph, and a minimal one for the code the agent writes. The sandbox image carries only numpy and sympy: enough for the code, nothing more:

sandbox_langgraph.py
import bladekit

app = bladekit.app("sandbox-langgraph")

# The agent (LLM + LangGraph) runs in this GPU container.
agent_image = (
    bladekit.Image.from_catalog("fabric/torch")
    .pip_install("transformers", "accelerate", "langgraph", "langchain-core")
)

# The generated code runs HERE, in an isolated gVisor sandbox, not the agent.
sandbox_image = (
    bladekit.Image.debian_slim(python_version="3.12")
    .pip_install("numpy", "sympy")
)

MODEL_ID = "Qwen/Qwen2.5-1.5B-Instruct"
MAX_ATTEMPTS = 3

# Loaded once per container, reused across calls that land on it.
_llm = None

Write the sandbox tool

The agent's one and only tool is a function that runs a code string in a fresh sandbox and reports back whether it worked. Return a simple (ok, text) tuple: stdout when it succeeds, truncated stderr when it doesn't:

Python
def run_in_sandbox(code: str) -> tuple[bool, str]:
    """Execute code in a throwaway gVisor sandbox; return (ok, stdout-or-stderr)."""
    with bladekit.Sandbox.create(image=sandbox_image, timeout=20) as sb:
        sb.write_file("/work/tool.py", code.encode())
        proc = sb.exec("python", "/work/tool.py")
        proc.wait()
        if proc.returncode == 0:
            return True, proc.stdout.read().decode()
        return False, proc.stderr.read().decode()[:500]

Define the graph's state and nodes

Inside the endpoint, load the model once into the module global and declare the typed state the graph threads through every node. The generate node prompts the model (replaying the last error on retries) and extracts the code from a fenced block:

Python
@app.web_endpoint(methods=["POST"], min_replicas=0, max_replicas=2)
@app.function(gpu="RTX-A4500", image=agent_image, timeout=300)
def run(item: dict) -> dict:
    """Build a tiny LangGraph agent (generate → execute → retry) over a sandbox."""
    import re
    from typing import TypedDict

    from langgraph.graph import END, StateGraph
    from transformers import pipeline

    global _llm
    if _llm is None:
        _llm = pipeline("text-generation", model=MODEL_ID, device=0)

    class State(TypedDict):
        task: str
        code: str
        output: str
        error: str
        attempts: int

    def generate(state: State) -> dict:
        instruction = f"Write Python code to: {state['task']}\n"
        if state.get("error"):
            instruction += f"The previous attempt failed:\n{state['error']}\nFix it.\n"
        instruction += "Output ONLY the code in a ```python block."
        messages = [{"role": "user", "content": instruction}]
        raw = _llm(messages, max_new_tokens=256, do_sample=False)[0]["generated_text"]
        reply = raw[-1]["content"] if isinstance(raw, list) else str(raw)
        m = re.search(r"```(?:python)?\s*\n(.*?)```", reply, re.DOTALL)
        code = (m.group(1) if m else reply).strip()
        return {"code": code, "attempts": state["attempts"] + 1}

Each node returns a dict of updates. LangGraph merges it into the running state rather than replacing it. That's why generate only returns code and attempts: the rest of the state carries over untouched.

Execute, then route on the result

The execute node calls your sandbox tool and records whether it errored. The route function is the conditional edge: it sends the agent back to generate while the code still errors and attempts remain, otherwise it ends:

Python
    def execute(state: State) -> dict:
        ok, out = run_in_sandbox(state["code"])
        return {"output": out, "error": "" if ok else out}

    def route(state: State) -> str:
        # Retry (back to generate) while the code errors and we have attempts left.
        if state["error"] and state["attempts"] < MAX_ATTEMPTS:
            return "generate"
        return END

Wire and compile the graph

Assemble the pieces: generate is the entry point, it always flows into execute, and execute branches through route. Compiling turns the description into a runnable agent:

Python
    graph = StateGraph(State)
    graph.add_node("generate", generate)
    graph.add_node("execute", execute)
    graph.set_entry_point("generate")
    graph.add_edge("generate", "execute")
    graph.add_conditional_edges("execute", route, {"generate": "generate", END: END})
    agent = graph.compile()

Invoke it and return the result

Pull the task from the request, seed the initial state with empty fields and attempts: 0, and invoke the compiled graph. It loops internally until route returns END, then you shape the final state into a response:

Python
    task = item.get("task", "compute the first 10 prime numbers")
    final = agent.invoke(
        {"task": task, "code": "", "output": "", "error": "", "attempts": 0}
    )
    return {
        "task": task,
        "result": "ok" if not final["error"] else "failed",
        "attempts": final["attempts"],
        "code": final["code"],
        "output": final["output"],
    }

Deploy and call it

Deploy the app:

Terminal
blade deploy sandbox_langgraph.py

Then POST a task to the /run route:

Terminal
curl -X POST <URL>/run -H 'content-type: application/json' -d '{"task": "compute the first 10 prime numbers"}'

LangGraph drives the loop (generate, run in the sandbox, retry on failure) and hands back the working code and its output. This exact agent is verified end-to-end: it writes the code, runs it safely, and returns the first 10 primes.

Take it for a spin

Everything above in one file, ready to run.

sandbox_langgraph.py
"""A LangGraph agent whose only tool is a disposable AI Fabric sandbox.

    blade deploy sandbox_langgraph.py
    curl -X POST https://sandbox-langgraph.apps.run.blade.sh/run \
         -H 'content-type: application/json' \
         -d '{"task": "compute the first 10 prime numbers"}'

The LLM (Qwen2.5-1.5B) runs in the GPU function on the host; the code it writes
runs in a fresh gVisor **sandbox** (debian_slim), so untrusted code never touches
the agent process. LangGraph drives the loop: generate → run-in-sandbox →
(retry on failure) → done. The sandbox is the agent's safe "code interpreter".
"""

import bladekit

app = bladekit.app("sandbox-langgraph")

# The agent (LLM + LangGraph) runs in this GPU container.
agent_image = (
    bladekit.Image.from_catalog("fabric/torch")
    .pip_install("transformers", "accelerate", "langgraph", "langchain-core")
)

# The generated code runs HERE, in an isolated gVisor sandbox, not the agent.
sandbox_image = (
    bladekit.Image.debian_slim(python_version="3.12")
    .pip_install("numpy", "sympy")
)

MODEL_ID = "Qwen/Qwen2.5-1.5B-Instruct"
MAX_ATTEMPTS = 3

# Loaded once per container, reused across calls that land on it.
_llm = None


def run_in_sandbox(code: str) -> tuple[bool, str]:
    """Execute code in a throwaway gVisor sandbox; return (ok, stdout-or-stderr)."""
    with bladekit.Sandbox.create(image=sandbox_image, timeout=20) as sb:
        sb.write_file("/work/tool.py", code.encode())
        proc = sb.exec("python", "/work/tool.py")
        proc.wait()
        if proc.returncode == 0:
            return True, proc.stdout.read().decode()
        return False, proc.stderr.read().decode()[:500]


@app.web_endpoint(methods=["POST"], min_replicas=0, max_replicas=2)
@app.function(gpu="RTX-A4500", image=agent_image, timeout=300)
def run(item: dict) -> dict:
    """Build a tiny LangGraph agent (generate → execute → retry) over a sandbox."""
    import re
    from typing import TypedDict

    from langgraph.graph import END, StateGraph
    from transformers import pipeline

    global _llm
    if _llm is None:
        _llm = pipeline("text-generation", model=MODEL_ID, device=0)

    class State(TypedDict):
        task: str
        code: str
        output: str
        error: str
        attempts: int

    def generate(state: State) -> dict:
        instruction = f"Write Python code to: {state['task']}\n"
        if state.get("error"):
            instruction += f"The previous attempt failed:\n{state['error']}\nFix it.\n"
        instruction += "Output ONLY the code in a ```python block."
        messages = [{"role": "user", "content": instruction}]
        raw = _llm(messages, max_new_tokens=256, do_sample=False)[0]["generated_text"]
        reply = raw[-1]["content"] if isinstance(raw, list) else str(raw)
        m = re.search(r"```(?:python)?\s*\n(.*?)```", reply, re.DOTALL)
        code = (m.group(1) if m else reply).strip()
        return {"code": code, "attempts": state["attempts"] + 1}

    def execute(state: State) -> dict:
        ok, out = run_in_sandbox(state["code"])
        return {"output": out, "error": "" if ok else out}

    def route(state: State) -> str:
        # Retry (back to generate) while the code errors and we have attempts left.
        if state["error"] and state["attempts"] < MAX_ATTEMPTS:
            return "generate"
        return END

    graph = StateGraph(State)
    graph.add_node("generate", generate)
    graph.add_node("execute", execute)
    graph.set_entry_point("generate")
    graph.add_edge("generate", "execute")
    graph.add_conditional_edges("execute", route, {"generate": "generate", END: END})
    agent = graph.compile()

    task = item.get("task", "compute the first 10 prime numbers")
    final = agent.invoke(
        {"task": task, "code": "", "output": "", "error": "", "attempts": 0}
    )
    return {
        "task": task,
        "result": "ok" if not final["error"] else "failed",
        "attempts": final["attempts"],
        "code": final["code"],
        "output": final["output"],
    }

Concepts used: Cold start, Endpoint, Replica, GPU

Contact the team

Loading the form…