Files & storage
Two different problems, two different stores, and the whole design follows from telling them apart:
- Someone hands your agent a document. It lands on the platform's upload buffer, you get an opaque file id, and it disappears after 3 days.
- Your agent produces something worth keeping. That goes in a data bucket your organization connected — addressed by a key you choose, kept until someone deletes it.
from im_sdk import ImCore, im_agent
@im_agent("archivar")
async def main(core: ImCore, data: dict) -> str:
file_id = data["datei"] # an io.json input of "type": "file"
# Read what the user uploaded.
doc = await core.file_store.get(file_id)
# Keep it past its 3 days: buffer → bucket, server-side.
stored = await core.object_store.put_from_upload("archiv", file_ref=file_id)
return f"{doc.output.filename} archiviert als {stored.output.key}"Upload buffer (core.file_store) | Data bucket (core.object_store) | |
|---|---|---|
| Whose it is | the platform's | your organization's |
| Addressed by | Portal file id (a uuid) | object key you choose |
| Lifetime | 3 days, then pruned | until someone deletes it |
| Grant needed | none | the service and each operation |
| Written by | the upload surfaces | your agent |
| Read by | any agent in that workspace | any agent granted the service |
Getting a file to your agent
Declare the input
Add it to .im/io.json with "type": "file". That is what makes the Portal
playground render an uploader for the field instead of a text box:
{
"inputs": [
{ "name": "datei", "type": "file" },
{ "name": "frage", "type": "string" }
],
"output": { "type": "multiline" },
"example": {
"inputs": { "frage": "Worum geht es?" },
"output": "Es geht um …"
}
}A file input takes no example value, and validation exempts it: the only
value you could write there is a file id from some other workspace or an invented
one, and the playground would offer it as a default — which is how a run ends up
failing on a file_ref that never existed while a real upload sat unused.
See The io.json contract for the rest of the shape.
Upload it
| Where | How |
|---|---|
| Portal | The playground's file field, or the workspace's Files list |
| CLI | im-cli files upload report.pdf — prints the id on stdout, pipe-friendly |
| Your app | POST /api/external/v1/…/workspaces/{ws}/files with an org API key |
im-cli files upload report.pdf # → 2247c37d-…
im-cli run --input 'datei=2247c37d-…'Files belong to a workspace, not to a run and not to an agent: every agent in
that workspace can read every live file in it, and im-cli files list shows them
all. The server enforces a 25 MB cap plus two independent allow-lists — the
filename's extension and the sniffed content type must both pass, so renaming
a binary does not get it in.
Agents that take several documents conventionally read a list under the input key
files; that is what im-cli run --input 'files=["…","…"]' produces.
Reading a file
As bytes — core.file_store.get(file_ref)
result = await core.file_store.get(file_id)
result.output.text # decoded when the bytes are text — "" otherwise
result.output.content_b64 # Base64 bytes, always
result.output.filename # what the uploader called it
result.output.mime_type
result.output.size_bytes.text is a convenience for the common case (CSV, JSON, plain text). A binary
object — or one that simply does not decode — yields "", not an error and
not None, so branch on the mime type rather than on the emptiness of .text;
otherwise a PDF looks exactly like an empty file. The same contract holds for
object_store's .text.
No service, and no grant. The buffer is the platform's own disk, so there is no third party to name and nothing to authorize against: the gateway resolves the ref against your execution's workspace, which is the entire tenancy story.
Without the bytes touching your process — document_parse
If all you want is the text, do not download it. Pass the ref and let the gateway fetch the bytes server-side:
result = await core.document_parse.partition(service="unstructured", file_ref=file_id)
text = result.textSame for extract() and ocr(). This is the better default for anything large:
the document never enters your agent's memory and never crosses the wire twice.
Keeping a file — put_from_upload
An upload expires. One call moves it into a bucket that does not:
stored = await core.object_store.put_from_upload("archiv", file_ref=file_id)
stored.output.key # "uploads/2247c37d-…-report.pdf"The bytes go buffer → bucket server-side — they never pass through your
process, which is what makes archiving a 25 MB upload cheap. Omit key and the
object is stored as uploads/<file-id>-<filename>, keeping the uploader's
original name (sanitized: a name containing a slash would otherwise pick its own
place in the bucket). Pass key= to file it your own way.
Like put, it is create-only: archiving never overwrites.
The data bucket — core.object_store
Service-addressed: the first argument is the name of a connected service, not
a provider and not a bucket. Read which ones your agent has with
im-cli agent services rather than guessing.
await core.object_store.put("archiv", key="berichte/q3.csv", content_b64=csv_b64)
text = (await core.object_store.get("archiv", "berichte/q3.csv")).output.text
page = await core.object_store.list("archiv", prefix="berichte/")
keys = [o.key for o in page.output.objects]
while page.output.next_cursor:
page = await core.object_store.list("archiv", prefix="berichte/", cursor=page.output.next_cursor)
keys += [o.key for o in page.output.objects]| Method | output | Notes |
|---|---|---|
get(service, key) | ObjectOutput | .content_b64, .text, .content_type, .size_bytes, .filename |
stat(service, key) | ObjectStatOutput | metadata only — the cheap "is it there / how big" |
list(service, prefix=…, limit=…, cursor=…) | ObjectListOutput | .objects, .next_cursor (None on the last page) |
put(service, key=…, content_b64=…) | ObjectWriteOutput | create-only — an existing key raises object_exists |
replace(service, key=…, content_b64=…) | ObjectWriteOutput | writes whether or not the key exists |
put_from_upload(service, file_ref=…, key=…) | ObjectWriteOutput | buffer → bucket, server-side; create-only |
delete(service, key) | ObjectDeleteOutput | one key; .deleted is False when there was nothing there |
list defaults to 100 entries per page and caps at 1000. The cursor is the
store's own continuation token — opaque, pass it back verbatim.
Keys are relative to the service
Each connected service owns one prefix inside its bucket. The gateway adds it on the way in and strips it on the way out, so the key you send is the key you get back and no key you can write reaches another service's objects.
Refused before the store is ever touched: .., a leading /, empty segments,
backslashes, control characters, unpaired surrogates, a key too long once the
service prefix is added, and the reserved .im- namespace.
What list actually returns
Keys — not filenames. filename and content_type are None on every entry
of a listing, because ListObjectsV2 carries neither, and a HEAD per entry would
turn one listing into N round trips. What you get per entry is key,
size_bytes, etag and last_modified.
That is usually fine, because the default key from put_from_upload already
contains the original filename. But if you need the recorded filename or the
content type, ask per object with stat() — and budget a call each.
Every operation is a separate grant
put and replace are different permissions on purpose: an agent granted only
put can add objects to an archive and can never destroy one. Expect to be
told which ones you have.
A call outside the granted set raises ImForbiddenError with
POLICY_ACTION_NOT_GRANTED, and the error's context carries granted_actions —
so the remedy is visible without opening the Portal:
from im_sdk import ImForbiddenError
try:
await core.object_store.replace("archiv", key=k, content_b64=b64)
except ImForbiddenError as exc:
(exc.context or {}).get("granted_actions") # e.g. ["get", "list", "put"]Errors
| Code | Raised as | Means |
|---|---|---|
file_not_found | ImValidationError | the file id is unknown, expired, or from another workspace — deliberately indistinguishable |
object_not_found | ImValidationError | nothing at that key; another service's object answers the same way |
object_exists | ImValidationError | put / put_from_upload onto a live key — use replace |
POLICY_ACTION_NOT_GRANTED | ImForbiddenError | that operation is not granted (or the quota withdrew it) |
The indistinguishability is deliberate in both directions: an error must never tell you that something exists somewhere you cannot reach.
delete is the exception to all of this — deleting a key that holds nothing is
not an error. .deleted is False and the call succeeds, so a cleanup loop
can safely run twice.
Limits
| Upload size | 25 MB (FILES_MAX_KILOBYTES) |
| Upload lifetime | 3 days (FILES_TTL_DAYS) |
| Object read/write | 26 MiB per object, in and out |
list page | 100 by default, 1000 maximum |
| Object key | 987 bytes (S3's 1024, less the service prefix the gateway adds) |
For anything past the object ceiling the bucket is not the transport — write it where your agent already streams.
Notes for the operator side
What an admin configures (connecting a bucket, the connection check on save, the
per-operation grants, the size cap, how the store is backed up) lives in the
platform repository: docs/agent-data-bucket.md for buckets and
docs/file-uploads.md for the buffer.