Build agents with ADK

ADK (Google's Agent Development Kit) is an open-source Python framework for building agents. The platform runs unmodified ADK agents — you write standard ADK code, and the harness handles serving, sessions, and memory. This page gives you the author contract, the Crusoe helpers, and a complete agent you can deploy right now.

Before you begin

• You can deploy: account, CLI, and sign-in per deploy an agent.
• Python knowledge. You do not need ADK installed locally to deploy — the build happens on the platform.

The contract

Your directory must contain an agent.py that defines a module-level variable named root_agent. That's the standard ADK convention, and it's the one thing the harness looks for when your agent starts.

If it's missing, your agent will crash-loop at startup, and this exact error lands in the agent's status message:

could not import `root_agent` from /app/agent/agent.py - the agent image must define a module-level `root_agent` in agent.py

You can add other .py files and import them from agent.py. An optional requirements.txt is pip-installed at build time — a bad dependency fails the build (readable in the status message field), not the running pod.

What the base image already provides

The ADK base image ships with pinned versions of everything the harness needs, so most agents need an empty requirements.txt or none at all:

Package	Pinned version
google-adk	2.5.0
litellm	1.93.0
fastapi	0.139.2
qdrant-client	1.18.0
valkey	6.1.1
Python	3.12

Plus the first-party crusoe_adk package described below. Pinned versions mean your agent won't silently break when an upstream library changes — the versions only move when the platform ships a new base image.

foundry_model(): the platform model helper

foundry_model() returns an ADK model object wired to Crusoe managed inference (an OpenAI-compatible endpoint the platform injects into every agent):

from crusoe_adk.foundry import foundry_model

model = foundry_model()                                        # use the platform's configured model
model = foundry_model("nvidia/NVIDIA-Nemotron-3-Super-120B-A12B")  # or pin one in code

• With no arguments, it uses the CHAT_MODEL environment variable. That means you can swap models from the console (or with the env API) without touching code — see secrets and environment variables.
• When nothing is configured anywhere, the platform default is zai/GLM-5.2 served from https://api.inference.crusoecloud.com/v1.
• The model API key comes from the MODEL_API_KEY secret. Setting it as a per-agent secret overrides the platform default key.

Built-in tools

Two ready-made tools ship in crusoe_adk.tools:

from crusoe_adk.tools import run_python, search_memory

• run_python(code) — runs Python in the platform's code sandbox: an isolated, single-use environment, never your agent's own container. Execution is capped at 20 seconds.
• search_memory(query) — searches the agent's long-term memory bank and returns the top 5 matching snippets. Memories get there via the explicit memorize step.

You can also write your own tools as plain Python functions — see tools. By default the platform runs user-written tool code in sandbox pods too (the TOOL_SANDBOX setting, on by default); set the env var TOOL_SANDBOX=false on the agent to run your tools inside the agent pod instead.

Complete example: research-buddy

This is the platform's canonical example agent, complete and runnable as-is. Two files.

my-agent/agent.py:

from google.adk.agents import Agent

from crusoe_adk.foundry import foundry_model
from crusoe_adk.tools import run_python, search_memory

root_agent = Agent(
    name="research_buddy",
    # foundry_model() with no args uses the CHAT_MODEL env var, so you can
    # swap the model from the console without touching code. To pin a model
    # in code instead, pass it:
    # foundry_model("nvidia/NVIDIA-Nemotron-3-Super-120B-A12B").
    model=foundry_model(),
    instruction=(
        "You are Research Buddy, a research assistant. Use the run_python tool "
        "for calculations and the search_memory tool to recall things you have "
        "been told to remember."
    ),
    tools=[run_python, search_memory],
)

my-agent/requirements.txt:

# No extra dependencies - google-adk, litellm, and crusoe_adk are already
# provided by the harness base image.

Deploy and test it

1. Deploy. The CLI detects ADK automatically (no crew.py or graph.py present):

platformctl deploy ./my-agent --name my-agent

You should see:

packaging ./my-agent...
uploading my-agent (1.2 KiB, framework=adk)...
build 2f6f2f6e-8a1e-4c3b-9d2a-1b2c3d4e5f6a accepted
status:  -> building
status: building -> deploying
status: deploying -> ready
my-agent is ready at http://my-agent.cai-p-x7k2q.svc.cluster.local

2. Talk to it — this exercises the model and the sandbox tool in one turn:

platformctl invoke my-agent "Compute 2**32 in python."

You should see:

2**32 is 4294967296.
(session: 3f2c8a1e-7b4d-4e2f-9a1c-5d6e7f8a9b0c)
tool_call: run_python called with args={'code': 'print(2**32)'}

3. Clean up when you're done:

platformctl delete my-agent

Next steps

• Invoke — sessions, streaming, and the full request/response shapes.
• Memory — make search_memory actually find things.
• Tools — write your own tool functions.
• Same agent, other frameworks: LangGraph, CrewAI.