show_image

Render a public image inline in the chat bubble.

show_image

Renders a public image inline in the chat bubble. Use when the user asks to see an image, or when a visual is the clearest answer.

Supported formats: .png, .jpg, .jpeg, .gif, .webp, .svg, .bmp, .ico.

For non-image documents, use present_public_file or show_file_excerpt instead.

Parameters

Name	Type	Required	Description
filename	string	yes	Exact filename of an image in the agent’s public files.
alt_text	string (≤300)	no	Alt text for accessibility. Defaults to the filename.
caption	string (≤300)	no	Optional caption rendered below the image.

Returns

{
  "action": "image",
  "filename": "diagram-architecture.png",
  "src_url": "https://cdn.../diagram-architecture.png?...",
  "mime": "image/png",
  "size": 18421,
  "alt_text": "System architecture diagram",
  "caption": "Architecture as of v2.0"
}

On failure (not in manifest, unsupported format, or missing from storage):

{
  "error": "show_image failed: not an image file.",
  "details": {
    "filename": "report.pdf",
    "rejection_reason": "unsupported extension",
    "available_image_files": ["logo.png", "diagram.webp", "screenshot.jpg"],
    "suggested_tool": "present_public_file",
    "hint": "Use present_public_file for PDF files."
  }
}

---

Examples

Show a diagram with a caption

{
  "filename": "data-flow-diagram.png",
  "alt_text": "Data flow through the pipeline",
  "caption": "Fig 1: Data flow — ingestion to storage"
}

Show a product image

{
  "filename": "product-hero.jpg",
  "alt_text": "Wireless headphones in midnight black",
  "caption": "Available in 3 colours. Click to view all."
}

Show a screenshot in a how-to

When the agent is walking a user through a process, it can show a screenshot at the right moment:

{
  "filename": "settings-2fa-screen.png",
  "alt_text": "Settings page with Two-factor authentication section highlighted",
  "caption": "Settings → Security → Two-factor authentication"
}

Show multiple images sequentially

The agent can call show_image multiple times to display a step-by-step visual guide. Each call produces its own inline image card in the conversation.

{ "filename": "step1-navigate.png", "caption": "Step 1: Open Settings" }

{ "filename": "step2-click-security.png", "caption": "Step 2: Click Security" }

{ "filename": "step3-enable-2fa.png", "caption": "Step 3: Toggle 2FA on" }

---

Call from your own custom tool

export async function handle(input, ctx) {
  return await ctx.tools.show_image({
    filename: input.image_name,
    alt_text: input.alt ?? input.image_name,
    caption:  input.caption,
  });
}

async def handle(input, ctx):
    return await ctx.tools.show_image({
        'filename': input['image_name'],
        'alt_text': input.get('alt', input['image_name']),
        'caption':  input.get('caption'),
    })

Notes

• Images appear only when explicitly returned by this tool — they cannot be injected through the agent’s text output.
• Only registered when the agent has at least one public file.
• Image links are short-lived and expire automatically.