Attach documents to Cortex Agent conversations¶

Let users attach PDFs, Office files, images, and CSVs to a custom agent frontend with a caller’s-rights document tool, per-user stage folders, and authenticated middleware.

This recipe is a reference implementation: review the code and adapt it to your environment before production use.

Let users of a custom agent frontend attach a PDF, a slide deck, a screenshot, or a CSV and ask questions that combine it with governed data. The Cortex Agent API has no file content block, so the file goes to a per-user folder on a stage, the request carries a one-line hint that names it, and the agent reads it with a caller’s-rights document tool only when the question needs it. The middleware holds no Snowflake credentials: every request runs as the user who sent it.

When to use this¶

• A custom frontend on the Cortex Agent REST API needs ad hoc attachments: one or a few files per conversation, used right away.
• Answers should combine an uploaded file with structured data behind a semantic view.
• Each user should only ever see their own uploads through the agent.

When not to use it:

• A shared, persistent document library. Index it with Cortex Search and give the agent a search tool; there is no per-question parsing cost and no size limit per answer.
• Documents far larger than a model context window. The tool returns at most 60,000 characters; split the work or use Cortex Search.
• Hard tenant isolation at the storage layer. A folder per user is enforced by the tool, not by stage privileges (see Gotchas).

How it works¶

Key concepts:

1. A tool, not injected text. The request carries only file names. The agent calls read_document when the question needs a file and skips it when it does not, so irrelevant turns cost nothing extra.
2. Caller’s rights. READ_UPLOADED_DOCUMENT is EXECUTE AS CALLER. The agent keeps a procedure’s rights model when it calls it, so the stage is read with the asking user’s privileges and CURRENT_USER() is that user.
3. The path is built server-side. The tool combines UPLOAD_PREFIX() (u_ plus a hash of CURRENT_USER()) with a file name that must match a strict pattern: no /, no .., one allowed extension. The model can name a file; it cannot name a path.
4. One parser per file type. Types that AI_PARSE_DOCUMENT accepts, including images, go through it in LAYOUT mode. CSV, JSON, and Markdown are read as text.
5. Authenticated middleware. The backend requires the caller’s own PAT or OAuth token on every request and uses it for both the upload and the agent call. It binds to 127.0.0.1 and allows cross-origin calls only from origins you list.

File types¶

AI_PARSE_DOCUMENT reads text. For a chart or photo where you need a description of what it shows, AI_COMPLETE accepts a staged image through TO_FILE with a vision-capable model; add that as a second branch in the tool if you need it.

Prerequisites¶

Quickstart¶

From document-context/:

1. snow sql -f sql/01_setup.sql (as ACCOUNTADMIN): roles, warehouse, database.

2. snow sql -f sql/02_objects.sql: stage, sample store data, semantic view, the document tool, the agent, and the end-user grants.

3. Get your folder name, then upload the sample documents into it:

   Copy code

   snow sql -q "SELECT COOKBOOK_DOCUMENT_CONTEXT.APP.UPLOAD_PREFIX()" \
     --role COOKBOOK_DOCUMENT_CONTEXT_USER --warehouse COOKBOOK_DOCUMENT_CONTEXT_WH
   snow sql -f sql/03_upload_samples.sql -D prefix=<the u_... value>
   

4. snow sql -f sql/04_ask_agent.sql: three questions; see Verify.

5. Optional: run the middleware in app/ and call it with your token.

6. snow sql -f sql/99_teardown.sql (as ACCOUNTADMIN).

Walkthrough¶

The document tool¶

The core of sql/02_objects.sql:

NAME_PATTERN = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]{0,99}\.[A-Za-z0-9]{1,5}")

def run(session, filename):
    if filename is None or not NAME_PATTERN.fullmatch(filename):
        return "[Rejected: pass a bare file name such as report.pdf, with no folders]"
    ...
    prefix = session.sql("SELECT COOKBOOK_DOCUMENT_CONTEXT.APP.UPLOAD_PREFIX()").collect()[0][0]
    relative_path = f"{prefix}/{filename}"
    if ext in PARSE_EXTENSIONS:
        text = session.sql(
            "SELECT AI_PARSE_DOCUMENT(TO_FILE('@COOKBOOK_DOCUMENT_CONTEXT.APP.DOC_UPLOADS', ?), "
            "{'mode': 'LAYOUT'}):content::VARCHAR", params=[relative_path]).collect()[0][0]
    else:
        with SnowflakeFile.open(f"{STAGE}/{relative_path}", "r", require_scoped_url=False) as f:
            text = f.read(MAX_CHARS + 1)

