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

# File inputs

> Pass files to tools - directly, or by reference in an LLM loop.

Tools that accept files mark the field in their `inputSchema` with `"format": "engini/file"` (a list of files is an array with that format). The SDK's `File` helper handles encoding.

## Direct execution

<CodeGroup>
  ```python Python theme={null}
  from engini import Engini, File

  client.tools.execute(
      "gmail_send_mail",
      {
          "to": "alex@acme.com",
          "subject": "Reports",
          "body": "See attached.",
          "attachmentsarray": [File.from_path("q3-report.pdf"), File.from_path("chart.png")],
      },
      connection_id=conn_id,
  )
  ```

  ```typescript TypeScript theme={null}
  import { Engini, File } from "@engini/sdk";

  await client.tools.execute(
    "gmail_send_mail",
    {
      to: "alex@acme.com",
      subject: "Reports",
      body: "See attached.",
      attachmentsarray: [File.fromPath("q3-report.pdf"), File.fromPath("chart.png")],
    },
    { connectionId },
  );
  ```
</CodeGroup>

Constructors: `File.from_path(path)` (mime type inferred), `File.from_bytes(data, filename=...)`, `File.from_base64(b64, filename=...)` - camelCase equivalents in TS. In TypeScript, `File` shadows the global DOM/Node `File` inside your import scope.

## Files in an LLM loop

Models can't emit binary content, so the SDK rewrites file fields into string **reference keys**: you register files under names, the model picks a name, and `handle_tool_calls` resolves it.

<CodeGroup>
  ```python Python theme={null}
  files = {"q3-report.pdf": File.from_path("q3-report.pdf")}
  results = toolset.handle_tool_calls(llm_response, files=files)
  ```

  ```typescript TypeScript theme={null}
  const results = await toolset.handleToolCalls(llmResponse, {
    files: { "q3-report.pdf": File.fromPath("q3-report.pdf") },
  });
  ```
</CodeGroup>

An unknown reference key raises `EnginiValidationError`.

## From the CLI

```bash theme={null}
engini tools call gmail_send_mail --args '{"to":"alex@acme.com"}' \
  --file attachmentsarray=@report.pdf --file attachmentsarray=@chart.png
```

Repeat `--file field=@path` with the same field name to build a list.