How to Handle Files in Pydantic AI Agents

Developers choose Pydantic AI to add data validation to their agent workflows. But Pydantic AI is a framework, not a platform. It lacks built-in storage, file hosting, or a way to handle binary data. When your agent needs to read a PDF, make a report, or analyze a dataset, you face four problems that standard libraries often miss:

• Persistence: Local storage (./tmp) disappears in serverless setups like Modal, Vercel, or AWS Lambda. Files from one run are gone in the next, which breaks state.
• Validation: You need to check for valid file paths, supported types, and file sizes before the agent wastes tokens trying to process them.
• Sharing: The agent needs a way to send the final file (like a CSV or image) to a user or another agent via a URL.
• Latency: Loading large datasets into memory can crash the agent. You need to move file processing to a storage layer. To fix this, we combine Pydantic AI tools with a file storage MCP (Model Context Protocol) server. This connects your logic to cloud storage.

Helpful references: Fastio Workspaces, Fastio Collaboration, and Fastio AI.

• LangChain Document Loader Alternatives for Better File HandlingLangChain document loader alternatives let you ingest files for RAG and agent applications without LangChain's...
• How to Use the LangChain File System for Persistent DataThe LangChain file system integration enables AI agents to read, write, and organize files on local disks or cloud...
• How to Use LangChain Document LoadersDocument loaders are the first step in any RAG pipeline. They pull data from over 100 sources into a standard format...
• ChatGPT File Upload Limits: How to Handle Large Files and FoldersChatGPT limits file uploads to 512MB per file with total storage limits per user, creating problems for large datasets.
• How to Manage Google AI Studio FilesGoogle AI Studio lets developers upload documents, images, and video for Gemini's large context window. But the file...
• How to Manage Files with Google ADK AgentsGoogle ADK (Agent Development Kit) provides a structured way for agents to manage binary data through the Artifacts...

More on this subject: Agent File and Document Workflows (183 guides)

In Pydantic AI, tools are Python functions with the @agent.tool decorator. To handle files securely, use Pydantic models to check inputs (like filenames and paths) before the tool runs. This stops the agent from guessing file paths and keeps it within your storage rules. Here is how to define a file upload tool using the remote Fastio MCP endpoint. We use Field to tell the LLM exactly what each parameter does:

from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext
import requests  # no Fastio SDK; call the MCP endpoint directly

class UploadRequest(BaseModel):
    local_path: str = Field(..., description="Path to the local file to upload")
    destination_folder: str = Field(..., description="Target folder in Fastio (e.g., 'reports/2024')")
    public_share: bool = Field(default=False, description="Whether to generate a public share link")

agent = Agent(
    'openai:gpt-4o',
    system_prompt='You are a file management assistant. Always validate file extensions before uploading.'
)

@agent.tool
async def upload_file(ctx: RunContext, request: UploadRequest) -> str:
    """Uploads a file to secure cloud storage and returns a shareable link."""
    fastio_auth = {'Authorization': f'Bearer {ctx.deps.api_key}'}  # POST to https://mcp.fast.io/mcp/key
    
    ### Upload via Streamable HTTP for efficiency
    result = await client.upload(
        request.local_path.
        folder=request.destination_folder.
        share=request.public_share
    )
    
    return f"File '{result.name}' uploaded successfully. Access URL: {result.url}"

This ensures the agent can only upload if it provides valid strings. Pydantic's validation lets you add custom checks for file existence or extensions (like .csv or .json), which stops errors before they happen.

Local file operations are risky for production agents because they tie your app to one machine. Instead of saving to disk, use the Fastio MCP server to handle files over the network. This keeps your agent stateless and portable. Fastio provides cloud workspaces and a consolidated MCP toolset over Streamable HTTP. It is a file management suite built for agent workflows.

Why use an MCP Server for Pydantic AI?

• Universal Protocol: MCP connects LLMs to data. It works with Claude, Pydantic AI, LangChain, and CrewAI.
• No Local Footprint: Stream files from a URL to storage (using the save_url tool) without using the agent's RAM or disk. This matters for large datasets in restricted environments.
• Security & Auth: The MCP connection handles authentication. Your agent does not need your S3 keys; it only needs to know how to call the tool. This keeps secrets out of prompts and logs.
• Version Control: Track file changes automatically. Your agent can roll back to a previous version if a data change fails. To connect your Pydantic AI agent, connect to the remote Fastio MCP server at https://mcp.fast.io/mcp using Streamable HTTP or legacy SSE at https://mcp.fast.io/sse.

Give Your AI Agents Persistent Storage

Get persistent cloud storage and a consolidated MCP toolset for your AI agents.

Start 14-Day Trial

Once files are stored, you often need to read them. Pydantic AI agents can use Fastio's Intelligence Mode for RAG (Retrieval-Augmented Generation) on documents. This removes the need for a vector database. Instead of writing code to parse PDFs and chunk text:

1. Agent uploads file to a workspace with Intelligence Mode on.
2. Fastio indexes the content with embedding models.
3. Agent uses the ask_about_file tool to query the document.

@agent.tool
async def analyze_document(ctx: RunContext, filename: str, question: str) -> str:
    """Asks a question about a stored document using semantic search. Use this for PDFs and large docs."""
    # This delegates the query to the remote MCP tool, saving context tokens
    answer = await call_mcp_tool("ask_about_file", {"filename": filename, "question": question})
    return answer

This separation keeps your Pydantic AI agent light. It stops context window issues by only sending relevant text from a large PDF to the LLM. It also keeps your agent fast when working with large data.

Security is critical when agents handle files. As agents get more autonomous, the risk of data leaks or deletion grows. Follow these rules to keep data safe:

• Use Version History and Permissions: In multi-agent systems, Fastio's per-file version history and granular folder permissions prevent accidental overwrites and keep an auditable trail of edits.
• Validate Extensions & Size: In your Pydantic models, use Field(pattern=r'.*\.pdf$') and le=10_000_000 (10MB) to limit file types and sizes. This stops the agent from trying to read a 1GB video as text.
• Audit Logging: Fastio logs every read, write, and share. This creates a trail for debugging. If an agent deletes a file, you will know which tool call did it.
• Lifecycle Management: Set expiration dates on links. If an agent makes a report for a user, set an expiration date on the link to reduce security risks.
• Least Privilege: Create specific workspaces in Fastio for different agents. A research agent does not need access to the finance agent's folder. Use the MCP server's permissions to enforce this.