Method runTool

packages/core/src/core/run-handler.ts:798–909

* Programmatically execute a registered frontend tool without going through an LLM turn. * The handler runs, render components show up in the UI, and both the tool call and * result messages are added to `agent.messages`.

(
    params: CopilotKitCoreRunToolParams,
  )

   * result messages are added to `agent.messages`.
   */
  async runTool(
    params: CopilotKitCoreRunToolParams,
  ): Promise<CopilotKitCoreRunToolResult> {
    const { name, agentId, parameters = {}, followUp = false } = params;

    // 1. Look up the tool
    const tool = this.getTool({ toolName: name, agentId });
    if (!tool) {
      const error = new Error(`Tool not found: ${name}`);
      await this._internal.emitError({
        error,
        code: CopilotKitCoreErrorCode.TOOL_NOT_FOUND,
        context: { toolName: name, agentId },
      });
      throw error;
    }

    // 2. Look up the agent
    const resolvedAgentId = agentId ?? "default";
    const agent = this._internal.getAgent(resolvedAgentId);
    if (!agent) {
      const error = new Error(`Agent not found: ${resolvedAgentId}`);
      await this._internal.emitError({
        error,
        code: CopilotKitCoreErrorCode.AGENT_NOT_FOUND,
        context: { agentId: resolvedAgentId },
      });
      throw error;
    }

    // 3. Create assistant message with tool call
    const toolCallId = randomUUID();
    const assistantToolCall = {
      id: toolCallId,
      type: "function" as const,
      function: {
        name,
        arguments: JSON.stringify(parameters),
      },
    };
    const assistantMessage: Message = {
      id: randomUUID(),
      role: "assistant",
      content: "",
      toolCalls: [assistantToolCall],
    };

    // 4. Push assistant message into agent's messages
    agent.messages.push(assistantMessage);

    // 5. Execute the tool handler (if it has one)
    let handlerResult: ExecuteToolHandlerResult = {
      result: "",
      error: undefined,
      isArgumentError: false,
    };

    if (tool.handler) {