Source files and the editor

When you deploy an agent, the platform also stores your source files so you can read them later, change one of them, and rebuild without re-uploading anything. This page covers the files API, the redeploy endpoint, what the console can and cannot do with stored source, and what happens when no source is stored.

What gets stored

Deploying an agent uploads a .tar.gz of your code. The platform builds that into an image and keeps a copy of the files as editable source.

Two limits matter. Storage is best-effort, meaning the platform tries to keep the copy but does not promise it. And it holds the latest version only — no history, no git, no undo. The API says as much itself: every file listing carries the note latest version only - the platform keeps no history, so copy anything you want to keep. Keep your real source of truth in your own repository.

These are management routes: sign in, owner or project admin only.

The files API

Method	Path	Behavior
GET	/v1/agents/{name}/files	List stored files
GET	/v1/agents/{name}/files/{path}	Read one file
PUT	/v1/agents/{name}/files/{path}	Create or overwrite one file
DELETE	/v1/agents/{name}/files/{path}	Delete one file
GET	/v1/agents/{name}/code.zip	Download the whole stored source as a zip
POST	/v1/agents/{name}/redeploy	Rebuild the agent from the stored source

The three interfaces are not equally granular, and it is worth knowing why before you pick one. The API and the CLI address one file at a time, and a write is a save that does not rebuild anything. The console's editor works on the whole tree at once and its only save button is Build and deploy — every console edit is also a deploy.

List files

platformctl

platformctl agents files list research-buddy

You should see:

PATH              SIZE   UPDATED
agent.py          512 B  2026-08-10T09:12:00Z
requirements.txt  64 B   2026-08-10T09:12:00Z

An agent with nothing stored prints no files stored for this agent rather than failing.

curl

curl -s "$CAI_API/v1/agents/research-buddy/files" \
  -H "Authorization: Bearer $CAI_TOKEN"

You should see:

{
  "agent": "research-buddy",
  "agent_id": "…",
  "files": [
    {"path": "agent.py", "size": 512, "updated_at": "2026-08-10T09:12:00Z"},
    {"path": "requirements.txt", "size": 64, "updated_at": "2026-08-10T09:12:00Z"}
  ],
  "editable": true,
  "note": "latest version only - the platform keeps no history, so copy anything you want to keep"
}

An agent with nothing stored answers 200 with an empty files array, not a 404.

Console

On the agent's page, click Edit code.

You should see: every stored file opened as its own tab, entry file first. That tab strip is the listing — there is no separate file browser.

If the platform cannot read the full tree, the editor refuses to open rather than showing you part of it. That is deliberate: deploying a partial tree would delete whatever it could not see.

Read a file

platformctl

platformctl agents files get research-buddy agent.py

The default output is the file itself, unadorned, so it redirects straight to disk:

platformctl agents files get research-buddy agent.py > agent.py

Add -o json for the API's full object instead — path, content, and updated_at.

curl

curl -s "$CAI_API/v1/agents/research-buddy/files/agent.py" \
  -H "Authorization: Bearer $CAI_TOKEN"

You should see:

{"path": "agent.py", "content": "from google.adk.agents import Agent\n…", "updated_at": "2026-08-10T09:12:00Z"}

Console

In Edit code, click the file's tab.

You should see: its contents in a real editor — line numbers, syntax highlighting, and a dot on any tab with unsaved changes.

Edit a file

platformctl

platformctl agents files put research-buddy agent.py --from ./agent.py

--from - reads stdin instead. The stored source is text: a file that is not valid UTF-8 is refused before it is uploaded, rather than stored with its bytes mangled.

curl

curl -s -X PUT "$CAI_API/v1/agents/research-buddy/files/agent.py" \
  -H "Authorization: Bearer $CAI_TOKEN" -H 'content-type: application/json' \
  -d '{"content": "from google.adk.agents import Agent\n# updated\n…"}'

You should see:

{"path": "agent.py", "bytes": 118, "note": "saved - redeploy the agent for this to take effect"}

Console

Type in the file's tab in Edit code, then click Build and deploy. + Add file adds a module to the tree.

There is no save-without-deploy in the browser: the editor packs every tab and deploys it in one action, so your edit and the new revision arrive together.

On the CLI and API paths, the note means what it says: saving a file changes stored source only. The running agent still runs the image it was built from until you redeploy.

