toolcontext

Chapter 10: ToolContext

In the previous chapter, we learned about InvocationContext, the object encapsulating all necessary information for a single agent turn. While components like callbacks receive a CallbackContext that wraps InvocationContext and provides delta-aware state access, Tools (BaseTool) require slightly more specific information during their execution. This chapter introduces ToolContext, the specialized context object passed directly to a tool's run_async method.

Motivation and Use Case

When an LLM decides to invoke a Tool (BaseTool), the framework needs to execute the tool's specific logic. This logic often requires:

1. Access to the general turn context (session, services, etc.) provided by InvocationContext.
2. Access to the session's State, both for reading existing information and for recording changes made by the tool.
3. A unique identifier linking this specific tool execution back to the LLM's function call request, especially if multiple tools might be called in parallel.
4. A mechanism for the tool to signal outcomes or requirements back to the framework, such as state updates, artifact creation/updates, or the need for user authorization.

ToolContext fulfills these needs. It inherits from CallbackContext, giving it access to the delta-aware state and services. Crucially, it adds the function_call_id specific to the tool invocation and directly exposes the actions object (EventActions) for the tool to modify.

Central Use Case: A user asks an agent equipped with a get_weather tool: "What's the weather like in London?". The agent's BaseLlmFlow receives a FunctionCall from the LLM.

1. The flow creates a ToolContext instance, passing the current InvocationContext and the id from the FunctionCall.
2. The flow calls get_weather_tool.run_async(args={'location': 'London'}, tool_context=ctx).
3. Inside run_async, the tool uses ctx.function_call_id for logging or associating results.
4. It might read user preferences from state: units = ctx.state.get(State.USER_PREFIX + 'weather_units', 'celsius').
5. After fetching the weather (e.g., 15 degrees Celsius), it uses ctx.actions.state_delta to store the result: ctx.state['last_weather_query'] = {'location': 'London', 'temp': 15, 'units': 'celsius'}. (Remember, ctx.state writes to the delta in ctx.actions).
6. The tool returns its primary result (e.g., the dictionary {'location': 'London', 'temp': 15, 'units': 'celsius'}).
7. The flow uses the function_call_id from the context to correctly format the FunctionResponse and includes the state_delta captured in ctx.actions within the resulting Event.