Access matched tool name before it is executed

[algosdev]

Checked other resources

• I added a very descriptive title to this question.
• I searched the LangChain documentation with the integrated search.
• I used the GitHub search to find a similar question and didn't find it.

Commit to Help

• I commit to help with one of those options 👆

Example Code

tools = [
        StructuredTool(
            func = lambda **args: f"Booked a hotel room at {args['hotel_name']}",
            name='book_hotel_room',
            description='Book a hotel room',
            args_schema=create_model('ArgsSchema_Book_hotel_room', hotel_name=(str, Field(..., description='Name of the hotel'))),
        ),
        # other tools
]
messages = [
        SystemMessagePromptTemplate(prompt=PromptTemplate(input_variables=[], template='You are a support assistant')),
        MessagesPlaceholder(variable_name='chat_history', optional=True),
        MessagesPlaceholder(variable_name='agent_scratchpad'),
        HumanMessagePromptTemplate(prompt=PromptTemplate(input_variables=['input'], template='{input}')),
    ]
  
chat_template = ChatPromptTemplate.from_messages(
        messages=messages
    )

agent = create_openai_tools_agent(llm_chat_model, tools, chat_template)
agent_executor = AgentExecutor(agent=agent, tools=tools, memory=conversational_memory, return_intermediate_steps=True, verbose=True)

response = agent_executor.invoke({"input": "I wanna book a hotel room"})
# response = [
#     'input': 'I wanna book a hotel room',
#     'output': 'Could you please provide me with the name of the hotel where you would like to book a room?'
#     'intermediate_steps': []
#]
# In the response above, it's clear that agent found matching intent and asked for its argument - the hotel name
# I wanna access the name of tool (book_hotel_room) here

response = agent_executor.invoke({"input": "Hilton"})
# response = [
#     'input': 'Hilton',
#     'output': 'I have successfully booked a hotel room at Hilton for you'
#     'intermediate_steps': [[(ToolAgentAction(tool='book_hotel_room', tool_input={'hotel_name': 'Hilton'}, log="\nInvoking: `book_hotel_room` with `{'hotel_name': 'Hilton'}`\n\n\n", message_log=[AIMessageChunk(content='', additional_kwargs={'tool_calls': [{'index': 0, 'id': 'call_xxxxxxxxxxxxxxxxxxxxx', 'function': {'arguments': '{"hotel_name":"Hilton"}', 'name': 'book_hotel_room'}, 'type': 'function'}]}, response_metadata={'finish_reason': 'tool_calls'}, id='run-xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', tool_calls=[{'name': 'book_hotel_room', 'args': {'hotel_name': 'Hilton'}, 'id': 'call_xxxxxxxxxxx', 'type': 'tool_call'}], tool_call_chunks=[{'name': 'book_hotel_room', 'args': '{"hotel_name":"Hilton"}', 'id': 'call_xxxxxxxxxxxxxxxx', 'index': 0, 'type': 'tool_call_chunk'}])], tool_call_id='call_xxxxxxxxxxxxxxxx'), 'Booked a hotel room at Hilton')]]
#]

Description

I’ve implemented a tool-calling agent (see attached code) that processes multiple tools, each defined with a name, description, and arguments. Based on the input, the agent identifies the most suitable tool and prompts for the required arguments. Once all arguments are collected, the agent executes the tool. At that point, I can retrieve the tool’s name via intermediate_steps or the tool function.

However, I want to access the matched tool’s name immediately after it is identified, either before or during the argument collection process. From the attached code, it seems intermediate_steps only populates after the tool is invoked. Still, the agent clearly identifies the tool early on, as the argument-gathering prompts are specific to it. I’ve also explored using callbacks, but they haven’t provided the desired functionality.

Is there a way to retrieve the tool’s name as soon as it is identified, but before it is executed?

System Info

langchain==0.2.16
langchain-community==0.2.16
langchain-core==0.2.38
langchain-openai==0.1.8

python:3.12

[devaleo731]

1. Implement a Custom Callback Handler

LangChain provides a BaseCallbackHandler interface, which you can extend to capture tool-related events, such as tool selection.

from langchain.callbacks.base import BaseCallbackHandler

class ToolSelectionCallback(BaseCallbackHandler):
def init(self):
self.selected_tool = None

def on_tool_start(self, tool_name: str, tool_input: dict, **kwargs):
    """Capture the tool name when it is selected."""
    self.selected_tool = tool_name
    print(f"Tool selected: {tool_name}")

Instantiate the callback

tool_selection_callback = ToolSelectionCallback()

2. Attach the Callback to the Agent

Pass your custom callback handler to the AgentExecutor when creating the agent.

from langchain.agents import AgentExecutor

agent_executor = AgentExecutor(
agent=agent,
tools=tools,
memory=conversational_memory,
return_intermediate_steps=True,
verbose=True,
callbacks=[tool_selection_callback] # Attach the callback
)

3. Access the Tool Name

The selected_tool attribute in your callback handler will contain the name of the most recently selected tool.

response = agent_executor.invoke({"input": "I wanna book a hotel room"})

Access the tool name from the callback

print(f"Tool identified immediately: {tool_selection_callback.selected_tool}")

4. Alternative: Modify the Agent Logic

If you need deeper control, you can override the agent’s _plan or _take_next_step methods. For example:

from langchain.agents import Agent

class CustomAgent(Agent):
def _plan(self, intermediate_steps, **kwargs):
"""Custom logic to capture the tool name."""
plan = super()._plan(intermediate_steps, **kwargs)
if isinstance(plan, ToolAgentAction):
print(f"Tool identified: {plan.tool}")
return plan
Attach your custom agent instead of the standard one when creating the AgentExecutor.

Key Notes
• The on_tool_start callback triggers before the tool is executed, making it ideal for your use case.
• If modifying the agent, ensure your changes don’t interfere with LangChain’s internal execution flow.
• Ensure you’re using compatible versions of LangChain, as the API evolves quickly.

This setup gives you access to the selected tool’s name as soon as the agent identifies it, before execution or argument collection.