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.json from the bundle and validates the declaration's shape — the types are known, every name is present and unique, the output is 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 from example, 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() reads example.inputs off the file on disk, so uv run main.py runs 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" }. Each name is the key your agent reads out of the input dict (data.get("prompt")).
  • output — a single { "type" }.
  • example — an inputs map and an output sample. The inputs map is what example_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):

TypeMeaningInputOutput
stringFree text (single line).✓✓
multilineFree text spanning multiple lines.✓✓
urlA URL — validated and rendered as a URL field.✓✓
emailAn email address.✓✓
json_stringA JSON document carried as a string; parse it yourself in the agent.✓✓
fileA 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 file output would have to mean "the agent uploaded something", which is what a data bucket is for.
  • It takes no example value, 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 a file_ref that never existed while the file the user just uploaded sat unused. Naming a file input under example.inputs therefore fails validation with agents.version.io.example_file_input. Every other declared input still needs its example.