Skip to content

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:

  • OpenAIConfig
  • OpenAIResponsesConfig
  • AnthropicConfig
  • GeminiConfig

Note

Gemini does not support downloading file bytes via its Files API. FilesAPI.read() raises NotImplementedError for Gemini.

Create a Files API client#

1
2
3
4
5
6
7
8
from autogen.beta import FilesAPI
from autogen.beta.config import OpenAIResponsesConfig

config = OpenAIResponsesConfig(
    model="gpt-5-mini",
    api_key="YOUR_API_KEY",
)
files = FilesAPI(config)

Upload files#

You can upload from a local path or from in-memory bytes.

Upload from local path#

1
2
uploaded = await files.upload(path="report.pdf", purpose="assistants")
print(uploaded.file_id)

Upload from bytes#

1
2
3
4
5
6
7
content = b"hello from ag2 beta"
uploaded = await files.upload(
    data=content,
    filename="hello.txt",
    purpose="assistants",
)
print(uploaded.file_id)

If data is provided without filename, upload() raises ValueError.

Read, list, and delete#

1
2
3
4
5
6
7
8
9
# list all uploaded files for this provider/account
all_files = await files.list()

# download bytes for one file (not supported by Gemini)
file_data = await files.read(all_files[0].file_id)
print(file_data.name, len(file_data.data), file_data.media_type)

# delete by file ID
await files.delete(all_files[0].file_id)

You can also call read() from an UploadedFile:

1
2
uploaded = await files.upload(path="report.pdf")
content = await uploaded.read(files)

Use uploaded files in agent requests#

After upload, pass the returned file_id to an input event.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
from autogen.beta import Agent
from autogen.beta.events import DocumentInput

agent = Agent(
    "assistant",
    config=config,
)

uploaded = await files.upload(path="report.pdf")
doc = DocumentInput(file_id=uploaded.file_id)

reply = await agent.ask("Summarize this report.", doc)
print(reply.body)

For more multimodal details, see Multimodal Inputs.