feat(beta): implement Files API client and related functionality

[vvlrff]

Summary

• Add provider-agnostic FilesAPI for file management (upload / list / read / delete)
• Support OpenAI, Anthropic, and Gemini providers
• UploadedFile extends FileIdInput — pass directly to agent.ask() without extra conversion
• Extend BinaryResult with .name and .content() for generated files
• Add create_files_client() to ModelConfig protocol
• Fix OpenAI mapper: file_id and filename are mutually exclusive in Responses API
• Add Anthropic files-api-2025-04-14 beta header auto-injection when messages contain file references
• Add Gemini FileIdInput support in mapper (was previously unsupported)

API

Upload & manage files

from autogen.beta.config import OpenAIResponsesConfig
from autogen.beta.files import FilesAPI

config = OpenAIResponsesConfig(model="gpt-4o", api_key="...")
files = FilesAPI(config)

# Upload from bytes
uploaded = await files.upload(data=b"...", filename="data.csv")

# Upload from path
uploaded = await files.upload(path="/tmp/report.pdf")

# List all files
all_files = await files.list()

# Read file content (OpenAI, Anthropic only)
content = await files.read(file_id="file-abc123")
print(content.name, len(content.data))

# Delete
await files.delete(file_id="file-abc123")

Use uploaded file with agent

from autogen.beta import Agent

agent = Agent("analyst", "You analyze data.", config=config)

# UploadedFile is an Input — pass directly to agent.ask()
reply = await agent.ask("Summarize this CSV", uploaded)
print(reply.body)

Read uploaded file content

# Via FilesAPI
content = await files.read(uploaded.file_id)

# Via UploadedFile convenience method
content = await uploaded.read(client=files)

print(content.name)  # "data.csv"
print(content.data)  # b"..."

Access generated files

reply = await agent.ask("Generate a chart")

for file in reply.files:
    print(file.name)                # from metadata
    data = await file.content()     # raw bytes

[codecov]

Codecov Report

❌ Patch coverage is 82.24852% with 30 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
autogen/beta/files/api.py	48.00%	13 Missing ⚠️
autogen/beta/config/anthropic/anthropic_client.py	14.28%	6 Missing ⚠️
autogen/beta/config/openai/config.py	60.00%	2 Missing ⚠️
autogen/beta/testing.py	50.00%	2 Missing ⚠️
autogen/beta/config/anthropic/config.py	66.66%	1 Missing ⚠️
autogen/beta/config/config.py	66.66%	1 Missing ⚠️
autogen/beta/config/dashscope/config.py	50.00%	1 Missing ⚠️
autogen/beta/config/gemini/config.py	66.66%	1 Missing ⚠️
autogen/beta/config/ollama/config.py	50.00%	1 Missing ⚠️
autogen/beta/config/openai/mappers.py	83.33%	0 Missing and 1 partial ⚠️
... and 1 more

Files with missing lines	Coverage Δ
autogen/beta/__init__.py	100.00% <100.00%> (ø)
autogen/beta/agent.py	91.10% <ø> (-0.04%)	⬇️
autogen/beta/config/anthropic/files.py	100.00% <100.00%> (ø)
autogen/beta/config/anthropic/mappers.py	89.18% <100.00%> (+0.17%)	⬆️
autogen/beta/config/gemini/files.py	100.00% <100.00%> (ø)
autogen/beta/config/gemini/mappers.py	76.29% <100.00%> (-0.45%)	⬇️
autogen/beta/config/openai/files.py	100.00% <100.00%> (ø)
autogen/beta/events/types.py	88.31% <100.00%> (+0.81%)	⬆️
autogen/beta/files/__init__.py	100.00% <100.00%> (ø)
autogen/beta/files/protocol.py	100.00% <100.00%> (ø)
... and 11 more

... and 53 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.