Artifacts and skills — AI Portal Docs

These tools turn a turn’s work into something lasting — an artifact — and shape how the agent works: loading a skill’s instructions, asking a clarification question, and keeping a visible task list.

Key rules

Artifacts are for reusable output. Reply text stays in the conversation.
Visual files are inspected before they are saved. The save carries the checksum of what was inspected.
A skill grants no tools. Loading one is reading instructions; the tool list is fixed before the loop starts.
Clarification pauses the same task. The answers come back as the tool’s result.
The task list is not a file. update_tasks sends the whole list each time.

Artifacts

An artifact is substantial, reusable output a person will reopen or download. The owner is resolved from the turn. Revising is the one place the model supplies an identifier — carried from the creating call’s result and checked by the backend against the caller’s organisation; a wrong id is an ordinary error.

A write returns the id and version, and the chat shows the card at that point in the turn. One turn can show several artifacts, and a later revision appears again where it was made. Reading and other versions open in the side panel.

Six kinds

Kind	Content
Prose (`DOCUMENT`)	Markdown
Code (`CODE`)	The source file
Web preview (`WEB_PREVIEW`)	One complete HTML document
File (`FILE`)	A stored file, and for a deck the HTML that built it
Chart (`CHART`)	A series and its rows
Diagram (`DIAGRAM`)	Mermaid (preferred), or positioned nodes and connections

The formats are declared once and shared by the create and revise tools.

Creating and revising

For prose, code, chart and diagram, create_artifact and rewrite_artifact take exactly one of inline content or a workspace path. A body already in the workspace is saved by path, preserving its UTF-8 content without another model transcription.
A path rewrite requires expectedVersion. A rewrite naming a version other than the saved one is refused with the saved version’s number — a bare “version changed” refusal used to lead the model to save a second artifact instead of a new version.
Small changes use update_artifact edits.
Saving a .pptx without naming the HTML it was built from is refused while the call is still being written, so the model learns what is missing in the same step.
Chat progress distinguishes preparing the call from saving its completed arguments.

Inspect → checksum → save

Inspect

Visual FILE artifacts and WEB_PREVIEW require inspection of the exact path with inspect_artifact, covering every page. Plain-text file downloads such as Markdown get an internal inspection that confirms the format; the model needs no separate call. Renaming a PDF to a text extension still requires visual review.
Checksum

The inspection computes the file’s checksum. When grounding review is enabled, the runtime also reads the complete text source and reviews it once; the authoring model gets a compact receipt.
Save

The save carries the checksum, and a changed file is refused. A supplied checksum must match, and the backend checks it again when saving.

Printing to PDF

print_pdf turns a workspace HTML file into a PDF beside it:

The backend opens the HTML in the same sandboxed frame inspection uses and lets its scripts finish.
Each canvas is replaced with an image of what it drew, and the scripts are removed.
That snapshot is loaded into a page with JavaScript off and printed — Chromium paginates only the top-level document.

The document’s own @page rule wins over the requested paper size and the default 16 mm margin. The PDF stays in the workspace; the model gets the path, page count and runtime errors. print_pdf writes no artifact: the PDF is saved like any visual file — every page inspected, then saved by path.

Artifact visual review

measure_layout, inspect_artifact and print_pdf accompany the available artifact tools without a separate skill binding or registration.

measure_layout lays HTML out in the backend’s browser and returns the geometry and paint properties of the elements a selector matches, plus the clipping and word-breaking checks the inspector runs. It renders no image and saves nothing — it is how a presentation gets its coordinates before any file exists.

inspect_artifact reads file bytes as the turn’s owner, after tool-access checks, and returns:

real Office and PDF page images, image-file pixels, or text chunks;
HTML screenshots at two sizes — a desktop width and a phone width;
for unknown binary formats, metadata and an explicit note that visual inspection is limited.

Picture sizes

A page taller than one readable capture comes back as several numbered frames rather than one tall picture; past four frames, a width stops and says how much was left. A picture past about 1,600 pixels on its long edge is resized before the model sees it, which shrinks body text to a few pixels — so tall pages are split instead.
A PDF or Office page is rendered for the viewer at 2,000 pixels wide (an A4 page is then near 2,800 tall), and the model’s copy fits within 2,000 on its longest side.
Once a request carries more than 20 pictures, the provider refuses any larger one and the whole call with it. How older pictures are released is described on The agentic loop.

