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:
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 = NoneWrite 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:
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:
@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:
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 ENDWire 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:
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:
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:
blade deploy sandbox_langgraph.pyThen POST a task to the /run route:
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.
"""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