Force Agent tool use on first request

[maxvdv94]

Description

When assigning tools there's no method or parameter to add that forces the model to use the tool. You either have to instruct it through a system_prompt or assume it makes the decision itself to use the tool.

The OpenAI SDK has a tool_choice parameter that can be found here.

Can you add this or a similar functionality that forces the model to use a specified tool on the first API request?

Example of the tool_choice parameter:

response = client.responses.create(
      model=model,
      tools=[{"type": "web_search_preview"}],
      input=search_query,
      tool_choice="required",
  )

References

https://platform.openai.com/docs/api-reference/responses/create#responses/object-tool_choice

[Whadup]

agent = Agent(
    ....
        model_settings=OpenAIModelSettings(
            temperature=chat_context.request.temperature,
            top_p=chat_context.request.top_p,
            extra_body={"tool_choice": "required},
        )
)

[jeroenvandermerwe]

It would be great if a tool_choice parameter could be set directly when running the agent (e.g., via agent.run).

Pairing this with the tools' prepare method (or the new prepare_tools method) could enable even more fine-grained and deterministic agent execution, allowing you to dynamically select or require specific tools at runtime based on the request context.

This would be a very useful addition for anyone needing strict control over tool invocation behavior!

[DouweM]

Do we just want to specify this for the first request to the LLM, or do we want a way to dynamically modify the tool_choice for every request to the LLM, through some kind of hook function that takes RunContext (similar to prepare_tools)?

One factor that complicates this slightly is that PydanticAI uses special output tools for structured output (until we get #1628 to use format=json_schema on models that support it), and uses tool_choice=required to indicate whether the model has to respond using one of the output tools, or tool_choice=auto if it's allowed to respond with plain text as well (e.g. output_type=str | SomeModel).

If we let tool_choice be set to explicitly at a per-LLM-call level (rather than through the agent model_settings property which is convoluted enough that you'll realize you're now overriding default PydanticAI behavior), we'd have to think about how to handle output tools. It may make sense to not register them with the model at all, so the model doesn't accidentally go straight for an output instead of using one of the user-provided tools.

As different APIs use different values (e.g. "required" or "any" to mean the same thing), it could be called require_tool_call, taking either a boolean or a list of possible tool names / references to already-registered tool functions.

[DouweM]

I imagine a hook similar to prepare_tools that can be set on the Agent, for example prepare_request or just prepare, that is passed the ModelRequestParameters, and would allow you to set an attribute to get the "you have to use a tool, not go straight to a final response" behavior. (As function_tools are already on ModelRequestParameters, this could possibly replace prepare_tools entirely.)

If we name it require_tool_call=True, would should we do with output tools that are automatically registered based on the specified output_type? Should they be removed so that the model has to use a user-specified tool, or would that be unexpected because the attribute name doesn't actually specify that distinction?

Perhaps if we name it something like allow_output=False, that'd imply that it has to call a user-provided tool because both str or output tools are output. But that wouldn't let us specify a specific tool or tools to be called, so if we have another attribute for that, you'd end up with 2 that could have conflicting values and we'd have to do a runtime error.

Perhaps require_tool_call taking a bool or tool function (name) or list of tool functions (names) would be sufficient, if we document clearly that this relates to user-provided tools and not output tools.

[simone-gaiarin]

First, could you clarify what you mean by "first request"? Are you referring to the very first call to run, or to the first internal request the agent makes when run is invoked?

My suggestion is to support dynamically changing tool_choice on every call to run. As I mentioned in #1777, when an agent is instantiated with multiple tools, we may want to invoke run multiple times and specify different tools for each call, thus re-using the agent.

Looking at the OpenAI API’s tool_choice parameter (docs), it supports three modes:

• auto - automatic tool selection
• required - requires the agent to pick a tool
• Forced Function - a JSON object specifying exactly which tool to call

Because of this flexibility, I don’t recommend introducing a simple boolean like require_tool_call, since it would limit the ability to specify exactly which tool to invoke. Instead, we should allow passing the full tool_choice value dynamically, similar to how LiteLLM enables specifying the precise tool to call, closely mirroring the OpenAI API behavior.

[DouweM]

First, could you clarify what you mean by "first request"? Are you referring to the very first call to run, or to the first internal request the agent makes when run is invoked?

@simone-gaiarin I've interpreted the users requesting this to mean the latter, as a way to say e.g. "never directly answer the prompt without having done a web search first". So the model would be required to use a tool on the first request, and on later request would be allowed to answer with a final response if it so decides.

My suggestion is to support dynamically changing tool_choice on every call to run.

I agree, I'd want to implement at least a prepare(_request) hook that is passed the RunContext (including message history up to this point) and can decide to modify any request param.

Instead, we should allow passing the full tool_choice value dynamically

How would you expect this to interact with the output tools PydanticAI uses when output_type is defined? I had some notes on that in my previous comments.

[thiagosalvatore]

I have a similar situation. We are currently using Google ADK, and they support what they call before model callback. It basically let me return something pretending that the model returned with that information - in this case, I return a tool call and then my agent will call that tool.

This is dynamic, meaning that depending on how the user is interacting with our chat we can or cannot force a function to be called first.

I was initially trying to solve this by iterating over the graph, detecting the model request node and then trying to add a tool call node after that, but it seems to be very messy.

Is there a better way?

[DouweM]

@thiagosalvatore Iterating over the model's graph and driving it to a CallToolsNode with a custom ModelResponse holding the ToolCallPart is indeed currently the way to go. You say messy, I say powerful and flexible :) , but I agree hooks/callbacks would be a nice way to support this as well. Would you mind filing an issue for that?