present_public_file

Present a public file as a download card in the chat.

present_public_file

Presents a public file as a downloadable card in the chat. Use this when a user asks for a file or when you want to offer a document for download.

Requires the file to exist in the agent’s public data (uploaded via the Data → Public tab in the dashboard).

Parameters

Name	Type	Required	Description
filename	string	yes	The exact filename of the public file to present. Case-sensitive, including extension.
description	string	no	Short description rendered alongside the download card.

Returns

{
  "action": "download",
  "filename": "user-guide.pdf",
  "description": "User guide v3",
  "size": 1843291,
  "downloadUrl": "https://cdn.../user-guide.pdf?..."
}

On failure (file not in manifest, missing from storage, or presign error):

{
  "error": "present_public_file failed: file not found.",
  "details": {
    "filename": "user-guide.pdf",
    "available_public_files": ["quickstart.pdf", "faq.md", "pricing.pdf"],
    "hint": "Use one of the filenames listed in available_public_files."
  }
}

The agent can retry with the correct filename from available_public_files.

---

Examples

Offer a single document

{ "filename": "refund-policy.pdf" }

Offer a document with context

{
  "filename": "integration-guide.pdf",
  "description": "Step-by-step guide for connecting your CRM"
}

Offer different files based on the user’s plan

Add a rule to your agent’s configuration:

When a user asks for the API docs, present api-docs-pro.pdf for Pro users
and api-docs-free.pdf for Free users. Read the user's plan from memory first.

The agent calls:

{ "filename": "api-docs-pro.pdf", "description": "Full API reference (Pro)" }

---

Call from your own custom tool

export async function handle(input, ctx) {
  return await ctx.tools.present_public_file({
    filename:    input.doc_name,
    description: input.doc_label ?? 'As requested',
  });
}

async def handle(input, ctx):
    return await ctx.tools.present_public_file({
        'filename':    input['doc_name'],
        'description': input.get('doc_label', 'As requested'),
    })

Notes

• Only registered when the agent has at least one file in data_public.
• Filenames are matched exactly (case-sensitive, including extension).
• Download links are short-lived and expire automatically.
• For binary files that should be shown inline rather than downloaded, use show_image. For displaying text file contents inline, use show_file_excerpt. For files generated at runtime, use surface_file.