feat(sdk): add optional id parameter to copilotkit_emit_tool_call (CopilotKit#4923)

## Summary
- Adds an optional `tool_call_id` / `toolCallId` parameter to
`copilotkit_emit_tool_call` across all three SDK variants (Python
LangGraph, Python CrewAI, JS/TS)
- When provided, the custom ID is used as the `toolCallId` in AG-UI
protocol events; when omitted, a random UUID is generated (backwards
compatible)
- All variants now return the tool call ID (`str` / `Promise<string>`)
instead of `True` / `void`, aligning the LangGraph Python and JS
variants with CrewAI which already returned it
- Introduces `CopilotKitError` base exception class and
`CopilotKitMisuseError` for invalid API usage in the Python SDK
- Adds compensating `TOOL_CALL_END` / `action_execution_end` dispatch
when mid-stream failures occur, preventing stuck client UIs
- Exports all exception types from the `copilotkit` package root

## Motivation
Customer request — enables use cases including:
- **Correlation across agent steps** — emit a tool call with a known ID
and reference it later
- **Idempotency / replay safety** — deterministic IDs prevent duplicate
tool calls on LangGraph checkpoint replays
- **External system linking** — use a job ID, trace span ID, or request
correlation ID as the tool call ID
- **Custom HITL flows** — programmatically approve/reject a specific
tool call by predictable ID
- **Testing** — deterministic IDs make snapshot/integration tests stable

## Behavioral changes
- **JS dispatch errors are no longer wrapped in
`CopilotKitMisuseError`**: Previously, `copilotkitEmitToolCall` wrapped
any `dispatchCustomEvent` failure in a `CopilotKitMisuseError`.
Transport/dispatch errors now propagate as their native error types.
This is more correct — a dispatch failure is not a misuse error — but
callers that specifically caught `CopilotKitMisuseError` for transport
errors will need to update their catch clauses.
- **Python return type changed**: `copilotkit_emit_tool_call` previously
returned `True` (documented as `Awaitable[bool]`). It now returns `str`
(the tool call ID). Code using truthiness checks (`if result:`) is
unaffected; strict equality (`== True`) will break.

## Test plan
- [x] 4 unit tests for LangGraph Python variant (default UUID, custom
ID, return value, explicit None)
- [x] 3 unit tests for CrewAI Python variant (skipped when crewai not
installed)
- [x] 3 integration tests for AG-UI dispatch (custom ID propagates to
all TOOL_CALL events)
- [x] All 26 existing `test_agui_agent.py` tests pass (no regressions)
- [x] JS SDK builds cleanly (`nx run @copilotkit/sdk-js:build`)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: mxmzb

packages/sdk-js/src/langgraph/__tests__/utils.test.ts

@@ -1,9 +1,16 @@
+import { vi } from "vitest";
+import { dispatchCustomEvent } from "@langchain/core/callbacks/dispatch";
 import {
   copilotkitCustomizeConfig,
+  copilotkitEmitToolCall,
   convertActionsToDynamicStructuredTools,
   convertActionToDynamicStructuredTool,
 } from "../utils";
 
+vi.mock("@langchain/core/callbacks/dispatch", () => ({
+  dispatchCustomEvent: vi.fn().mockResolvedValue(undefined),
+}));
+
 describe("copilotkitCustomizeConfig", () => {
   it("returns config unchanged when no options provided", () => {
     const baseConfig = { metadata: { existing: true } };
@@ -252,3 +259,105 @@ describe("convertActionsToDynamicStructuredTools", () => {
     );
   });
 });
+
+describe("copilotkitEmitToolCall", () => {
+  const mockConfig = { metadata: {} } as any;
+  const mockedDispatch = vi.mocked(dispatchCustomEvent);
+
+  beforeEach(() => {
+    mockedDispatch.mockClear();
+  });
+
+  it("returns a generated id when no id is provided", async () => {
+    const result = await copilotkitEmitToolCall(mockConfig, "SearchTool", {
+      steps: 10,
+    });
+
+    expect(typeof result).toBe("string");
+    expect(result.length).toBeGreaterThan(0);
+    expect(mockedDispatch).toHaveBeenCalledWith(
+      "copilotkit_manually_emit_tool_call",
+      { name: "SearchTool", args: { steps: 10 }, id: result },
+      mockConfig,
+    );
+  });
+
+  it("uses caller-provided toolCallId verbatim", async () => {
+    const result = await copilotkitEmitToolCall(
+      mockConfig,
+      "SearchTool",
+      { steps: 10 },
+      { toolCallId: "custom-abc" },
+    );
+
+    expect(result).toBe("custom-abc");
+    expect(mockedDispatch).toHaveBeenCalledWith(
+      "copilotkit_manually_emit_tool_call",
+      { name: "SearchTool", args: { steps: 10 }, id: "custom-abc" },
+      mockConfig,
+    );
+  });
+
+  it("treats undefined options the same as omitted", async () => {
+    const result = await copilotkitEmitToolCall(
+      mockConfig,
+      "SearchTool",
+      {},
+      undefined,
+    );
+
+    expect(typeof result).toBe("string");
+    expect(result.length).toBeGreaterThan(0);
+    expect(mockedDispatch).toHaveBeenCalledWith(
+      "copilotkit_manually_emit_tool_call",
+      { name: "SearchTool", args: {}, id: result },
+      mockConfig,
+    );
+  });
+
+  it("throws on empty string toolCallId", async () => {
+    await expect(
+      copilotkitEmitToolCall(mockConfig, "SearchTool", {}, { toolCallId: "" }),
+    ).rejects.toThrow("non-empty string");
+  });
+
+  it("throws on whitespace-only toolCallId", async () => {
+    await expect(
+      copilotkitEmitToolCall(
+        mockConfig,
+        "SearchTool",
+        {},
+        { toolCallId: "   " },
+      ),
+    ).rejects.toThrow("non-empty string");
+  });
+
+  it("throws on whitespace-only name", async () => {
+    await expect(copilotkitEmitToolCall(mockConfig, "   ", {})).rejects.toThrow(
+      "non-empty string",
+    );
+  });
+
+  it("throws on undefined args", async () => {
+    await expect(
+      copilotkitEmitToolCall(mockConfig, "SearchTool", undefined),
+    ).rejects.toThrow("required");
+  });
+
+  it("throws on non-JSON-serializable args", async () => {
+    const circular: any = {};
+    circular.self = circular;
+    await expect(
+      copilotkitEmitToolCall(mockConfig, "SearchTool", circular),
+    ).rejects.toThrow("not JSON-serializable");
+  });
+
+  it("propagates dispatch errors with tool-call context", async () => {
+    mockedDispatch.mockRejectedValueOnce(new Error("transport closed"));
+    await expect(
+      copilotkitEmitToolCall(mockConfig, "SearchTool", {}),
+    ).rejects.toThrow(
+      /copilotkitEmitToolCall dispatch failed.*SearchTool.*transport closed/,
+    );
+  });
+});

packages/sdk-js/src/langgraph/utils.ts

@@ -1,14 +1,15 @@
-import { RunnableConfig } from "@langchain/core/runnables";
+import type { RunnableConfig } from "@langchain/core/runnables";
 import { dispatchCustomEvent } from "@langchain/core/callbacks/dispatch";
 import {
   convertJsonSchemaToZodSchema,
   randomId,
+  randomUUID,
   CopilotKitMisuseError,
 } from "@copilotkit/shared";
 import { interrupt } from "@langchain/langgraph";
 import { DynamicStructuredTool } from "@langchain/core/tools";
 import { AIMessage } from "@langchain/core/messages";
-import { OptionsConfig } from "./types";
+import type { OptionsConfig } from "./types";
 
 /**
  * Customize the LangGraph configuration for use in CopilotKit.
@@ -301,8 +302,14 @@ export async function copilotkitEmitMessage(
  * ```typescript
  * import { copilotkitEmitToolCall } from "@copilotkit/sdk-js";
  *
- * await copilotkitEmitToolCall(config, name="SearchTool", args={"steps": 10})
+ * const autoId = await copilotkitEmitToolCall(config, "SearchTool", { steps: 10 });
+ *
+ * // With a custom ID for correlation/idempotency:
+ * const customId = await copilotkitEmitToolCall(config, "SearchTool", { steps: 10 }, { toolCallId: "my-custom-id" });
  * ```
+ *
+ * @returns The tool call ID used for the emitted call — equals `options.toolCallId`
+ *          when provided, otherwise a randomly generated ID.
  */
 export async function copilotkitEmitToolCall(
   /**
@@ -317,37 +324,73 @@ export async function copilotkitEmitToolCall(
    * The arguments to emit.
    */
   args: any,
-) {
+  /**
+   * Options for the tool call emission.
+   */
+  options?: {
+    /**
+     * Optional tool call ID. If not provided, a random ID is generated.
+     * When provided, this ID is used as the toolCallId and parentMessageId
+     * in AG-UI protocol events. The caller is responsible for ensuring uniqueness.
+     */
+    toolCallId?: string;
+  },
+): Promise<string> {
   if (!config) {
     throw new CopilotKitMisuseError({
       message: "LangGraph configuration is required for copilotkitEmitToolCall",
     });
   }
 
-  if (!name || typeof name !== "string") {
+  if (typeof name !== "string" || name.trim().length === 0) {
     throw new CopilotKitMisuseError({
       message:
         "Tool name must be a non-empty string for copilotkitEmitToolCall",
     });
   }
 
+  if (
+    options?.toolCallId !== undefined &&
+    (typeof options.toolCallId !== "string" ||
+      options.toolCallId.trim().length === 0)
+  ) {
+    throw new CopilotKitMisuseError({
+      message:
+        "Tool call id must be a non-empty string when provided for copilotkitEmitToolCall",
+    });
+  }
+
   if (args === undefined) {
     throw new CopilotKitMisuseError({
       message: "Tool arguments are required for copilotkitEmitToolCall",
     });
   }
 
+  try {
+    JSON.stringify(args);
+  } catch (error) {
+    throw new CopilotKitMisuseError({
+      message: `Tool arguments for '${name}' are not JSON-serializable: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+
+  const toolCallId = options?.toolCallId ?? randomUUID();
+
   try {
     await dispatchCustomEvent(
       "copilotkit_manually_emit_tool_call",
-      { name, args, id: randomId() },
+      { name, args, id: toolCallId },
       config,
     );
   } catch (error) {
-    throw new CopilotKitMisuseError({
-      message: `Failed to emit tool call '${name}': ${error instanceof Error ? error.message : String(error)}`,
-    });
+    const wrapped = new Error(
+      `copilotkitEmitToolCall dispatch failed for tool="${name}" id="${toolCallId}": ${error instanceof Error ? error.message : String(error)}`,
+    );
+    (wrapped as any).cause = error;
+    throw wrapped;
   }
+
+  return toolCallId;
 }
 
 export function convertActionToDynamicStructuredTool(

sdk-python/copilotkit/__init__.py

@@ -7,6 +7,14 @@
     CopilotKitSDKContext,
 )
 from .action import Action
+from .exc import (
+    CopilotKitError,
+    CopilotKitMisuseError,
+    ActionNotFoundException,
+    AgentNotFoundException,
+    ActionExecutionException,
+    AgentExecutionException,
+)
 from .langgraph import CopilotKitState
 from .parameter import Parameter
 from .agent import Agent
@@ -32,6 +40,12 @@
     "Agent",
     "CopilotKitContext",
     "CopilotKitSDKContext",
+    "CopilotKitError",
+    "CopilotKitMisuseError",
+    "ActionNotFoundException",
+    "AgentNotFoundException",
+    "ActionExecutionException",
+    "AgentExecutionException",
     "CrewAIAgent",  # pyright: ignore[reportUnsupportedDunderAll] pylint: disable=undefined-all-variable
     "LangGraphAGUIAgent",
     "CopilotKitMiddleware",

sdk-python/copilotkit/crewai/crewai_sdk.py

@@ -5,7 +5,8 @@
 import uuid
 import json
 import asyncio
-from typing_extensions import Any, Dict, List, Literal
+from typing_extensions import Any, Dict, List, Literal, Optional
+from copilotkit.exc import CopilotKitMisuseError
 from pydantic import BaseModel, Field
 from litellm.types.utils import (
     ModelResponse,
@@ -226,14 +227,19 @@ async def copilotkit_emit_message(message: str) -> str:
     return message_id
 
 
-async def copilotkit_emit_tool_call(*, name: str, args: Dict[str, Any]) -> str:
+async def copilotkit_emit_tool_call(
+    *, name: str, args: Dict[str, Any], tool_call_id: Optional[str] = None
+) -> str:
     """
     Manually emits a tool call to CopilotKit.
 
     ```python
     from copilotkit.crewai import copilotkit_emit_tool_call
 
-    await copilotkit_emit_tool_call(name="SearchTool", args={"steps": 10})
+    auto_id = await copilotkit_emit_tool_call(name="SearchTool", args={"steps": 10})
+
+    # With a custom ID for correlation/idempotency:
+    custom_id = await copilotkit_emit_tool_call(name="SearchTool", args={"steps": 10}, tool_call_id="my-custom-id")
     ```
 
     Parameters
@@ -242,22 +248,57 @@ async def copilotkit_emit_tool_call(*, name: str, args: Dict[str, Any]) -> str:
         The name of the tool to emit.
     args : Dict[str, Any]
         The arguments to emit.
+    tool_call_id : Optional[str]
+        Optional tool call ID. If not provided, a random UUID is generated.
+        When provided, this ID is used as both the toolCallId and
+        parentMessageId in AG-UI protocol events.
+        The caller is responsible for ensuring uniqueness.
 
     Returns
     -------
-    Awaitable[bool]
-        Always return True.
+    str
+        The tool call ID used for the emitted tool call.
     """
-    message_id = str(uuid.uuid4())
-    await queue_put(
-        action_execution_start(
-            action_execution_id=message_id,
-            action_name=name,
-            parent_message_id=message_id,
-        ),
-        action_execution_args(action_execution_id=message_id, args=json.dumps(args)),
-        action_execution_end(action_execution_id=message_id),
-    )
+    if not isinstance(name, str) or not name.strip():
+        raise CopilotKitMisuseError(
+            "Tool name must be a non-empty string for copilotkit_emit_tool_call"
+        )
+
+    if tool_call_id is not None:
+        if not isinstance(tool_call_id, str) or not tool_call_id.strip():
+            raise CopilotKitMisuseError(
+                "Tool call id must be a non-empty string when provided for copilotkit_emit_tool_call"
+            )
+    try:
+        args_json = json.dumps(args)
+    except (TypeError, ValueError) as e:
+        raise CopilotKitMisuseError(
+            f"Tool arguments for '{name}' are not JSON-serializable: {e}"
+        ) from e
+
+    message_id = tool_call_id if tool_call_id is not None else str(uuid.uuid4())
+    try:
+        await queue_put(
+            action_execution_start(
+                action_execution_id=message_id,
+                action_name=name,
+                parent_message_id=message_id,
+            ),
+            action_execution_args(action_execution_id=message_id, args=args_json),
+            action_execution_end(action_execution_id=message_id),
+        )
+    except Exception:
+        try:
+            await queue_put(
+                action_execution_end(action_execution_id=message_id),
+            )
+        except Exception:
+            logger.error(
+                "Failed to emit compensating action_execution_end for %s",
+                message_id,
+                exc_info=True,
+            )
+        raise
 
     return message_id