The stage name is a constant and the relative path is a bind parameter. SnowflakeFile with require_scoped_url=False reads a stage path with the caller’s privileges inside a caller’s-rights procedure.

The agent¶

The tool is a generic tool backed by the procedure:

tools:
  - tool_spec:
      type: generic
      name: read_document
      input_schema:
        type: object
        properties:
          filename: {type: string, description: "The file name exactly as listed ..."}
        required: [filename]
tool_resources:
  read_document:
    type: procedure
    identifier: COOKBOOK_DOCUMENT_CONTEXT.APP.READ_UPLOADED_DOCUMENT
    execution_environment: {type: warehouse, warehouse: COOKBOOK_DOCUMENT_CONTEXT_WH}

The orchestration instructions tell the agent to call read_document only for listed files and only when the question needs them, and to treat file text as data rather than instructions. The agent is created with CREATE OR REPLACE AGENT ... COPY GRANTS, so reruns keep the USAGE grant.

The request¶

The hint is one extra text block in the user message:

{"messages": [{"role": "user", "content": [
  {"type": "text", "text": "[Uploaded files available to the read_document tool: q2_board_summary.pdf]"},
  {"type": "text", "text": "Compare the board's projected Q2 revenue for the Southeast with actual Q1 revenue."}
]}]}

For follow-up questions, create a thread (POST /api/v2/cortex/threads), send the first message with thread_id and parent_message_id: 0, and send each follow-up with the previous response’s assistant message ID. The file hint is only needed when a file is first introduced.

The middleware¶

app/backend.py (FastAPI) exposes POST /upload, POST /ask, POST /threads, and GET /health:

• Every endpoint except /health requires Authorization: Bearer <token>. Send X-Snowflake-Authorization-Token-Type: PROGRAMMATIC_ACCESS_TOKEN (the default) with X-Snowflake-User, or OAUTH. Missing or malformed credentials return 401 before anything reaches Snowflake; a token Snowflake rejects also returns 401.
• Uploads open a connector session with the caller’s token, ask Snowflake for UPLOAD_PREFIX(), check it against ^u_[0-9a-f]{32}$, and PUT the file into that folder. File names are validated with the same pattern as the tool, and uploads are capped at MAX_UPLOAD_BYTES (20 MB by default).
• /ask validates every listed file name, builds the hint, and calls /api/v2/databases/COOKBOOK_DOCUMENT_CONTEXT/schemas/APP/agents/INSIGHTS_AGENT:run with the caller’s token and X-Snowflake-Role: COOKBOOK_DOCUMENT_CONTEXT_USER.
• It binds to 127.0.0.1:8000 by default. CORS is off unless ALLOWED_ORIGINS lists exact origins, and interactive API docs are disabled.

cd app
python -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt
export SNOWFLAKE_ACCOUNT=<account identifier>
export SNOWFLAKE_ACCOUNT_URL=https://<account identifier>.snowflakecomputing.com
export ALLOWED_ORIGINS=http://localhost:5173   # your frontend, if it runs on another origin
python backend.py

curl -s -X POST http://127.0.0.1:8000/upload \
  -H "Authorization: Bearer $SNOWFLAKE_PAT" -H "X-Snowflake-User: $SNOWFLAKE_USER" \
  -F "file=@../sample-docs/menu_price_changes.png"
curl -s -X POST http://127.0.0.1:8000/ask \
  -H "Authorization: Bearer $SNOWFLAKE_PAT" -H "X-Snowflake-User: $SNOWFLAKE_USER" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the new Combo Meal price?", "files": ["menu_price_changes.png"]}'

Keep the backend behind your application’s own login, and pass each signed-in user’s Snowflake token (for example from Snowflake OAuth) instead of a shared one.

Verify¶

