Skip to content

Structured answers, artifacts and pages

A model call returns text by default. Many applications need more: a form your interface fills in itself, a chart a tool made, a report a customer opens in the browser that keeps the same address at every new version. Core has three building blocks for that: structured output, artifacts and pages.

You want Use What you get back
fields your own code reads and lays out structured output JSON that matches your schema, in the response itself
a file an agent makes during a turn an artifact a reference in the response; you download the bytes separately
an HTML report people open in a browser a page, or an HTML file you show a view address you open, or a share link for someone outside your organisation

Structured output

You pass a JSON Schema in a turn's text field, and the model answers with JSON that matches it: {"format": {"type": "json_schema", "name": "...", "schema": {...}}}. Your interface reads the fields and shows them its own way, as a table, a card or a filled-in form, instead of parsing text.

When the model supports a schema itself, the schema goes to the vendor. Otherwise Core asks the model for JSON following the schema and checks the answer itself. When that answer does not match, the turn fails with invalid_structured_output and you get no half answer. The schema shapes only the final answer; tool calls along the way fall outside it.

Use structured output when your code does something with the answer: store a field, make a decision, fill a screen. For an answer a person only reads, text is enough.

Artifacts

An artifact is a file a tool makes during a turn: a chart from a script, an image from an image model, or a document the model wrote with the builtin__create_artifact tool, such as an HTML report, Markdown or CSV. The model gets a reference to the file, not the bytes. Every artifact names the response, the tool call and the tool it came from, so your application can list and download the files of one response. It starts with the labels of that response.

An artifact is a stored file like an upload. It stays as long as your organisation's retention window allows, unless you mark it to keep. Downloading an artifact needs the artifacts and files capabilities, and a rule in the policy that allows downloading. That is how you choose per key whether what a tool made may leave the organisation.

Pages

A stored HTML file, an upload or an artifact, can be shown in a browser instead of downloaded. There are two addresses:

  • a view address, valid for a few minutes, for yourself or your application's user. You open it in a tab or window of its own. Showing it in a frame inside your own product works only when your deployment allows your product's origin, with the artifacts_view_frame_ancestors setting. By default it allows no origin; your operator sets it;
  • a share link, valid for days, for someone outside your organisation without an account. It needs a rule in the policy that allows sharing with a link, and you can revoke it at any moment.

Whoever has an address opens the file without a key. Treat an address as a secret. A model never gets an address: your own code asks for it.

A report gets updated, and every version is a new file. A page is a fixed name over those versions. Publish a new version, and every view address and every share link of the page shows it, at the address people already have. You set a previous version back with one call.

How it fits together

  • Structured output is a field of a model call and works with every agent.
  • Artifacts come from tools; the tool that writes a document is switched on per key.
  • Artifacts and pages are stored files of your organisation, fall under its retention period and under the key's policy. An artifact a turn made for a person belongs to that person.

Read on