Artifacts and Media

AgentOS can create and deliver files as part of agent work: reports, HTML files, PDFs, slide decks, spreadsheets, generated images, and other artifacts. Use artifacts when the output is too large, visual, structured, or important to leave only in chat text.

Artifacts#

Artifacts are user-visible files created during a session. In Web UI chat they appear as artifact cards when the runtime publishes them. In CLI runs, artifact events can include file names, ids, and download URLs.

Common use cases:

• generate a report;
• create a standalone HTML prototype;
• build a CSV/XLSX workbook;
• create a PDF briefing;
• produce a slide deck;
• package generated output for channel delivery.

Ask directly:

Create a one-page HTML dashboard from this data and publish it as an artifact.

Generate a PDF briefing with sources and publish the final file.

When to Use Artifacts Instead of Chat#

Use artifacts for:

• files the user should download or share;
• tables or reports that need layout;
• generated apps, dashboards, or prototypes;
• long output that would be awkward in chat;
• channel delivery where the platform supports file upload.

Use chat text for short answers, decisions, and next steps.

Inline Charts#

Most artifacts render in Web UI chat as a download chip; images and audio render inline. One more mime renders inline as an interactive chart:

There is nothing to register: any skill gets a chart by publishing a file with that mime. Two steps, and both have a failure mode worth knowing.

1. Write the JSON inside the workspace. Scripts run with the workspace as their working directory, so a bare filename lands in the right place. publish_artifact rejects anything outside the workspace, so an absolute path like /tmp/chart.json fails after the data has already been fetched.

2. Publish it with the mime spelled out.

publish_artifact path=bonk-1h.chart.json mime=application/vnd.agentos.chart+json

Passing mime is what makes the chart appear. Omit it and the filename guess returns application/json, which classifies as a data artifact and renders as an ordinary download chip — no error, just no chart. Tell the model to pass it explicitly in your SKILL.md.

The body is:

{
  "type": "candlestick",
  "title": "BONK · 1h",
  "subtitle": "SOL · 1h",
  "candles": [
    { "time": 1754380800, "open": 1.2e-6, "high": 1.5e-6, "low": 1.1e-6,
      "close": 1.4e-6, "volume": 12500.5 }
  ]
}

time is a Unix timestamp in seconds and volume is optional; every other candle field is required. Rows may arrive in any order and may repeat a timestamp — the renderer sorts them and keeps the last entry per timestamp. title and subtitle are display-only text, never markup.

Hovering a candle reveals its open, high, low, close, volume, and the move from open to close as a percentage, so there is no need to repeat those numbers in the reply.

The gmgn-market and gmgn-token skills each ship scripts/kline_chart.py, which converts GMGN kline output into this shape; use it as a worked example when adding charts to another skill. Note that they carry a copy each rather than sharing one: {baseDir} resolves to the skill that is running, so a skill cannot reach into another skill's scripts/ directory — and the skill it pointed at may not even be enabled. Give your skill its own copy.

Charts render in the Web UI only. Other surfaces receive the artifact as a normal JSON file, so keep a short text summary in the reply alongside the chart.

Document Skills#

AgentOS includes skills for common document formats:

• docx for Word documents;
• pptx for PowerPoint decks;
• xlsx for Excel workbooks;
• pdf-toolkit for structured PDF work;
• html-to-pdf for styled PDF rendering.

Discover them:

agentos skills search pdf
agentos skills view pptx
agentos skills view xlsx

Some document features require optional native/system dependencies. Use agentos skills list and agentos doctor to check readiness.

Image Input and Generation#

In terminal chat, send an image for analysis:

/image /path/to/screenshot.png Describe what is wrong with this UI.

Configure image generation:

agentos configure image-generation

Then ask for images in chat:

Generate a clean product mockup image for this landing page.

Image provider support depends on configured provider credentials, optional dependencies, and runtime policy.

Text to Speech and Media Helpers#

The media tool family includes image, PDF, and TTS helpers. Availability can depend on provider config, optional dependencies, and runtime policy.

Use media helpers when the requested output is naturally a file or asset rather than a plain text answer.

Channel Delivery#

Channels differ in file-size limits, threading behavior, and upload APIs. If a channel cannot deliver an artifact directly, use the Web UI artifact card or session export as the recovery surface.

For channel setup, see Channels.

Troubleshooting#

If an artifact does not appear:

1. Check the chat or CLI output for artifact events.

2. Open the Web UI session and inspect artifact cards.

3. Export the session if you need durable evidence:

   Copy

   agentos sessions export <session-key>
   

4. Run agentos doctor if a document or media dependency appears missing.