• 03 lists four files under your u_... folder, returns OK: files are in your folder, returns the menu table from the PNG and the CSV rows from the tool, and rejects ../u_someone_else/q2_board_summary.pdf with [Rejected: pass a bare file name ...].
• 04 returns three rows:
  • pdf + data: tools_called includes read_document and store_analytics, files_read is q2_board_summary.pdf, and the answer compares the board’s $3.30M Southeast projection with actual Q1 Southeast revenue of $3,030,000.00, in line with the +9% change the board summary states.
  • image: files_read is menu_price_changes.png and the answer is $11.49, effective July 15, 2024.
  • file not needed: read_document is not called; the answer is the Northeast at $3,320,000.00.
• Backend, without Snowflake: requests without a Bearer token return 401, file names such as ../x.pdf or x.exe return 400, and a CORS preflight from an origin not in ALLOWED_ORIGINS gets no Access-Control-Allow-Origin header.

Gotchas¶

Teardown¶

snow sql -f sql/99_teardown.sql (as ACCOUNTADMIN) drops the database, which removes the stage and every uploaded file, then the warehouse and both roles. It works without secondary roles because 01 grants the admin role to SYSADMIN. Nothing at the account level needs to be restored.

Adapt this recipe¶

Keep these, so a customized version keeps the recipe’s security model:

• Least privilege: ACCOUNTADMIN only for the scripts listed under Privileges; everything else runs as the recipe’s own role.
• No grants to PUBLIC.
• Caller’s rights: procedures run as EXECUTE AS CALLER, so each user’s own grants apply.
• Credentials: create keys, tokens, and secrets yourself, in a separate terminal, and read them from environment variables. Never put them in a script or give them to an agent.
• Dynamic SQL, if you add any, uses bind variables or an allowlist of identifiers, never text concatenated from user or model input.

Change these to fit your use case:

• Object names. Rename them in every script, including teardown, then check that teardown still removes everything.
• Roles, personas, and users: map them to your own, each granted no more than the recipe grants.
• Data: point the scripts at your tables instead of the sample data, then run Verify again.
• Models and warehouse sizes.

To have a coding agent adapt it:

Adapt the document-context recipe in document-context/ (unzipped from document-context.zip) to <describe your use case>.
Read README.md first. Keep everything the "Adapt this recipe" section says to keep.
Change only names, roles and personas, data, and models.
Show me each changed file before you run anything, then run the recipe's Verify steps.

Run it with a coding agent¶

Install or enable the bundled document-intelligence skill and the check-agent-access
skill from Snowflake-Labs/coco-skills if they are not already available.
Then, from document-context/:
1. Confirm the target with SELECT CURRENT_ACCOUNT(), CURRENT_REGION(), CURRENT_ROLE(),
   CURRENT_WAREHOUSE() and show me the result before creating anything.
2. sql/01_setup.sql runs as ACCOUNTADMIN and creates account-level roles and a
   warehouse. Show me what it creates and wait for my confirmation, then run it
   and sql/02_objects.sql with snow sql -f.
3. Get my folder with SELECT COOKBOOK_DOCUMENT_CONTEXT.APP.UPLOAD_PREFIX() using
   --role COOKBOOK_DOCUMENT_CONTEXT_USER --warehouse COOKBOOK_DOCUMENT_CONTEXT_WH,
   then run snow sql -f sql/03_upload_samples.sql -D prefix=<value>.
4. Run sql/04_ask_agent.sql and compare the three rows with the Verify section.
5. Use check-agent-access to confirm COOKBOOK_DOCUMENT_CONTEXT_USER can use the
   agent and every tool it references.
6. If I want to try the backend in app/, I create and export my own PAT or OAuth
   token. Never create, print, or store a token yourself.
7. Only touch objects whose names start with COOKBOOK_DOCUMENT_CONTEXT.
   Run sql/99_teardown.sql when I say so.

Related skills¶

• document-intelligence (bundled with Cortex Code): extraction, parsing, and classification over staged files with Cortex AI functions. Use it when a document type needs more than the text this tool returns, for example structured field extraction.
• check-agent-access (Snowflake-Labs/coco-skills): audits whether a role can use an agent and every tool behind it.

References¶

• Parsing documents with AI_PARSE_DOCUMENT
• AI_PARSE_DOCUMENT
• Create and manage agents (custom tools)
• Cortex Agents REST API
• Cortex Agents Run API
• Reading files with a Python stored procedure
• Caller’s rights and owner’s rights stored procedures
• Using programmatic access tokens for authentication
• Executing SQL statements with Snowflake CLI