Class ToolInvocation

java.lang.Object
com.github.copilot.rpc.ToolInvocation
public final class ToolInvocation extends Object
Represents a tool invocation request from the AI assistant.

When the assistant invokes a tool, this object contains the context including the session ID, tool call ID, tool name, and arguments parsed from the assistant's request.

In annotation-based tools, methods annotated with CopilotTool may declare a ToolInvocation parameter in any position (before, between, or after schema-visible parameters). It is always injected as runtime context and is never included in the tool's JSON schema.

Since:
1.0.0
See Also:

  • Constructor Details

    • ToolInvocation

      public ToolInvocation()

  • Method Details

    • getSessionId

      public String getSessionId()
      Gets the session ID where the tool was invoked.
      Returns:
      the session ID

    • setSessionId

      public ToolInvocation setSessionId(String sessionId)
      Sets the session ID.
      Parameters:
      sessionId - the session ID
      Returns:
      this invocation for method chaining

    • getToolCallId

      public String getToolCallId()
      Gets the unique identifier for this tool call.

      This ID correlates the tool invocation with its response.

      Returns:
      the tool call ID

    • setToolCallId

      public ToolInvocation setToolCallId(String toolCallId)
      Sets the tool call ID.
      Parameters:
      toolCallId - the tool call ID
      Returns:
      this invocation for method chaining

    • getToolName

      public String getToolName()
      Gets the name of the tool being invoked.
      Returns:
      the tool name

    • setToolName

      public ToolInvocation setToolName(String toolName)
      Sets the tool name.
      Parameters:
      toolName - the tool name
      Returns:
      this invocation for method chaining

    • getArguments

      public Map<String,Object> getArguments()
      Gets the arguments passed to the tool as a Map.

      The arguments are provided as a Map<String, Object> matching the parameter schema defined in the tool's ToolDefinition. Values can be accessed using standard Map operations.

      For type-safe access, use getArgumentsAs(Class) to deserialize arguments into a record or POJO.

      Returns:
      the arguments as a Map, or null if no arguments
      See Also:

    • getArgumentsAs

      public <T> T getArgumentsAs(Class<T> type)
      Deserializes the tool arguments into the specified type.

      This method provides type-safe access to tool arguments by converting the JSON arguments into a record, POJO, or other compatible type. 

      // Define a record for your tool's arguments
record WeatherArgs(String city) {
}

// In your tool handler
WeatherArgs args = invocation.getArgumentsAs(WeatherArgs.class);
String city = args.city();
      Type Parameters:
      T - the type to deserialize to
      Parameters:
      type - the class of the target type
      Returns:
      the arguments deserialized as the specified type
      Throws:
      IllegalArgumentException - if deserialization fails
      Since:
      1.0.0

    • setArguments

      public ToolInvocation setArguments(com.fasterxml.jackson.databind.JsonNode arguments)
      Sets the tool arguments.

      Note: This method is intended for internal SDK use and JSON deserialization. Users typically do not need to call this method directly.

      Parameters:
      arguments - the arguments as a JsonNode
      Returns:
      this invocation for method chaining

    • getAvailableTools

      public List<CurrentToolMetadata> getAvailableTools()
      Gets a snapshot of the session's currently initialized tools.

      The SDK populates this only when the invocation targets the built-in tool-search tool ("tool_search_tool"), so a tool-search override can rank or filter the live catalog — including MCP tools configured in settings — without issuing its own RPC. It is null for every other tool invocation.

      Returns:
      the available tools snapshot, or null if not applicable
      Since:
      1.0.7

    • setAvailableTools

      public ToolInvocation setAvailableTools(List<CurrentToolMetadata> availableTools)
      Sets the available tools snapshot.

      Note: This method is intended for internal SDK use. Users typically do not need to call this method directly.

      Parameters:
      availableTools - the available tools snapshot
      Returns:
      this invocation for method chaining

    • getAgentId

      @CopilotExperimental public String getAgentId()
      Gets the sub-agent instance that issued this call.

      Experimental. This is the agentId of the sub-agent's session events. It is null for a root-agent call, for every call when the runtime does not attribute sub-agent tool calls, and for a call that did not arrive as an external tool request.

      Returns:
      the sub-agent instance id, or null when no sub-agent is named
      Since:
      1.0.15-preview.1

    • setAgentId

      @CopilotExperimental public ToolInvocation setAgentId(String agentId)
      Sets the sub-agent instance that issued this call.

      Note: This method is intended for internal SDK use. Users typically do not need to call this method directly.

      Parameters:
      agentId - the sub-agent instance id, or null when no sub-agent is named
      Returns:
      this invocation for method chaining

    • getRequestId

      @CopilotExperimental public String getRequestId()
      Gets the runtime request id of this call.

      Experimental. This is the key session.tools.handlePendingToolCall and session.tools.listPendingRequests use. A root-agent call stays answerable after the session is resumed with pending work continued; a sub-agent's call can be answered only while that sub-agent is still running.

      Returns:
      the request id, or null if the call did not arrive as an external tool request
      Since:
      1.0.15-preview.1

    • setRequestId

      @CopilotExperimental public ToolInvocation setRequestId(String requestId)
      Sets the runtime request id of this call.

      Note: This method is intended for internal SDK use. Users typically do not need to call this method directly.

      Parameters:
      requestId - the request id
      Returns:
      this invocation for method chaining