Gmail agent with file attachments

This is the monday assistant loop plus one new capability: uploading files in a tool call. It demonstrates the pattern behind every file-accepting tool.

How files work in an agent loop

Gmail’s send-email tool declares its attachments field as a file input ("format": "engini/file" in the tool schema). Two things follow:

The model never produces base64. When Engini wraps the schema for the model, file fields become plain string fields. The model picks a file by name (a reference key), not by content.
You decide what those names resolve to. You hand handle_tool_calls a registry of files; the SDK swaps the key the model chose for the real file and encodes it on the way out.

The recipe

from pathlib import Path
from engini import Engini, File
from engini.providers.anthropic import AnthropicProvider

client = Engini(provider=AnthropicProvider())   # reads ENGINI_API_KEY
conn_id = next(c.connection_id for c in client.connections.list(application="gmail"))

toolset = client.toolset(connections={"gmail": conn_id})
tools = toolset.tools()          # the attachments field appears as string keys

# The files the agent MAY attach, referenced by name
def load_attachments(directory: Path) -> dict[str, File]:
    return {
        p.name: File.from_path(p)
        for p in sorted(directory.iterdir())
        if p.is_file() and not p.name.startswith(".")
    }

files = load_attachments(Path("files"))

Tell the model what’s available in the system prompt:

system = (
    "You are an assistant that sends email through the user's Gmail account "
    "via Engini tools. Always confirm the recipient, subject, and attachments. "
    "These files are available to attach, referenced by name: "
    + ", ".join(repr(name) for name in files)
)

The loop is identical to the monday agent, with one changed line - the file registry:

results = toolset.handle_tool_calls(reply, files=files)

The model decides which file to attach (by name); your code controls what those names resolve to. The model never sees file bytes. An unknown reference key raises EnginiValidationError.

Without an LLM

Outside an agent loop, pass a File straight into the tool call:

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

Run the original

python/examples/gmail-agent/ - includes a sample attachment; drop your own files into its files/ folder:

cd python/examples/gmail-agent
uv run agent.py "Email alex@acme.com the Q3 report and mention it's attached"

More on file handling (constructors, mime types, CLI --file): File inputs.

Start here

REST API

CLI

SDK

How files work in an agent loop

The recipe

Without an LLM

Run the original

​How files work in an agent loop

​The recipe

​Without an LLM

​Run the original

How files work in an agent loop

The recipe

Without an LLM

Run the original