> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/builtin-tools/present_public_file) or [show\_file\_excerpt](/builtin-tools/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

```json theme={null}
{
  "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):

```json theme={null}
{
  "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

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

### Show a product image

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```json theme={null}
{ "filename": "step1-navigate.png", "caption": "Step 1: Open Settings" }
```

```json theme={null}
{ "filename": "step2-click-security.png", "caption": "Step 2: Click Security" }
```

```json theme={null}
{ "filename": "step3-enable-2fa.png", "caption": "Step 3: Toggle 2FA on" }
```

***

## Call from your own custom tool

```js theme={null}
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,
  });
}
```

```python theme={null}
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.