Files API - AG2
Files
The Beta Files API provides a provider-agnostic interface for uploading, listing, reading, and deleting files used by multimodal workflows. It wraps each provider's native files endpoint behind a single async client.
When to use Files API
Use FilesAPI when you want to:
- Upload large assets once, then reference them by
file_id - Manage file lifecycle in your app (list and delete stale files)
- Keep file handling logic consistent across supported providers
Supported providers
FilesAPI is available for:
OpenAIConfigOpenAIResponsesConfigAnthropicConfigGeminiConfigXAIConfig
Note
Gemini does not support downloading file bytes via its Files API. FilesAPI.read() raises NotImplementedError for Gemini.
Create a Files API client
<br>1<br>2<br>3<br>4<br>5<br>6<br>7<br>8<br> |
<br>from autogen.beta import FilesAPI<br>from autogen.beta.config import OpenAIResponsesConfig<br>config = OpenAIResponsesConfig(<br> model="gpt-5-mini",<br> api_key="YOUR_API_KEY",<br>)<br>files = FilesAPI(config)<br> |
Upload files
You can upload from a local path or from in-memory bytes.
Upload from local path
<br>1<br>2<br> |
<br>uploaded = await files.upload(path="report.pdf", purpose="assistants")<br>print(uploaded.file_id)<br> |
Upload from bytes
<br>1<br>2<br>3<br>4<br>5<br>6<br>7<br> |
<br>content = b"hello from ag2 beta"<br>uploaded = await files.upload(<br> data=content,<br> filename="hello.txt",<br> purpose="assistants",<br>)<br>print(uploaded.file_id)<br> |
If data is provided without filename, upload() raises ValueError.
Read, list, and delete
<br>1<br>2<br>3<br>4<br>5<br>6<br>7<br>8<br>9<br> |
<br># list all uploaded files for this provider/account<br>all_files = await files.list()<br># download bytes for one file (not supported by Gemini)<br>file_data = await files.read(all_files[0].file_id)<br>print(file_data.name, len(file_data.data), file_data.media_type)<br># delete by file ID<br>await files.delete(all_files[0].file_id)<br> |
You can also call read() from an UploadedFile:
<br>1<br>2<br> |
<br>uploaded = await files.upload(path="report.pdf")<br>content = await uploaded.read(files)<br> |
Use uploaded files in agent requests
After upload, pass the returned file_id to an input event.
<br> 1<br> 2<br> 3<br> 4<br> 5<br> 6<br> 7<br> 8<br> 9<br>10<br>11<br>12<br>13<br> |
<br>from autogen.beta import Agent<br>from autogen.beta.events import DocumentInput<br>agent = Agent(<br> "assistant",<br> config=config,<br>)<br>uploaded = await files.upload(path="report.pdf")<br>doc = DocumentInput(file_id=uploaded.file_id)<br>reply = await agent.ask("Summarize this report.", doc)<br>print(reply.body)<br> |
For more multimodal details, see Multimodal Inputs.