@openai/agents-core 0.9.0 → 0.10.0

package/dist/runState.mjs

@@ -40,8 +40,11 @@ import { getSerializedApplyPatchToolPlaceholder, getSerializedComputerToolPlaceh
  *   aliasing to serialized run state payloads.
  * - 1.9: Adds optional sandbox session persistence with a versioned session-state
  *   envelope for sandbox-agent resume.
+ * - 1.10: Adds optional stable agent identity keys so duplicate-name agent graphs can
+ *   serialize and resume without ambiguous name resolution.
+ * - 1.11: Allows null maxTurns to persist runs without a turn limit.
  */
-export const CURRENT_SCHEMA_VERSION = '1.9';
+export const CURRENT_SCHEMA_VERSION = '1.11';
 const SUPPORTED_SCHEMA_VERSIONS = [
     '1.0',
     '1.1',
@@ -52,11 +55,14 @@ const SUPPORTED_SCHEMA_VERSIONS = [
     '1.6',
     '1.7',
     '1.8',
+    '1.9',
+    '1.10',
     CURRENT_SCHEMA_VERSION,
 ];
 const $schemaVersion = z.enum(SUPPORTED_SCHEMA_VERSIONS);
 const serializedAgentSchema = z.object({
     name: z.string(),
+    identity: z.string().optional(),
 });
 const serializedSpanBase = z.object({
     object: z.literal('trace.span'),
@@ -307,7 +313,7 @@ export const SerializedRunState = z.object({
         toolInput: z.any().optional(),
     }),
     toolUseTracker: z.record(z.string(), z.array(z.string())),
-    maxTurns: z.number(),
+    maxTurns: z.number().nullable(),
     currentAgentSpan: SerializedSpan.nullable().optional(),
     noActiveAgentRun: z.boolean(),
     inputGuardrailResults: z.array(inputGuardrailResultSchema),
@@ -470,10 +476,10 @@ export class RunState {
      */
     _trace = null;
     /**
-     * Runtime-only tool_search-loaded tools, scoped by agent name and preserved across turns for
+     * Runtime-only tool_search-loaded tools, scoped by agent object and preserved across turns for
      * the lifetime of this in-memory run.
      */
-    _toolSearchRuntimeToolsByAgentName = new Map();
+    _toolSearchRuntimeToolsByAgent = new Map();
     /**
      * Persisted sandbox session metadata for sandbox-agent resume.
      */
@@ -517,20 +523,20 @@ export class RunState {
     setCurrentAgentSpan(span) {
         this._currentAgentSpan = span;
     }
-    getOrCreateToolSearchRuntimeToolState(agentName) {
-        let state = this._toolSearchRuntimeToolsByAgentName.get(agentName);
+    getOrCreateToolSearchRuntimeToolState(agent) {
+        let state = this._toolSearchRuntimeToolsByAgent.get(agent);
         if (!state) {
             state = {
                 anonymousEntries: [],
                 keyedEntries: new Map(),
                 nextOrder: 0,
             };
-            this._toolSearchRuntimeToolsByAgentName.set(agentName, state);
+            this._toolSearchRuntimeToolsByAgent.set(agent, state);
         }
         return state;
     }
     recordToolSearchRuntimeTools(agent, toolSearchOutput, tools) {
-        const runtimeState = this.getOrCreateToolSearchRuntimeToolState(agent.name);
+        const runtimeState = this.getOrCreateToolSearchRuntimeToolState(agent);
         const entry = {
             order: runtimeState.nextOrder++,
             tools,
@@ -543,7 +549,7 @@ export class RunState {
         runtimeState.anonymousEntries.push(entry);
     }
     getToolSearchRuntimeTools(agent) {
-        const runtimeState = this._toolSearchRuntimeToolsByAgentName.get(agent.name);
+        const runtimeState = this._toolSearchRuntimeToolsByAgent.get(agent);
         if (!runtimeState) {
             return [];
         }
@@ -680,15 +686,13 @@ export class RunState {
      * rehydrate in a separate process that lacks the original environment variables).
      */
     toJSON(options = {}) {
-        buildAgentMap(this.#startingAgent);
+        const agentIdentity = buildAgentIdentityMap(this.#startingAgent);
         const includeTracingApiKey = options.includeTracingApiKey === true;
         const contextJson = this._context.toJSON();
         const output = {
             $schemaVersion: CURRENT_SCHEMA_VERSION,
             currentTurn: this._currentTurn,
-            currentAgent: {
-                name: this._currentAgent.name,
-            },
+            currentAgent: serializeAgentReference(this._currentAgent, agentIdentity.byAgent),
             originalInput: this._originalInput,
             modelResponses: this._modelResponses.map((response) => {
                 return {
@@ -720,7 +724,9 @@ export class RunState {
                 };
             }),
             context: contextJson,
-            toolUseTracker: this._toolUseTracker.toJSON(),
+            toolUseTracker: this._toolUseTracker.toJSON({
+                agentIdentityKeys: agentIdentity.byAgent,
+            }),
             maxTurns: this._maxTurns,
             currentAgentSpan: this._currentAgentSpan?.toJSON(),
             noActiveAgentRun: this._noActiveAgentRun,
@@ -728,16 +734,18 @@ export class RunState {
             inputGuardrailResults: this._inputGuardrailResults,
             outputGuardrailResults: this._outputGuardrailResults.map((r) => ({
                 ...r,
-                agent: r.agent.toJSON(),
+                agent: serializeAgentReference(r.agent, agentIdentity.byAgent),
             })),
             toolInputGuardrailResults: this._toolInputGuardrailResults,
             toolOutputGuardrailResults: this._toolOutputGuardrailResults,
-            currentStep: this._currentStep,
+            currentStep: serializeCurrentStep(this._currentStep, agentIdentity.byAgent),
             lastModelResponse: this._lastTurnResponse,
-            generatedItems: this._generatedItems.map((item) => item.toJSON()),
+            generatedItems: this._generatedItems.map((item) => serializeRunItem(item, agentIdentity.byAgent)),
             pendingAgentToolRuns: Object.fromEntries(this._pendingAgentToolRuns.entries()),
             currentTurnPersistedItemCount: this._currentTurnPersistedItemCount,
-            lastProcessedResponse: this._lastProcessedResponse,
+            lastProcessedResponse: this._lastProcessedResponse
+                ? serializeProcessedResponse(this._lastProcessedResponse, agentIdentity.byAgent)
+                : undefined,
             conversationId: this._conversationId,
             previousResponseId: this._previousResponseId,
             reasoningItemIdPolicy: this._reasoningItemIdPolicy,
@@ -797,7 +805,10 @@ async function buildRunStateFromString(initialAgent, str, options = {}) {
     return buildRunStateFromJson(initialAgent, stateJson, options);
 }
 function assertSchemaVersionSupportsToolSearch(schemaVersion, stateJson) {
-    if (schemaVersion === '1.8' || schemaVersion === '1.9') {
+    if (schemaVersion === '1.8' ||
+        schemaVersion === '1.9' ||
+        schemaVersion === '1.10' ||
+        schemaVersion === CURRENT_SCHEMA_VERSION) {
         return;
     }
     if (!containsSerializedToolSearchState(stateJson)) {
@@ -805,6 +816,9 @@ function assertSchemaVersionSupportsToolSearch(schemaVersion, stateJson) {
     }
     throw new UserError(`Run state schema version ${schemaVersion} does not support tool_search items. Please reserialize the run state with schema ${CURRENT_SCHEMA_VERSION}.`);
 }
+function schemaVersionSupportsAgentIdentity(schemaVersion) {
+    return schemaVersion === '1.10' || schemaVersion === CURRENT_SCHEMA_VERSION;
+}
 function containsSerializedToolSearchState(stateJson) {
     return (containsToolSearchProtocolItems(stateJson.originalInput) ||
         containsToolSearchInModelResponses(stateJson.modelResponses) ||
@@ -908,17 +922,17 @@ function assertRuntimeToolKeysMatch(args) {
     throw new UserError(`RunState cannot resume custom client tool_search call ${callId} for agent ${agent.name} because the registered execute callback returned runtime tools [${formatRuntimeToolKeys(actualRuntimeToolKeys)}] but the serialized state expects [${formatRuntimeToolKeys(expectedRuntimeToolKeys)}].`);
 }
 async function getConfiguredAgentTools(args) {
-    const { agent, context, configuredToolsByAgentName } = args;
-    const existing = configuredToolsByAgentName.get(agent.name);
+    const { agent, context, configuredToolsByAgent } = args;
+    const existing = configuredToolsByAgent.get(agent);
     if (existing) {
         return existing;
     }
     const configuredTools = (await agent.getAllTools(context));
-    configuredToolsByAgentName.set(agent.name, configuredTools);
+    configuredToolsByAgent.set(agent, configuredTools);
     return configuredTools;
 }
 async function rehydrateToolSearchRuntimeTools(state) {
-    const configuredToolsByAgentName = new Map();
+    const configuredToolsByAgent = new Map();
     const pendingToolSearchCalls = new Map();
     for (const item of state._generatedItems) {
         if (item instanceof RunToolSearchCallItem) {
@@ -926,10 +940,14 @@ async function rehydrateToolSearchRuntimeTools(state) {
                 continue;
             }
             const callId = resolveToolSearchCallId(item.rawItem);
-            pendingToolSearchCalls.set(`${item.agent.name}:${callId}`, {
+            const agent = item.agent;
+            const pendingCallsById = pendingToolSearchCalls.get(agent) ??
+                new Map();
+            pendingCallsById.set(callId, {
                 agent: item.agent,
                 toolSearchCall: item.rawItem,
             });
+            pendingToolSearchCalls.set(agent, pendingCallsById);
             continue;
         }
         if (!(item instanceof RunToolSearchOutputItem)) {
@@ -941,7 +959,7 @@ async function rehydrateToolSearchRuntimeTools(state) {
         const configuredTools = await getConfiguredAgentTools({
             agent: item.agent,
             context: state._context,
-            configuredToolsByAgentName,
+            configuredToolsByAgent,
         });
         const configuredToolKeys = getRuntimeToolKeys(configuredTools, {
             allowUnsupported: true,
@@ -951,7 +969,9 @@ async function rehydrateToolSearchRuntimeTools(state) {
             continue;
         }
         const callId = resolveToolSearchCallId(item.rawItem);
-        const pendingCall = pendingToolSearchCalls.get(`${item.agent.name}:${callId}`);
+        const pendingCall = pendingToolSearchCalls
+            .get(item.agent)
+            ?.get(callId);
         if (!pendingCall) {
             throw new UserError(`RunState cannot resume custom client tool_search output ${callId} for agent ${item.agent.name} because the serialized state is missing the matching tool_search call item.`);
         }
@@ -994,7 +1014,9 @@ async function rehydrateToolSearchRuntimeTools(state) {
     }
 }
 async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
-    const agentMap = buildAgentMap(initialAgent);
+    const agentMap = schemaVersionSupportsAgentIdentity(stateJson.$schemaVersion)
+        ? buildAgentIdentityMap(initialAgent).byIdentity
+        : buildAgentMap(initialAgent);
     const contextOverride = options.contextOverride;
     const contextStrategy = options.contextStrategy ?? 'merge';
     //
@@ -1019,10 +1041,7 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
     //
     // Find the current agent from the initial agent
     //
-    const currentAgent = agentMap.get(stateJson.currentAgent.name);
-    if (!currentAgent) {
-        throw new UserError(`Agent ${stateJson.currentAgent.name} not found`);
-    }
+    const currentAgent = resolveSerializedAgent(stateJson.currentAgent, agentMap);
     const state = new RunState(context, '', initialAgent, stateJson.maxTurns);
     state._currentAgent = currentAgent;
     state._currentTurn = stateJson.currentTurn;
@@ -1033,7 +1052,13 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
     // rebuild tool use tracker
     state._toolUseTracker = new AgentToolUseTracker();
     for (const [agentName, toolNames] of Object.entries(stateJson.toolUseTracker)) {
-        state._toolUseTracker.addToolUse(agentMap.get(agentName), toolNames, { allowEmpty: true });
+        const agent = agentMap.get(agentName);
+        if (!agent) {
+            throw new UserError(`Agent ${agentName} not found`);
+        }
+        state._toolUseTracker.addToolUse(agent, toolNames, {
+            allowEmpty: true,
+        });
     }
     state._pendingAgentToolRuns = new Map(Object.entries(stateJson.pendingAgentToolRuns ?? {}));
     // rebuild current agent span
@@ -1056,7 +1081,7 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
         stateJson.inputGuardrailResults;
     state._outputGuardrailResults = stateJson.outputGuardrailResults.map((r) => ({
         ...r,
-        agent: agentMap.get(r.agent.name),
+        agent: resolveSerializedAgent(r.agent, agentMap),
     }));
     state._toolInputGuardrailResults =
         stateJson.toolInputGuardrailResults;
@@ -1079,7 +1104,7 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
     if (stateJson.currentStep?.type === 'next_step_handoff') {
         state._currentStep = {
             type: 'next_step_handoff',
-            newAgent: agentMap.get(stateJson.currentStep.newAgent.name),
+            newAgent: resolveSerializedAgent(stateJson.currentStep.newAgent, agentMap),
         };
     }
     else if (stateJson.currentStep?.type === 'next_step_interruption') {
@@ -1100,7 +1125,9 @@ export async function rehydrateProcessedResponseTools(initialAgent, state, execu
     if (!state._lastProcessedResponse) {
         return;
     }
-    state._lastProcessedResponse = await deserializeProcessedResponse(buildAgentMap(initialAgent), state, state._lastProcessedResponse, {
+    const agentIdentity = buildAgentIdentityMap(initialAgent);
+    const serializedProcessedResponse = serializeProcessedResponse(state._lastProcessedResponse, agentIdentity.byAgent);
+    state._lastProcessedResponse = await deserializeProcessedResponse(agentIdentity.byIdentity, state, serializedProcessedResponse, {
         executionTools,
         allowSerializedExecutionToolPlaceholder: false,
     });
@@ -1140,6 +1167,250 @@ export function buildAgentMap(initialAgent) {
     }
     return map;
 }
+/**
+ * @internal
+ */
+export function buildAgentIdentityMap(initialAgent) {
+    const agents = collectAgentGraph(initialAgent);
+    const groups = new Map();
+    const literalNames = new Set();
+    for (const entry of agents) {
+        literalNames.add(entry.agent.name);
+        const group = groups.get(entry.agent.name) ?? [];
+        group.push(entry);
+        groups.set(entry.agent.name, group);
+    }
+    const byIdentity = new Map();
+    const byAgent = new Map();
+    const usedIdentities = new Set();
+    for (const [agentName, group] of groups) {
+        const sortedGroup = group.length === 1
+            ? group
+            : [...group].sort((left, right) => {
+                if (left.agent === initialAgent) {
+                    return -1;
+                }
+                if (right.agent === initialAgent) {
+                    return 1;
+                }
+                const leftSignature = getAgentIdentitySignature(left.agent);
+                const rightSignature = getAgentIdentitySignature(right.agent);
+                if (leftSignature !== rightSignature) {
+                    return leftSignature < rightSignature ? -1 : 1;
+                }
+                return left.index - right.index;
+            });
+        let nextSuffix = 0;
+        for (const { agent } of sortedGroup) {
+            let identity;
+            do {
+                identity =
+                    nextSuffix === 0 ? agentName : `${agentName}#${nextSuffix + 1}`;
+                nextSuffix += 1;
+            } while (usedIdentities.has(identity) ||
+                (identity !== agent.name && literalNames.has(identity)));
+            usedIdentities.add(identity);
+            byIdentity.set(identity, agent);
+            byAgent.set(agent, identity);
+        }
+    }
+    return { byIdentity, byAgent };
+}
+function collectAgentGraph(initialAgent) {
+    const agents = [];
+    const visitedAgents = new Set();
+    const queue = [initialAgent];
+    while (queue.length > 0) {
+        const currentAgent = queue.shift();
+        if (visitedAgents.has(currentAgent)) {
+            continue;
+        }
+        visitedAgents.add(currentAgent);
+        agents.push({ agent: currentAgent, index: agents.length });
+        for (const handoff of currentAgent.handoffs) {
+            if (handoff instanceof Agent) {
+                queue.push(handoff);
+            }
+            else if (handoff.agent) {
+                queue.push(handoff.agent);
+            }
+        }
+        for (const tool of currentAgent.tools) {
+            const sourceAgent = getAgentToolSourceAgent(tool);
+            if (sourceAgent) {
+                queue.push(sourceAgent);
+            }
+        }
+    }
+    return agents;
+}
+function getAgentIdentitySignature(agent) {
+    const sandboxAgent = agent;
+    const signature = {
+        type: agent.constructor?.name,
+        name: agent.name,
+        handoffDescription: agent.handoffDescription,
+        instructions: summarizeIdentityValue(agent.instructions),
+        prompt: summarizeIdentityValue(agent.prompt),
+        model: summarizeIdentityValue(agent.model),
+        modelSettings: summarizeIdentityValue(agent.modelSettings),
+        tools: agent.tools.map(summarizeToolIdentity),
+        handoffs: agent.handoffs.map((entry) => entry instanceof Agent
+            ? { type: 'agent', name: entry.name }
+            : {
+                type: 'handoff',
+                toolName: entry.toolName,
+                agentName: entry.agentName,
+                targetName: entry.agent?.name,
+            }),
+        mcpServers: agent.mcpServers.map(summarizeIdentityValue),
+        mcpConfig: summarizeIdentityValue(agent.mcpConfig),
+        inputGuardrails: agent.inputGuardrails.map(summarizeIdentityValue),
+        outputGuardrails: agent.outputGuardrails.map(summarizeIdentityValue),
+        outputType: summarizeIdentityValue(agent.outputType),
+        toolUseBehavior: summarizeIdentityValue(agent.toolUseBehavior),
+        resetToolChoice: agent.resetToolChoice,
+        defaultManifest: summarizeIdentityValue(sandboxAgent.defaultManifest),
+        baseInstructions: summarizeIdentityValue(sandboxAgent.baseInstructions),
+        capabilities: sandboxAgent.capabilities?.map(summarizeIdentityValue),
+        runAs: summarizeIdentityValue(sandboxAgent.runAs),
+    };
+    return stableStringify(signature);
+}
+function summarizeToolIdentity(tool) {
+    return {
+        type: tool.type,
+        name: tool.name,
+        namespace: tool.namespace,
+        strict: tool.strict,
+        parameters: summarizeIdentityValue(tool.parameters),
+    };
+}
+function summarizeIdentityValue(value) {
+    return normalizeForIdentity(value, new WeakSet(), 0);
+}
+function normalizeForIdentity(value, seen, depth) {
+    if (value === null || typeof value === 'undefined') {
+        return value;
+    }
+    if (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'function') {
+        return `[function:${value.name || 'anonymous'}]`;
+    }
+    if (typeof value !== 'object') {
+        return String(value);
+    }
+    if (seen.has(value)) {
+        return '[circular]';
+    }
+    if (depth >= 4) {
+        return `[${value.constructor?.name ?? 'Object'}]`;
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeForIdentity(item, seen, depth + 1));
+    }
+    if (value instanceof Map) {
+        return [...value.entries()]
+            .map(([key, entryValue]) => [
+            normalizeForIdentity(key, seen, depth + 1),
+            normalizeForIdentity(entryValue, seen, depth + 1),
+        ])
+            .sort((left, right) => stableStringify(left).localeCompare(stableStringify(right)));
+    }
+    if (value instanceof Set) {
+        return [...value.values()]
+            .map((entry) => normalizeForIdentity(entry, seen, depth + 1))
+            .sort((left, right) => stableStringify(left).localeCompare(stableStringify(right)));
+    }
+    const record = value;
+    const normalized = {
+        constructor: value.constructor?.name,
+    };
+    for (const key of Object.keys(record).sort()) {
+        normalized[key] = normalizeForIdentity(record[key], seen, depth + 1);
+    }
+    return normalized;
+}
+function stableStringify(value) {
+    return JSON.stringify(value, (_key, currentValue) => {
+        if (!currentValue ||
+            typeof currentValue !== 'object' ||
+            Array.isArray(currentValue)) {
+            return currentValue;
+        }
+        return Object.fromEntries(Object.entries(currentValue).sort(([left], [right]) => left.localeCompare(right)));
+    });
+}
+function serializeAgentReference(agent, agentIdentityKeys) {
+    const identity = agentIdentityKeys.get(agent);
+    if (!identity || identity === agent.name) {
+        return { name: agent.name };
+    }
+    return { name: agent.name, identity };
+}
+function resolveSerializedAgent(serializedAgent, agentMap, fallbackAgent) {
+    const identity = serializedAgent.identity ?? serializedAgent.name;
+    const agent = agentMap.get(identity);
+    if (agent) {
+        return agent;
+    }
+    if (!serializedAgent.identity && fallbackAgent) {
+        return fallbackAgent;
+    }
+    if (serializedAgent.identity) {
+        throw new UserError(`Agent identity ${serializedAgent.identity} not found`);
+    }
+    throw new UserError(`Agent ${serializedAgent.name} not found`);
+}
+function serializeRunItem(item, agentIdentityKeys) {
+    const serialized = item.toJSON();
+    switch (item.type) {
+        case 'handoff_output_item':
+            serialized.sourceAgent = serializeAgentReference(item.sourceAgent, agentIdentityKeys);
+            serialized.targetAgent = serializeAgentReference(item.targetAgent, agentIdentityKeys);
+            return serialized;
+        default:
+            serialized.agent = serializeAgentReference(item.agent, agentIdentityKeys);
+            return serialized;
+    }
+}
+function serializeCurrentStep(currentStep, agentIdentityKeys) {
+    if (!currentStep) {
+        return undefined;
+    }
+    if (currentStep.type === 'next_step_handoff') {
+        return {
+            ...currentStep,
+            newAgent: serializeAgentReference(currentStep.newAgent, agentIdentityKeys),
+        };
+    }
+    if (currentStep.type === 'next_step_interruption') {
+        const interruptions = Array.isArray(currentStep.data?.interruptions)
+            ? currentStep.data.interruptions.map((item) => item instanceof RunToolApprovalItem
+                ? serializeRunItem(item, agentIdentityKeys)
+                : item)
+            : currentStep.data?.interruptions;
+        return {
+            ...currentStep,
+            data: {
+                ...currentStep.data,
+                interruptions,
+            },
+        };
+    }
+    return currentStep;
+}
+function serializeProcessedResponse(processedResponse, agentIdentityKeys) {
+    return {
+        ...processedResponse,
+        newItems: processedResponse.newItems.map((item) => serializeRunItem(item, agentIdentityKeys)),
+    };
+}
 /**
  * @internal
  */
@@ -1178,23 +1449,23 @@ export function deserializeModelResponse(serializedModelResponse) {
 export function deserializeItem(serializedItem, agentMap) {
     switch (serializedItem.type) {
         case 'message_output_item':
-            return new RunMessageOutputItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name));
+            return new RunMessageOutputItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap));
         case 'tool_search_call_item':
-            return new RunToolSearchCallItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name));
+            return new RunToolSearchCallItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap));
         case 'tool_search_output_item':
-            return new RunToolSearchOutputItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name));
+            return new RunToolSearchOutputItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap));
         case 'tool_call_item':
-            return new RunToolCallItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name));
+            return new RunToolCallItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap));
         case 'tool_call_output_item':
-            return new RunToolCallOutputItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name), serializedItem.output);
+            return new RunToolCallOutputItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap), serializedItem.output);
         case 'reasoning_item':
-            return new RunReasoningItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name));
+            return new RunReasoningItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap));
         case 'handoff_call_item':
-            return new RunHandoffCallItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name));
+            return new RunHandoffCallItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap));
         case 'handoff_output_item':
-            return new RunHandoffOutputItem(serializedItem.rawItem, agentMap.get(serializedItem.sourceAgent.name), agentMap.get(serializedItem.targetAgent.name));
+            return new RunHandoffOutputItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.sourceAgent, agentMap), resolveSerializedAgent(serializedItem.targetAgent, agentMap));
         case 'tool_approval_item':
-            return new RunToolApprovalItem(serializedItem.rawItem, agentMap.get(serializedItem.agent.name), serializedItem.toolName);
+            return new RunToolApprovalItem(serializedItem.rawItem, resolveSerializedAgent(serializedItem.agent, agentMap), serializedItem.toolName);
     }
 }
 function deserializeInterruptionItem(serializedItem, agentMap, currentAgent) {
@@ -1204,7 +1475,7 @@ function deserializeInterruptionItem(serializedItem, agentMap, currentAgent) {
     const parsed = itemSchema.safeParse(serializedItem);
     if (parsed.success) {
         if (parsed.data.type === 'tool_approval_item') {
-            const mappedAgent = agentMap.get(parsed.data.agent.name) ?? currentAgent;
+            const mappedAgent = resolveSerializedAgent(parsed.data.agent, agentMap, currentAgent);
             return new RunToolApprovalItem(parsed.data.rawItem, mappedAgent, parsed.data.toolName);
         }
         const item = deserializeItem(parsed.data, agentMap);
@@ -1228,7 +1499,15 @@ function deserializeInterruptionItem(serializedItem, agentMap, currentAgent) {
     const agentName = value.agent && typeof value.agent.name === 'string'
         ? value.agent.name
         : undefined;
-    const mappedAgent = (agentName ? agentMap.get(agentName) : undefined) ?? currentAgent;
+    const agentIdentity = value.agent && typeof value.agent.identity === 'string'
+        ? value.agent.identity
+        : undefined;
+    const mappedAgent = agentName || agentIdentity
+        ? resolveSerializedAgent({
+            name: agentName ?? currentAgent.name,
+            identity: agentIdentity,
+        }, agentMap, currentAgent)
+        : currentAgent;
     const toolName = typeof value.toolName === 'string'
         ? value.toolName
         : typeof rawItem.name === 'string'