surface_file

Save generated content and return a time-limited download URL.

surface_file

Saves a generated or computed file and returns a time-limited download card in the chat. Use when the agent (or your code) has produced a file at runtime — reports, exports, CSVs, processed images, generated PDFs.

Exactly one of content, content_base64, or source_path must be provided.

Parameters

Name	Type	Required	Description
filename	string	yes	Display name including extension (e.g. report.pdf, data.csv).
content	string	one of three	UTF-8 string content. Use for text files (CSV, JSON, Markdown, plain text).
content_base64	string	one of three	Base64-encoded binary content, no data: prefix. Use for binary files (PDF, images, XLSX).
source_path	string	one of three	Absolute server path to an existing file to copy. Used by skills that write to disk.
content_type	string	no	MIME type override. Inferred from extension if omitted.
description	string	no	Short description shown on the download card.
expires_hours	number	no	Hours until the link expires. Default 24.

Returns

{
  "action": "download",
  "filename": "report.csv",
  "description": "Monthly sales report",
  "size": 4821,
  "downloadUrl": "/api/download/dl_8fk2mx..."
}

On failure: { "error": "...", "details": { "hint": "..." } }.

---

Examples

Text content — CSV report

export async function handle(input, ctx) {
  const rows = input.data.map((row) =>
    Object.values(row)
      .map((v) => `"${String(v).replace(/"/g, '""')}"`)
      .join(',')
  );
  const csv = [Object.keys(input.data[0]).join(','), ...rows].join('\n');

  return await ctx.tools.surface_file({
    filename:      `${input.report_name}.csv`,
    content:       csv,
    description:   `${input.report_name} — ${input.data.length} rows`,
    expires_hours: 48,
  });
}

Text content — Markdown document

export async function handle(input, ctx) {
  const md = `# ${input.title}\n\n${input.body}`;
  return await ctx.tools.surface_file({
    filename:     'summary.md',
    content:      md,
    content_type: 'text/markdown',
    description:  input.title,
  });
}

Binary content — PDF (JavaScript)

export async function handle(input, ctx) {
  const pdfBase64 = generatePdfBase64(input);  // your PDF library
  return await ctx.tools.surface_file({
    filename:       'invoice.pdf',
    content_base64: pdfBase64,
    content_type:   'application/pdf',
    description:    `Invoice #${input.invoice_number}`,
    expires_hours:  72,
  });
}

Binary content — PDF (Python)

async def handle(input, ctx):
    import base64
    pdf_bytes = generate_pdf(input)           # your PDF library
    b64       = base64.b64encode(pdf_bytes).decode()
    return await ctx.tools.surface_file({
        'filename':       'invoice.pdf',
        'content_base64': b64,
        'content_type':   'application/pdf',
        'description':    f"Invoice #{input['invoice_number']}",
        'expires_hours':  72,
    })

Short-lived link for a sensitive file

return await ctx.tools.surface_file({
  filename:       'salary-bands.xlsx',
  content_base64: xlsxBase64,
  content_type:   'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
  description:    'Salary band analysis — confidential',
  expires_hours:  1,
});

Pair with render_ui to show a preview card alongside the download

export async function handle(input, ctx) {
  const csv  = buildCsv(input.data);
  const file = await ctx.tools.surface_file({
    filename:    'results.csv',
    content:     csv,
    description: `${input.data.length} rows`,
  });

  // Show a summary card with the download URL embedded
  return await ctx.tools.render_ui({
    interactive: false,
    spec: {
      root: 'card',
      elements: {
        card: { type: 'card', props: { title: 'Export ready', subtitle: null }, children: ['kv'] },
        kv: {
          type: 'key_value',
          props: {
            items: [
              { key: 'Rows',      value: String(input.data.length) },
              { key: 'Format',    value: 'CSV' },
              { key: 'Expires',   value: '24 hours' },
              { key: 'Download',  value: file.downloadUrl },
            ],
          },
          children: [],
        },
      },
      state: {},
    },
  });
}

---

Notes

• Always registered.
• Generated files are stored securely; the download link expires after expires_hours (default 24).
• For files that already exist in data_public (not generated at runtime), use present_public_file instead.
• For binary output, always base64-encode and pass via content_base64 — do not embed raw bytes in content.