interactions.create with agent="deep-research-*" returns 501 not_implemented for any document input — even the docs’ own example
Summary
Attaching a document ({"type": "document", ...}) to a Deep Research agent interaction (background=True, as required) fails with a generic 501 not_implemented error. This reproduces with every documented way of specifying a document (uri pointing to a Gemini Files API resource, uri pointing to a public HTTPS URL, and inline base64 data), with every deep-research agent variant, and — critically — with the exact code sample from the official docs page, copy-pasted verbatim.
Environment
- google-genai Python SDK version: Reproduced on both 2.8.0 and the latest 2.17.0
- Python: 3.11 / 3.13 (reproduced on both)
- Endpoint: client.interactions.create(...) (the “next-gen” Interactions API)
Steps to reproduce
python
from google import genai
client = genai.Client(api_key=API_KEY, http_options={"timeout": 60000})
interaction = client.interactions.create(
agent="deep-research-preview-04-2026",
input=[
{"type": "text", "text": "What is this document about?"},
{
"type": "document",
"uri": "https://arxiv.org/pdf/1706.03762",
"mime_type": "application/pdf",
},
],
background=True,
)
This is the exact example shown on the Deep Research docs page under “Multimodal input” / document attachment.
Expected behavior
An Interaction object is returned with status="in_progress", and the agent eventually reads the document and produces a summary (as the docs imply).
Actual behavior
google.genai._interactions.InternalServerError: Error code: 501 - {'error': {'message': 'There was a problem processing your request. You will not be charged.', 'code': 'not_implemented'}}
This happens synchronously on the `create()` call itself — before any background processing starts.
Variations tried (all fail identically)
- deep-research-preview-04-2026 + uri = Gemini Files API resource (https://generativelanguage.googleapis.com/v1beta/files/...) → 501 not_implemented
- deep-research-preview-04-2026 + uri = public HTTPS URL (arXiv PDF, straight from the docs example) → 501 not_implemented
- deep-research-pro-preview-12-2025 + uri = Gemini Files API resource → 501 not_implemented
- deep-research-max-preview-04-2026 + uri = Gemini Files API resource → 501 not_implemented
Sanity check: document input works fine without an agent
The identical document/uri mechanism (same Gemini Files API resource, same request shape) works perfectly against a plain model interaction (no agent, foreground):
interaction = client.interactions.create(
model="gemini-2.5-pro",
input=[
{"type": "text", "text": "Summarize this document in one sentence."},
{"type": "document", "uri": file_ref.uri, "mime_type": "application/pdf"},
],
)
# -> status="completed", correct real summary of the file content
```
Happy to provide any additional information as needed. Thank you very much for your help!