Method runAgent

packages/core/src/core/run-handler.ts:302–405

* Run an agent

({
    agent,
    forwardedProps,
    resume,
  }: CopilotKitCoreRunAgentParams)

   * Run an agent
   */
  async runAgent({
    agent,
    forwardedProps,
    resume,
  }: CopilotKitCoreRunAgentParams): Promise<RunAgentResult> {
    // Agent ID is guaranteed to be set by validateAndAssignAgentId
    if (agent.agentId) {
      void this._internal.suggestionEngine.clearSuggestions(agent.agentId);
    }

    // Re-apply core headers (merged on top of the agent's own headers) so a
    // late header update is picked up without clobbering per-agent headers.
    this._internal.applyHeadersToAgent(agent);

    // Detach any active run (e.g. a long-lived connectAgent pipeline) before
    // starting a new run.  We await the detach to ensure the previous pipeline
    // has fully finalized — its activeRunCompletionPromise resolves once the
    // observable finalize block runs, which happens synchronously after the
    // takeUntil signal completes the chain.  This prevents a race where the new
    // runAgent() overwrites activeRunDetach$ / activeRunCompletionPromise before
    // the old pipeline can clean up, causing dropped runs.
    //
    // Historical note: an earlier version used fire-and-forget (`void`) here
    // because awaiting caused a deadlock when connectAgent's
    // ConnectNotImplementedError cleanup was still in-flight.  That deadlock
    // was resolved in @ag-ui/client ≥0.0.42 where the catchError path
    // (ConnectNotImplementedError → EMPTY) always runs the finalize block,
    // so the completion promise now resolves reliably.
    if (agent.detachActiveRun) {
      await agent.detachActiveRun();
    }

    // Set up abort controller and agent.abortRun() intercept only for the
    // top-level call. Recursive follow-up calls from processAgentResult
    // reuse the same controller.
    const isTopLevel = this._runDepth === 0;
    let originalAbortRun: (() => void) | undefined;

    if (isTopLevel) {
      this._runAbortController = new AbortController();

      // Intercept agent.abortRun() so that calling it directly (not via
      // stopAgent) also aborts in-flight tool execution and prevents
      // follow-up runs.
      const controller = this._runAbortController;
      originalAbortRun = agent.abortRun.bind(agent);
      agent.abortRun = () => {
        controller.abort();
        originalAbortRun!();
      };

      // Notify subscribers (e.g. the inspector) about the agent that is about
      // to run. Per-thread clones are not in the agent registry, so
      // onAgentsChanged never fires for them and they would otherwise be
      // invisible to subscribers. Fired once per top-level run; recursive
      // follow-up runs reuse the same instance and need no re-notification.
      await this._internal.notifySubscribers(
        (subscriber) =>