Review rules

FILE and WEB_PREVIEW artifacts are workspace files with no body of their own, so a create, a rewrite and an HTML patch each require inspection of the exact path and checksum, all returned pages, and a later model decision.
A new file or changed HTML needs fresh inspection. Reported layout or runtime issues block saving.
Images stay images through result handling so the model can review them; the text beside them is shortened like any result. Afterwards the portal keeps each image’s size in place of its pixels.
Pages of unchanged bytes count across turns: a turn saving a 37-page PDF an earlier turn inspected only inspects the pages still missing. Issues do not carry over — every inspection checks the bytes again.
One inspection renders up to 10 pages. A save demands every page of the bytes it stores, and a rebuild makes new bytes — so a nine-slide deck changed by one line is inspected whole again (three pages per call means three model round trips against a second of rendering).

This proves that render evidence reached the model before it decided to save — not that every visual judgment is correct. The rendering service itself is described on Deployment.

Skill loader

The prompt carries one sentence per bound skill; the loader takes one name and returns the skill’s text. Both say to decide about a skill before answering, and that loading is reading instructions — so a skill governing every answer is loaded even for a greeting.

The backend re-derives the accepted names from the turn. A name outside the list — another agent’s, another organisation’s, or nothing — is refused as though it did not exist, and the refusal is an error, not an empty answer.
Loading grants no tool.
Every load, refused or not, leaves a trace step naming the skill.
A skill’s own files can be mounted into a code run — see Workspace and code.

Which skills an agent binds is set when building an agent.

Clarification

Calling the clarification tool raises an interrupt: the loop halts and the turn records a pause. A later invocation answers the interrupt, and the call returns the answers. How the pause is stored and resumed lives on Agent execution.

Rule	Detail
Before asking	Check the conversation, memory and the tools it holds; state an assumption when the ambiguity would not change the answer
Answers	Offer them; an open question is the fallback when they cannot be listed
Lead line	Says where an answer leads; omitted when it fits every answer or the answer already says it
Recommendation	At most one, with grounds — the schema refuses two
Typed reply	Available unless the offered set is exhaustive
Declining	Always available
Question ids	Assigned by the runtime

What you see is on Approvals and questions.

Task list

The task list is not a file. The agent calls update_tasks with the whole list each time.

Up to 20 tasks, each with a title and a status: pending, in progress or completed. At most one in progress.
An empty list clears it — how the agent drops work you have moved away from.
The tool runs inside the runtime and calls no portal route. It keeps the list for the rest of the turn.
It answers with how many tasks are done, the step to mark next, and the tasks whose status changed since the previous call — which is what the trace row shows.
The transcript keeps every call; the latest successful one is the list the chat shows above the message box.
The agent sends the update in the same message as the call that starts or finishes a task, since every message costs a model call.

Planning a heavy task

How much planning a turn does depends on the request: a question answered in one or two lookups gets none; clear work of three to five steps gets a task list; large or vague work gets a spec, then a plan, then a task list.

Unfinished lists

Before a turn ends. If the turn called update_tasks and a task is not completed, the runtime gives the model one more call to bring the list up to date and say what remains. This happens once per turn, after any message you wrote during the last call has been answered. A turn that only inherited a list leaves it alone, and a budget stop during that extra call still records the turn as answered.
When the next turn opens. If the latest list has an unfinished task, it is carried in the turn’s own message beside the clock, so the cached system prompt stays the same bytes. The portal reads it from the newest successful update_tasks call in the transcript; a resumed turn reads it from the history it restores.

Under the hood

Inspection and grounding internals

For inspect_artifact, the internal endpoint resolves a live turn, checks tool access and reads file bytes as that turn’s owner. Inspection traces record fingerprints, page coverage and diagnostics without duplicating screenshot bytes in the audit row; each trace records the path, checksum and pages shown, and the backend answers later inspections in the conversation with the pages of the same bytes already reviewed. The artifact tools share an invocation-local review state. Grounding review reads the complete text source through the internal artifact-source endpoint.

Artifacts Open, version and download artifacts. Building an agent Choose an agent’s tools and skills. Agent execution Pauses, approvals and resuming. Workspace and code Where artifact files are built.