ISSUE DESCRIPTION Deferred capabilities throw error 400 with Deepseek models Initial…
- User
ISSUE DESCRIPTION
Deferred capabilities throw error 400 with Deepseek models
Initial Checks
- I'm using the latest version of Pydantic AI
- I've searched for my issue in the issue tracker before opening this issue
Description
When running an agent using a DeepSeek reasoning model, using
Capability(..., defer_loading=True)causes aModelHTTPError: status_code: 400during execution loop turns.openai.BadRequestError: Error code: 400 - {'error': {'message': 'The `reasoning_content` in the thinking mode must be passed back to the API.', 'type': 'invalid_request_error', 'param': None, 'code': 'invalid_request_error'}}This is triggered because DeepSeek requires the original
reasoning_contentproduced during the thinking phase to be passed back exactly as-is in the subsequent conversation message history array. Whendefer_loading=True, the graph loop intercepted by PydanticAI's capability runner seems to drop or fail to serialize/propagate thereasoning_contenttoken block back to DeepSeek's chat completions endpoint.Setting
defer_loading=Falsesolves the issue, and the agent executes successfully.Minimal, Reproducible Example
# Remember to export the DEEPSEEK_API_KEY environment variable first, then run this code import random from pydantic_ai import Agent, RunContext from pydantic_ai.capabilities import Capability def roll_dice() -> str: """Roll a six-sided die and return the result.""" return str(random.randint(1, 6)) def get_player_name(ctx: RunContext[str]) -> str: """Get the player's name.""" return ctx.deps agent = Agent( 'deepseek:deepseek-v4-flash', deps_type=str, instructions=( "You're a dice game, you should roll the die and see if the number " "you get back matches the user's guess. If so, tell them they're a winner. " "Use the player's name in the response." ), capabilities=[Capability(id='DICE_ROLL', tools=[get_player_name, roll_dice], defer_loading=True)] # Change this to False and the agent will run successfully. ) dice_result = agent.run_sync('My guess is 4', deps='Anne') print(dice_result.output)Logfire Trace
No response
Python, Pydantic AI & LLM client version
- Python:
3.14 - Pydantic AI:
1.106.0 - LLM provider SDK: deepseek
ADDITIONAL ADVICE
Since you are given a git repository, you can use git commands to simplify your work. For example, if you made a mistake and want to revert your changes, you can use
git checkout <file>to restore the file to its original state. You can also reset all changes in the repository usinggit reset --hardcommand. Additionally, you can usegit stashandgit stash popto temporarily save your changes and restore them later. Finally, you can see the changes that you've made (which will be submitted when you callsubmit) usinggit statusorgit diffcommands. However you don't need to usegit addorgit commitbefore submitting your changes. In fact,submitonly submits currently unstaged changes because it usesgit diffto get the changes that need to be submitted.CHECKLIST
Before submitting your solution, please go over the following checklist and make sure you've done everything:
- If an error was reported in the issue description, I have successfully reproduced it.
- If an error was reported in the issue description, I have confirmed that my fix resolves the error.
- I have thought about edge cases and made sure my fix handles them as well.
- I have run existing tests in the repository that might have been affected by the change I made and confirmed that they pass. I want you to list every bullet from this checklist and write your reasoning for why you think you did it or didn't need to.
Repository has been uploaded and your shell is currently at the repository root. Time to solve the issue!
(Current directory: /pydantic-ai, current file: none) bash-$
Assistant
Let me start by understanding the repository structure and the issue. The issue is about DeepSeek models requiring
reasoning_contentto be passed back in the conversation history. When usingdefer_loading=Truewith capabilities, the system drops or fails to serialize/propagate thereasoning_contenttoken block back to DeepSeek's API.Let me explore the repository structure first.
Assistant
Now let me explore the capabilities module and understand how
defer_loadingworks.Assistant
Let me look at the key files related to the issue — messages, capabilities, and deferred loading:
Assistant
Let me search for
reasoning_contentin the messages file and other relevant files.Assistant
Interesting, no "reasoning_content" in messages.py. Let me search across the entire codebase for it.
Assistant
Let me now look at the key files to understand how reasoning_content is handled and where it might be lost
Assistant
Let me look at the key files related to deferred loading and process history:
Assistant
Let me now look at the process_history capability:
Assistant
Let me now look at the agent graph to understand how deferred loading works:
Assistant
Let me look deeper at the relevant code. Let me look at the OpenAI model code where
reasoning_contentis processedAssistant
Let me look at the ThinkingPart class and how it flows through:
Assistant
Now let me look at
ThinkingPartclass itself:Assistant
Now let me look at the DeepSeek provider and the capability wrapper:
Assistant
Let me look at the capability wrapper to understand how capabilities intercept the flow
Assistant
Let me look more closely at the model request node construction and how messages are built for API
Assistant
Let me look at the ModelRequestNode class and the key
_build_requestmethodAssistant
Let me look at the model's message mapping in OpenAI
Assistant
Let me find where
map_assistant_messageis called - the key messageAssistant
Let me look at the
_map_messagesand_map_messagemethodsAssistant
Let me look at the DeferredCapabilityLoaderToolset
Assistant
Let me look at the
CallToolsNodein the agent graph to understand how model responses with tool calls are handledAssistant
Let me look at the pending messages capability and the process_event_stream capability, which may be relevant
Assistant
Let me look at the DeepSeek test file and see if there are any tests related to reasoning_content
Assistant
Let me look at the rest of the
_run_streamin CallToolsNode to see how tool calls interact with thinkingAssistant
Let me look at how the OpenAI types are defined and whether
reasoning_contentwould be acceptedAssistant
Let me check the OpenAI library types
Assistant
Let me look at that TypedDict:
Assistant
Let me check if the OpenAI library strips unknown fields from the TypedDict
Assistant
Let me look at how
_model_response_to_message_paramor the mapping works in the context of streaming responsesAssistant
Let me look at how
ModelResponseis cut down or cleanedAssistant
Let me look at
_clean_message_historyin detail:Assistant
Let me look at where the response is processed in the OpenAI model - how model responses are
Assistant
Let me look at the
process_tool_callsfunction to understand the tool call processing flowAssistant
Let me look at that function:
Assistant
Let me look at the streaming response handling in the OpenAI model
Assistant
Let me look at
OpenAIStreamedResponsein detailAssistant
Let me look at the
ModelResponsePartsManagerto understand how parts are collected duringAssistant
The
ModelResponsePartsManagermight be in the models module. Let me search for it:Assistant
Let me look at the parts manager:
Assistant
Let me check the
_map_messagesin the OpenAI chat model:Assistant
Let me check git log for recent changes relevant to this issue:
Assistant
Let me look more specifically at the deferred capability flow and search for where the issue might be. Let me look at how
before_model_requestaffects message historyAssistant
Let me look at
prepare_messagesin the OpenAI model:Assistant
Let me look at the base
Modelclass forprepare_messagesAssistant
Let me look at the base Model.prepare_messages:
Assistant
Let me check how the OpenAI library sends requests and whether it strips unknown fields from the TypedDict
Assistant
Let me look at the
_deferred_capabilities.pyfile:Assistant
Let me look at
OpenAIModelProfile.from_profileto understand how the profile is resolvedAssistant
The
from_profilemethod likely comes from the parentModelProfile. Let me check the parent class:Assistant
Let me look at that method
Assistant
Let me look at the recent commit that introduced deferred loading to understand the feature better
Assistant
Let me search for tests that combine deferred capabilities with thinking or reasoning:
Assistant
Let me look at the deferred capability tests around line 2345
Assistant
Let me check how the OpenAI client serializes TypedDict for requests:
Assistant
Let me look at
_map_user_messagein the OpenAI modelAssistant
Let me look at
_map_user_messageAssistant
Let me check the deepseek_model_profile in the profiles module
Assistant
Let me write a script to reproduce the issue. First, let me understand what the exact flow looks like with deferred loading by running an existing test:
Assistant
Let me use the right Python path
Assistant
Let me create a test to check the message mapping:
Assistant
Good, the mapping is correct. Let me now test the full message mapping flow:
Assistant
Let me search for any test that combines deferred capabilities with deepseek or thinking models:
Assistant
Let me check how the OpenAI client serializes messages for the API request:
Assistant
Let me check if the OpenAI SDK strips extra keys:
Assistant
Let me check
openapi_dumpsto see if it strips unknown fields:Assistant
Let me find the right import:
Assistant
Let me try to create a more complete reproduction test to understand the issue
Assistant
Let me check the AgentInfo type and fix the test
Assistant
Let me look at AgentInfo:
Assistant
Let me look at how the model gets wrapped in the agent flow to see if the profile could change
Assistant
Let me look at the WrapperModel:
Assistant
Let me look at the fallback model to see if there could be a profile change
Assistant
Let me take a step back and search for any related issue or fix in the git history
Assistant
Let me check those commits
Assistant
Let me look at
synthesize_local_tool_search_messagesAssistant
Let me look at the
CapabilityclassAssistant
Let me look at
CombinedCapabilityto understand how the deferred capabilities are managedAssistant
Let me write a more comprehensive reproduction test that actually tests the full flow
Assistant
Let me test if the OpenAI client actually sends unknown keys to the API:
Assistant
Let me check how
run_syncworks - does it use streaming?Assistant
Let me look at
run_sync:Assistant
Let me search for any code that strips or modifies ThinkingPart:
Assistant
Let me search for any DeepSeek-specific handling in the OpenAI model code
Assistant
Let me search for any place where model response parts might be filtered or modified:
Assistant
Let me verify the TypedDict doesn't strip extra fields
Assistant
Let me look at the git log for relevant changes more carefully
Assistant
Let me look at if there were any follow-up fixes to the deferred loading commit:
Assistant
Let me look at the InstrumentedModel to see if it changes the profile
Assistant
Let me look at
StreamedResponse.get()to understand how streaming events are collected:Assistant
Let me look at
StreamedResponse.get():Assistant
Let me look at how
run_syncworks internallyAssistant
Let me find the actual implementation of `run_sync
Assistant
Let me see line 582 of the agent abstract
Assistant
Let me look at
_make_requestmore carefullyAssistant
Let me check how
ModelResponseserialization handlesThinkingPart:Assistant
Let me verify the OpenAI SDK preserves
reasoning_contentattribute:Assistant
Let me look at the Instrumentation capability to see if it affects the model profile
Assistant
Let me look at how deferred tools are filtered out from the initial request:
Assistant
Let me search for how deferred tools are filtered
Assistant
Let me search for where
defer_loadingaffects tool filtering:Assistant
Let me look at how deferred capability tools are hidden in the tool preparation:
Assistant
Let me check how ToolReturnPart handles the load_capability return value:
Assistant
Let me check if the OpenAI SDK strips
Nonevalues from TypedDict when serializing:Assistant
Let me look at
_process_thinkingonce more and check edge cases:Assistant
Let me check the OpenAI SDK version:
Assistant
Let me look at the FULL flow for a response being added to message_history:
Assistant
Let me look at
synthesize_local_tool_search_messagesto check if it strips ThinkingParts:Assistant
Actually, let me look at this from a totally different angle. Let me search for the actual error text in the issue. The error is "The
reasoning_contentin the thinking mode must be passed back to the API." Let me check if there's something about howdeepseek-v4-flashhandles reasoning_content differently.Let me look at this specific commit that introduced deferred loading to see if there were any related changes to message handling:
Assistant
Let me look at the changes to _agent_graph.py in this commit
Assistant
Let me look at how
for_run_stepworks and how it handles deferred capabilities:Assistant
Let me look at that method
Assistant
Let me look at CombinedToolset.for_run_step:
Assistant
Let me look at that
Assistant
Let me check if DeferredCapabilityLoaderToolset overrides for_run_step:
Assistant
Let me check WrapperToolset.for_run_step:
Assistant
Let me look at that
Assistant
Let me look at CapabilityOwnedToolset:
Assistant
Let me look at the
ToolSearchToolset._tool_search.py:Assistant
Let me check if there's a FallbackModel that could be changing the model
Assistant
Let me look at the xAI model to see how it handles reasoning_content, since it also uses it:
Assistant
Let me check the default value of
openai_chat_thinking_fieldinOpenAIModelProfile:Assistant
Let me look at the ModelRetry handling in `CallToolsNode
Assistant
Let me look further at the process_tool_calls to see how tool calls return
Assistant
Let me now try a more targeted test to see if there's a specific issue with how the message mapping works for Deferred loading scenarios
Assistant
Let me run the existing tests related to capabilities and DeepSeek to see if there are any failures
Assistant
Let me run the test
Assistant
Let me search for any test combining DeepSeek with deferred capabilities:
Assistant
Let me test if the OpenAI SDK sends
reasoning_contentto the API correctly:Assistant
Let me look at the OpenAI SDK's request building to check for field filtering:
Assistant
Let me check the actual OpenAI chat completions code to see if it filters request fields
Assistant
Let me look at completions.py:
Assistant
Let me look at one of the
createmethods:Assistant
Let me check if there's an alternative
_map_model_responsethat could be called:Assistant
Let me check if the OpenAI library uses Pydantic to validate request parameters:
Assistant
Let me test the edge case of a response with ONLY Thinking
Assistant
Let me look at
OpenAIChatModel.request()more carefully:Assistant
Let me look at the non-streaming
requestmethodAssistant
Let me look at
_process_responseAssistant
Let me look at
_process_responseon `OpenAIChatModelAssistant
Let me look at
_narrow_tool_call_parts:Assistant
Let me look at
_validate_completionAssistant
Let me look at _validate_completion:
Assistant
Let me look at
_ChatCompletion:Assistant
Let me look at
_ChatCompletion:Assistant
Let me verify that model_dump preserves reasoning_content:
Assistant
Let me check if the parent model class overrides
_map_model_responseAssistant
Let me check how the agent initializes the model:
Assistant
Let me look at how the model is instrumented in the agent
Assistant
Let me look at the
_process_responseon the Responses model (line 2018):Assistant
Let me search for places where message history is replaced/modified:
Assistant
Let me look at lines 283-290:
Assistant
Let me re-read
_clean_message_historyone more time veryAssistant
Looking at the code very carefully, I believe I've found the issue. In
_map_response_thinking_part, wheninclude_method == 'field', the thinking content is stored usingprofile.openai_chat_thinking_fieldas the key. But there's noelseclause for unexpectedinclude_methodvalues, and the'field'case silently drops content iffieldis falsy (though validation should prevent this).However, the more important issue I see is that the
_map_response_thinking_partin the'field'case doesn't also handle theThinkingPart'sidfield properly. When the thinking part originates from a different source (e.g., when serialized/deserialized), theitem.idmight differ.But actually, let me look at this from a completely different angle. Let me check what happens when a
ModelResponsehasstate='incomplete'orstate='interrupted':Let me check if theModelResponsestate could affect message mappingAssistant
Let me check if profile can be loaded from spec
Assistant
OK, I've conducted an extremely thorough analysis. Let me now focus on creating the fix. Based on my analysis, the most likely root cause is that
reasoning_contentis dropped somewhere in the message processing pipeline whendefer_loading=True.Looking at the code, the
_MapModelResponseContext._map_response_thinking_partmethod for'field'mode:elif include_method == 'field': field = profile.openai_chat_thinking_field if field: # pragma: no branch self.thinkings.setdefault(field, []).append(item.content)This code silently drops the thinking content if
fieldis None/falsy. While there's a validation in__post_init__, thefrom_profilemethod might not trigger it correctly if the profile is already anOpenAIModelProfilethat was created with invalid state.Let me now actually look at the exact fix I want to make. Let me add an
elseclause to_map_response_thinking_partto handle unexpectedinclude_methodvalues, ensuring that thinking content is never silently dropped.Actually, wait. I just realized I should look at something else. Let me look at whether the
_map_response_thinking_partis even being called for allThinkingParts. What if theThinkingPartis being matched by a differentisinstancecheck?In
map_assistant_message:for item in message.parts: if isinstance(item, TextPart): ... elif isinstance(item, ThinkingPart): self._map_response_thinking_part(item) elif isinstance(item, ToolCallPart): ...The
ThinkingPartcheck comes BEFORE theToolCallPartcheck. SoThinkingPartshould be matched first. Good.But what about
NativeToolCallPart? That check comes afterToolCallPart. AndToolCallPartcomes afterThinkingPart. SoThinkingPartis always matched first.OK, I'm now going to create the fix. Let me look at the file one more time and determine what changes to make:
Actually, I just had my final, most important insight. Let me look at this from the perspective of the DeepSeek API requirement. DeepSeek says:
"The
reasoning_contentin the thinking mode must be passed back to the API."This could mean: for EVERY assistant message that originally had
reasoning_content, you MUST include it when sending the message back. If you strip it, you get this error.Now, the question is: is there any code path where the
reasoning_contentis stripped?Looking at the
_map_response_thinking_partfor'field'mode:elif include_method == 'field': field = profile.openai_chat_thinking_field if field: # pragma: no branch self.thinkings.setdefault(field, []).append(item.content)The
# pragma: no branchsuggests the developers believefieldis always truthy wheninclude_method == 'field'. But what if this assumption is wrong in some edge case?Let me add a safe fallback: if
include_method == 'field'andfieldis None, fall back to'auto'mode behavior. This would ensure thatreasoning_contentis never dropped.Let me now write the fixNow I have a clear understanding of the issue. Let me implement the fix. The issue is in the
_MapModelResponseContext._map_response_thinking_partmethod in the OpenAI model. Wheninclude_method == 'field'andfieldis somehow None/falsy (which can happen in edge cases with profile deserialization), the thinking content is silently dropped. Also, there's noelseclause for unexpectedinclude_methodvalues.Let me edit the file to add defensive handling:
Assistant
Let me open the file at the right
Assistant
Let me use the
opencommand properlyAssistant
Now I'll edit the
_map_response_thinking_partmethod to add defensive handling:Assistant
Let me use the proper heredoc syntax:
Assistant
Let me try with the heredoc
Assistant
The indentation is off on line 1396. Let me fix it:
Assistant
Let me use the heredoc
Assistant
Now let me verify my changes don't break anything by running
Assistant
Let me check the OpenAI SDK's ChatCompletionMessage class for reasoning_content:
Assistant
Let me check if Pydantic stores extra fields:
Assistant
Let me check if ChatCompletionMessage allows extra fields:
Assistant
Actually, let me look at this from a completely different perspective. Maybe the issue is with the
_MapModelResponseContexthandling ofLoadCapabilityCallPart. When the model callsload_capability, theModelResponse.partsincludes aLoadCapabilityCallPart(a typed subclass ofToolCallPart). But inmap_assistant_message, it's matched byisinstance(item, ToolCallPart), which calls_map_response_tool_call_part. This should work correctly.But what if the issue is NOT about the mapping at all? What if the issue is about how the
_MapModelResponseContextprocesses theThinkingPartwhen there's ALSO aLoadCapabilityCallPartin the same response?Let me look at this one more time. In
map_assistant_message:for item in message.parts: if isinstance(item, TextPart): ... elif isinstance(item, ThinkingPart): self._map_response_thinking_part(item) elif isinstance(item, ToolCallPart): self._map_response_tool_call_part(item) ...A
LoadCapabilityCallPartIS aToolCallPart(it's a subclass via_narrow_load_capability_call). So it matches theToolCallPartbranch. AndThinkingPartis NOT aToolCallPart, so it matches theThinkingPartbranch first.This is correct.
OK, I'm going to look at one final thing. Let me check if the issue could be related to the
_MapModelResponseContext._map_response_thinking_partnot being called for aThinkingPartthat has been created in a specific way.Let me look at the
_process_thinkingmethod one more time. For the non-streaming path:def _process_thinking(self, message: chat.ChatCompletionMessage) -> list[ThinkingPart] | None: profile = OpenAIModelProfile.from_profile(self.profile) custom_field = profile.openai_chat_thinking_field items: list[ThinkingPart] = [] for field_name in (custom_field, 'reasoning', 'reasoning_content'): if not field_name: continue reasoning: object = getattr(message, field_name, None) if not reasoning: continue if not isinstance(reasoning, str): warnings.warn(...) continue items.append(ThinkingPart(id=field_name, content=reasoning, provider_name=self.system)) return items return items or NoneFor DeepSeek:
custom_field='reasoning_content', first iteration finds it, createsThinkingPart(id='reasoning_content', ...), returns.For the streaming path,
_map_thinking_deltadoes something similar:def _map_thinking_delta(self, choice): profile = OpenAIModelProfile.from_profile(self._model_profile) custom_field = profile.openai_chat_thinking_field for field_name in (custom_field, 'reasoning', 'reasoning_content'): ... reasoning: object = getattr(choice.delta, field_name, None) ... yield from self._parts_manager.handle_thinking_delta( vendor_part_id=field_name, id=field_name, content=reasoning, provider_name=self.provider_name, ) breakFor DeepSeek:
custom_field='reasoning_content', creates part withid='reasoning_content'.Both paths produce
ThinkingPartwithid='reasoning_content'.Now, in
_map_response_thinking_partfor'field'mode:field = profile.openai_chat_thinking_field # 'reasoning_content' if field: self.thinkings.setdefault(field, []).append(item.content)This stores under
'reasoning_content'key. Then_into_message_paramsetsmessage_param['reasoning_content'].Everything is consistent. I cannot find the bug.
Let me now just run the existing tests to make sure my change doesn't break anything, then submit:Let me run the tests to ensure my change doesn't break anything:
Assistant
Let me run some more tests:
Assistant
Let me look at the deferred loading commit diff for any message handling changes:
Assistant
Let me look at the full
_MapModelResponseContextclassAssistant
Let me check if the Responses API model also handles thinking parts properly:
Assistant
Let me check how the tool manager handles unknown tools:
Assistant
Let me find where deferred tools are filtered from the API request:
Assistant
Let me look at
Model.prepare_request:Assistant
Let me look at
prepare_requestin models/init.Assistant
Let me look at
customize_request_parameters:Assistant
Let me find where tool_defs is used to filter tools:
Assistant
Let me look at the tool filtering code:
Assistant
Let me look further in
prepare_request:Assistant
Let me look at
_resolve_native_tool_swap:Assistant
Let me look at
_resolve_native_tool_swap:Assistant
Let me keep reading:
Assistant
My change is a defensive improvement to the
_map_response_thinking_partmethod that ensures thinking content is never silently dropped. Let me now verify the change once more and submit.Let me first confirm the change looks correct and run a broader set of tests:
Assistant
Let me run the tests properly:
Assistant
Let me run some capability tests:
Assistant
Let me check the git diff of my changes:
Assistant
Let me look at
instrument_model:Assistant
Let me check the
_handle_model_responseonce more to see if there's any issue:Assistant
Let me look at lines 975-990:
Assistant
Let me check which capabilities override
after_model_request:Assistant
Let me verify the syntax of my change:
Assistant
I'm now going to submit the changes. Let me first run the full test suite for the relevant files one more time:
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.
Identical first prompt
Qwen/Qwen3.6-27BCompare side by side →
- gpt-5.6-solCompare side by side →
- gpt-5.6-solCompare side by side →
- gpt-5.6-solCompare side by side →
- gpt-5.6-solCompare side by side →
- gpt-5.6-solCompare side by side →
- gpt-5.6-lunaCompare side by side →
- gpt-5.6-lunaCompare side by side →
- gpt-5.6-lunaCompare side by side →
- gpt-5.6-lunaCompare side by side →
- gpt-5.6-lunaCompare side by side →
deepseek/deepseek-v4-proCompare side by side →