The io.json contract
Every agent project has a .im/io.json that declares the agent's typed
inputs and output. Unlike .im/config.json (local, gitignored), io.json
is committed — it's part of the agent, and it travels with each pushed
version. im-cli link scaffolds a skeleton; you edit it to match what your
main.py actually reads and returns.
Three things read it, and it pays to be exact about which does what:
- The Portal, at push time. It extracts
.im/io.jsonfrom the bundle and validates the declaration's shape — the types are known, everynameis present and unique, theoutputis well-formed — then stores the result on the version. This checks the file you pushed. It never sees a run. - The Portal playground. It builds a form from
inputs[], pre-fills it fromexample, and won't submit while a field is empty. That is the one place a missing input is ever caught, and it is caught in a browser. - The SDK, locally.
example_input()readsexample.inputsoff the file on disk, souv run main.pyruns with no--input.
Nothing checks a run's input
The runner does not read io.json. It hands your agent --input '<json>'
verbatim, and read_input() parses that JSON into a dict — no key is compared
against anything you declared, in either direction. A run started from the API,
from im-cli run, or from a resumed execution can carry a missing key, a
misspelt key, or a key io.json never mentions, and every one of them reaches
your code untouched.
So read io.json as a declaration — for the form, and for the next person to
open the project — and put the requirement itself in main.py, which is the
only place that runs on every execution:
from im_sdk import ImError, read_input
data = read_input()
company = str(data.get("company") or "").strip()
if not company:
raise ImError("input 'company' is required")Keeping the two in step is manual: when main.py starts reading a new key, add
it to io.json so the form offers it. Nothing will tell you if you forget.
Shape
{
"inputs": [
{ "name": "prompt", "type": "string" }
],
"output": { "type": "string" },
"example": {
"inputs": { "prompt": "Say hello in one sentence." },
"output": "Hello! Nice to meet you."
}
}inputs— an ordered list of{ "name", "type" }. Eachnameis the key your agent reads out of the input dict (data.get("prompt")).output— a single{ "type" }.example— aninputsmap and anoutputsample. The inputs map is whatexample_input()returns for local runs; both are shown in the Portal.
Supported types
Inputs and the output are typed with one of these (richer numeric/structured types are deferred):
| Type | Meaning | Input | Output |
|---|---|---|---|
string | Free text (single line). | ✓ | ✓ |
multiline | Free text spanning multiple lines. | ✓ | ✓ |
url | A URL — validated and rendered as a URL field. | ✓ | ✓ |
email | An email address. | ✓ | ✓ |
json_string | A JSON document carried as a string; parse it yourself in the agent. | ✓ | ✓ |
file | A workspace upload, carried as its Portal file id. | ✓ | — |
An invalid io.json (unknown type, missing name, duplicate name, malformed
output, an example that doesn't cover every input) is rejected at push time
with an agents.version.io.* error.
Only name and type are kept
Passing validation and being stored are not the same thing. Each input row is
checked on the keys it has, then rebuilt from name and type alone.
Everything else you write on a row — description, label, default,
required — is accepted at push and then dropped: it never reaches the stored
contract, so the playground cannot render it and nothing downstream can read
it. output likewise keeps only its type.
Dropped is not the same as invalid, and the difference is the trap: the push
succeeds, so there is nothing to tell you the key went nowhere. A row carrying
"required": false is a plain { name, type } by the time the form sees it —
and the form requires every field it renders, so that row is now mandatory. A
description you meant as help text under the field simply does not exist.
example is the exception: it is stored whole. That is why it can carry values
for the playground to pre-fill and for example_input() to replay locally.
Anywhere else, the place for a note about an input is the project's README
or main.py, where a reader will actually meet it.
File inputs
"type": "file" is the one type that is not a string you type. It exists
because the playground has to render it differently — the field becomes an
uploader, and the id it produces is bound to that field:
{
"inputs": [
{ "name": "datei", "type": "file" },
{ "name": "frage", "type": "string" }
],
"output": { "type": "multiline" },
"example": {
"inputs": { "frage": "Worum geht es?" },
"output": "Es geht um …"
}
}Your agent receives the file id, and reads the document with
core.file_store.get(...) or by handing the ref to core.document_parse — see
Files & storage.
Two rules follow from the type:
- It is input-only. An agent returns text; a
fileoutput would have to mean "the agent uploaded something", which is what a data bucket is for. - It takes no
examplevalue, and one is refused — not merely optional. The only value you could put there is a file id from another workspace or an invented one, and the playground would offer it as a default — which is how a run ends up failing on afile_refthat never existed while the file the user just uploaded sat unused. Naming afileinput underexample.inputstherefore fails validation withagents.version.io.example_file_input. Every other declared input still needs its example.