Delete a file

platformctl

platformctl agents files delete research-buddy old_helper.py

You should see:

deleted old_helper.py from agent research-buddy

curl

curl -s -X DELETE "$CAI_API/v1/agents/research-buddy/files/old_helper.py" \
  -H "Authorization: Bearer $CAI_TOKEN"

You should see:

{"deleted": "old_helper.py"}

There is no Console tab here. The editor's tab close button only removes a file you added in that same dialog, never one already stored. To drop a stored file from the browser, deploy an upload that leaves it out — which is the whole-tree replacement described under the console editor, and it deletes everything else you omit too.

Redeploy from stored source

When your edits are ready, rebuild the agent from what's stored — no tarball, no upload.

platformctl

platformctl agents redeploy research-buddy

You should see:

agent      research-buddy
build_id   8c41…
files      2
note       rebuilding from the stored source

The build runs in the background; platformctl status research-buddy is where it finishes.

curl

curl -s -X POST "$CAI_API/v1/agents/research-buddy/redeploy" \
  -H "Authorization: Bearer $CAI_TOKEN"

You should see:

{"agent": "research-buddy", "build_id": "…", "files": 2, "note": "rebuilding from the stored source"}

You get 202 back immediately, then poll GET /v1/agents/{name} and watch state move through building and deploying to ready.

Console

Edit code → Build and deploy, with your edits applied first.

The console does not call the redeploy route: it packs the tabs on screen and uploads them, so a build with no edits at all still rebuilds from exactly what you see.

This runs the same build steps as a normal deploy, and rolls a new revision.

Download the source as a zip

GET /v1/agents/{name}/code.zip streams the whole stored tree as a zip, with every file under a <name>/ top directory so unzipping makes a folder.

platformctl

platformctl agents files download research-buddy

You should see:

wrote research-buddy-code.zip (915 bytes)

-o <file> names the output, and -o - writes the zip to stdout.

curl

curl -s -o research-buddy-code.zip \
  -H "Authorization: Bearer $CAI_TOKEN" \
  "$CAI_API/v1/agents/research-buddy/code.zip"

An agent with nothing stored answers 404 with a JSON body explaining that it predates source storage and that one redeploy fixes it.

Console

Click Download code on the agent's (or function's) detail page. It saves the same tree as <name>-code.zip.

The console editor

Functions have the same editor under Update source on the function's detail page; the deploy dialogs for both use the same tabbed editor in their Write code mode, pre-filled with a working starter for the framework you pick: agent.py (ADK), crew.py (CrewAI), or graph.py (LangGraph), plus a requirements.txt. Switching frameworks resets the starter, so choose the framework first. The other two modes are Upload files or a folder and Upload a .tar.gz you already have.

Deploying an existing name — from Edit code, Update source, or the deploy dialog — replaces the agent's whole stored source. Edit code and Update source open every stored file as a tab, so what you see is exactly what will be stored; the upload modes send exactly what you upload, and any stored file you did not include is deleted. There is no history to fall back on.

An agent deployed before source storage existed has nothing to edit; Edit code says so and the fix is one redeploy (platformctl deploy <dir>), after which its code is stored, editable, and downloadable.

Binary files

The browser upload refuses binary files — images, compiled libraries, anything that is not text — and names the file it rejected. The stored-source API handles text only as well. If your agent needs binary assets, deploy with a .tar.gz, either through the browser's tarball mode or with platformctl deploy. Binary content survives on that path and no other.

When no source is stored

Source storage is best-effort, so an agent can exist with no stored files at all — if the write failed at deploy time, for instance. Redeploying that agent fails with 400:

no source is stored for this agent - deploy it once from the CLI or upload files first

The fix is in the message: deploy once with platformctl deploy <dir> (which uploads and stores the source), or create the files with PUT /v1/agents/{name}/files/{path} first, then redeploy.

Limits

Limit	Value
Per file	1 MiB
Files per agent	200
Uploaded archive, expanded	64 MiB
History kept	None — latest version only
Symlinks, or paths in an archive that point outside it	Rejected
Binary content	Only via the .tar.gz upload path

Next steps

• Deploy an agent — the full deploy pipeline.
• Traffic and revisions — what a rebuild creates and how to roll back.
• Troubleshooting — build failures and stuck deploys.