Quickstart: deploy your first agent

In about five minutes you'll deploy a real AI agent — one that can run Python code in an isolated sandbox and remember what you told it earlier in the conversation — then talk to it and clean it up. There is one agent and one set of code; you can deploy it from the console (nothing to install) or from the CLI. Pick either path.

If anything goes wrong, jump to If something breaks at the bottom — the common failures and their exact error messages are listed there.

Before you begin

• A platform account and a selected project — see Create an account.
• Console path: nothing else. A browser is enough.
• CLI path: platformctl built and signed in — see Install the CLI.

The model your agent thinks with is wired in by the platform — you do not need to bring a model API key for this quickstart.

The agent code

Both paths deploy this one file, agent.py. It uses ADK (Google's open-source Agent Development Kit), which the platform runs natively:

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="my_first_agent",
    model=foundry_model(),
    instruction="Use run_python for math and search_memory to recall facts.",
    tools=[run_python, search_memory],
)

Four things worth knowing, in plain words:

• root_agent is the name the platform looks for. Every ADK agent must define it at the top of agent.py.
• foundry_model() returns the platform-managed model. Swap models later via configuration, not code.
• run_python is a tool that executes Python in a single-use sandbox — the agent's calculator.
• search_memory searches the agent's long-term memory bank. It's empty today; that's fine.

You don't need a requirements.txt — the platform's base image already ships ADK and these tools.

---

Path A: the console

1. Open the Agents page

Sign in at https://console.codyhill.dev, press Cmd+K / Ctrl+K to pick your project, then go to Compute → Agents in the left nav and click Deploy agent.

2. Write the code in the browser

In the deploy dialog:

1. Name the agent my-first-agent (names must be lowercase letters, digits, and hyphens).
2. Keep the framework as ADK.
3. Choose the write mode and replace the starter agent.py with the code above.
4. Click through Review & deploy.

You should see: a build panel streaming the status — building, then deploying, then ready. This usually finishes within a few minutes. If it lands on failed, the build's own output is shown right there on the agent's Overview tab — that is the build log.

3. Talk to it

Open the agent's Test tab. Type:

My favorite number is 42. Compute 2**32 in python.

You should see: a reply containing 4294967296, a tool call entry showing run_python ran, and the session id of this conversation. The agent didn't guess the math — it wrote Python, the sandbox executed it, and the answer came back.

4. Prove it remembers

In the same Test panel, send a follow-up:

What's my favorite number?

You should see: a reply mentioning 42. The Test panel reuses the same session, and the platform replays the conversation history to the model on every turn. That's sessions working.

5. Clean up

On the agent's page, click Delete and confirm. The endpoint, its build, and its stored source are removed.

---

Path B: the CLI

1. Write the agent

mkdir my-first-agent && cat > my-first-agent/agent.py <<'EOF'
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="my_first_agent",
    model=foundry_model(),
    instruction="Use run_python for math and search_memory to recall facts.",
    tools=[run_python, search_memory],
)
EOF

2. Deploy it

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

You should see:

packaging ./my-first-agent...
uploading my-first-agent (1.2 KiB, framework=adk)...
build 2f6f1c3a-... accepted
status:  -> building
status: building -> deploying
status: deploying -> ready
my-first-agent is ready at http://my-first-agent.cai-p-ab12cd.svc.cluster.local

The CLI polls every 2 seconds and waits up to 5 minutes. The framework was auto-detected as ADK because the folder contains agent.py.

3. Talk to it

platformctl invoke my-first-agent "My favorite number is 42. Compute 2**32 in python."

You should see:

2**32 is 4294967296.
(session: 3f2c8a1e-9b7d-4e21-a6c0-5d8f13b2e470)
  tool_call: run_python called with args={'code': 'print(2**32)'}

Three things happened: the model decided to use a tool, run_python executed real Python in an isolated sandbox, and the platform minted a session id for this conversation. Copy yours — you need it next.

4. Prove it remembers

Reuse the session id from step 3 (yours will differ):

platformctl invoke my-first-agent "What's my favorite number?" \
  --session 3f2c8a1e-9b7d-4e21-a6c0-5d8f13b2e470

You should see: a reply mentioning 42. Same session, same conversation — the platform stored turn 1 and replayed it to the model for turn 2. Without --session, each invoke starts a brand-new conversation.

5. Look under the hood (optional)

platformctl status my-first-agent

You should see: the agent's name, framework, status (ready), internal URL, and image. The status table decodes only those fields from the API response — it does not show the public URL or the latest revision, so check the agent's page in the console for those.

And:

platformctl logs my-first-agent --history

shows persisted logs that survive even when the agent has scaled to zero.

6. Clean up

platformctl delete my-first-agent

You should see:

deleted my-first-agent

---

What just happened

1. Build. The platform packaged your folder, built it into a container image on top of the managed agent harness (a small web server that runs your code), and stored it in the platform registry.
2. Deploy. The image became a serverless service in your project with a stable invoke endpoint.
3. Wire-up. Sessions (conversation history), the memory bank, the sandbox, and the model were injected automatically — zero configuration from you.
4. Scale-to-zero. A few minutes after your last message, the agent's instances drop to zero. The next invoke cold-starts it — expect that first reply after an idle period to be slower than the ones that follow.

If something breaks

Symptom	Cause and fix
Status is failed after deploy	The build or startup failed. Run platformctl logs my-first-agent — in the console, the build output is shown on the Overview tab.
Error mentions could not import 'root_agent'	Your agent.py doesn't define a module-level root_agent. Match the code above exactly.
invalid agent name (must be a lowercase DNS label)	Names allow only lowercase letters, digits, and hyphens, starting with a letter, up to 63 characters.
The reply is a model authentication error	The platform's model key isn't configured for your install. Ask your administrator, or set a per-agent MODEL_API_KEY — see Secrets and env.
this is a management endpoint and requires authentication...	You're not signed in. Run platformctl login (invoking works without it; deploying doesn't).
Turn 2 forgot turn 1	You didn't pass --session, so each invoke started a fresh conversation.

More in Agent Engine troubleshooting.

Next steps

• Deploy your first function — a plain HTTPS endpoint in one file.
• Sessions — how conversations persist, and the user_id model.
• Memory — promote a conversation into long-term memory that new sessions can recall.
• Tools — write your own tools beyond run_python.
• Deploying agents — frameworks, revisions, and everything the deploy path supports.