@openai/agents-core 0.8.5 → 0.9.1

package/dist/runState.mjs

@@ -13,11 +13,13 @@ import { getCurrentTrace } from "./tracing/index.mjs";
 import logger from "./logger.mjs";
 import { handoff } from "./handoff.mjs";
 import * as protocol from "./types/protocol.mjs";
+import { SANDBOX_SESSION_STATE_VERSION } from "./sandbox/session.mjs";
 import { safeExecute } from "./utils/safeExecute.mjs";
 import { getClientToolSearchExecutor, getToolSearchRuntimeToolKey, } from "./tool.mjs";
 import { getFunctionToolQualifiedName, toolQualifiedName, resolveFunctionToolCallName, } from "./toolIdentity.mjs";
 import { getToolSearchExecution, getToolSearchOutputReplacementKey, resolveToolSearchCallId, } from "./utils/toolSearch.mjs";
 import { executeCustomClientToolSearch, getClientToolSearchHelper, } from "./runner/toolSearch.mjs";
+import { getSerializedApplyPatchToolPlaceholder, getSerializedComputerToolPlaceholder, getSerializedFunctionToolPlaceholder, getSerializedShellToolPlaceholder, } from "./sandbox/runtime/toolRehydration.mjs";
 /**
  * The schema version of the serialized run state. This is used to ensure that the serialized
  * run state is compatible with the current version of the SDK.
@@ -36,8 +38,12 @@ import { executeCustomClientToolSearch, getClientToolSearchHelper, } from "./run
  * - 1.7: Adds optional approval rejection messages.
  * - 1.8: Adds tool search item variants, batched computer actions, and GA computer tool
  *   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.
  */
-export const CURRENT_SCHEMA_VERSION = '1.8';
+export const CURRENT_SCHEMA_VERSION = '1.10';
 const SUPPORTED_SCHEMA_VERSIONS = [
     '1.0',
     '1.1',
@@ -47,11 +53,14 @@ const SUPPORTED_SCHEMA_VERSIONS = [
     '1.5',
     '1.6',
     '1.7',
+    '1.8',
+    '1.9',
     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'),
@@ -160,6 +169,32 @@ const serializedTraceSchema = z.object({
     // and serialization opts in to include it. By default this is omitted to avoid persisting secrets.
     tracing_api_key: z.string().optional().nullable(),
 });
+const sandboxSessionStateEnvelopeSchema = z.object({
+    version: z.literal(SANDBOX_SESSION_STATE_VERSION),
+    backendId: z.string(),
+    manifest: z.record(z.string(), z.any()),
+    snapshot: z.record(z.string(), z.any()).nullable().optional(),
+    snapshotFingerprint: z.string().nullable().optional(),
+    snapshotFingerprintVersion: z.string().nullable().optional(),
+    workspaceReady: z.boolean(),
+    exposedPorts: z.record(z.string(), z.any()).optional(),
+    providerState: z.record(z.string(), z.any()),
+});
+const sandboxSessionEntrySchema = z.object({
+    backendId: z.string(),
+    currentAgentKey: z.string(),
+    currentAgentName: z.string(),
+    sessionState: sandboxSessionStateEnvelopeSchema,
+    preservedOwnedSession: z.boolean().optional(),
+    reuseLiveSession: z.boolean().optional(),
+});
+const sandboxStateSchema = z.object({
+    backendId: z.string(),
+    currentAgentKey: z.string(),
+    currentAgentName: z.string(),
+    sessionState: sandboxSessionStateEnvelopeSchema,
+    sessionsByAgent: z.record(z.string(), sandboxSessionEntrySchema),
+});
 const serializedProcessedResponseSchema = z.object({
     newItems: z.array(itemSchema),
     toolsUsed: z.array(z.string()),
@@ -300,6 +335,7 @@ export const SerializedRunState = z.object({
     previousResponseId: z.string().optional(),
     reasoningItemIdPolicy: z.enum(['preserve', 'omit']).optional(),
     trace: serializedTraceSchema.nullable(),
+    sandbox: sandboxStateSchema.optional(),
 });
 /**
  * Serializable snapshot of an agent's run, including context, usage and trace.
@@ -438,10 +474,14 @@ 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.
+     */
+    _sandbox = undefined;
     constructor(context, originalInput, startingAgent, maxTurns) {
         this._context = context;
         this._agentToolInvocation = undefined;
@@ -481,20 +521,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,
@@ -507,7 +547,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 [];
         }
@@ -644,15 +684,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 {
@@ -684,7 +722,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,
@@ -692,22 +732,25 @@ 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,
             trace: this._trace
                 ? this._trace.toJSON({ includeTracingApiKey })
                 : null,
+            sandbox: this._sandbox,
         };
         // parsing the schema to ensure the output is valid for reparsing
         const parsed = SerializedRunState.safeParse(output);
@@ -760,7 +803,9 @@ async function buildRunStateFromString(initialAgent, str, options = {}) {
     return buildRunStateFromJson(initialAgent, stateJson, options);
 }
 function assertSchemaVersionSupportsToolSearch(schemaVersion, stateJson) {
-    if (schemaVersion === '1.8') {
+    if (schemaVersion === '1.8' ||
+        schemaVersion === '1.9' ||
+        schemaVersion === CURRENT_SCHEMA_VERSION) {
         return;
     }
     if (!containsSerializedToolSearchState(stateJson)) {
@@ -768,6 +813,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 === CURRENT_SCHEMA_VERSION;
+}
 function containsSerializedToolSearchState(stateJson) {
     return (containsToolSearchProtocolItems(stateJson.originalInput) ||
         containsToolSearchInModelResponses(stateJson.modelResponses) ||
@@ -871,17 +919,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) {
@@ -889,10 +937,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)) {
@@ -904,7 +956,7 @@ async function rehydrateToolSearchRuntimeTools(state) {
         const configuredTools = await getConfiguredAgentTools({
             agent: item.agent,
             context: state._context,
-            configuredToolsByAgentName,
+            configuredToolsByAgent,
         });
         const configuredToolKeys = getRuntimeToolKeys(configuredTools, {
             allowUnsupported: true,
@@ -914,7 +966,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.`);
         }
@@ -957,7 +1011,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';
     //
@@ -982,10 +1038,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;
@@ -996,7 +1049,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
@@ -1019,7 +1078,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;
@@ -1034,6 +1093,7 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
     state._generatedItems = stateJson.generatedItems.map((item) => deserializeItem(item, agentMap));
     state._currentTurnPersistedItemCount =
         stateJson.currentTurnPersistedItemCount ?? 0;
+    state._sandbox = stateJson.sandbox ?? undefined;
     await rehydrateToolSearchRuntimeTools(state);
     state._lastProcessedResponse = stateJson.lastProcessedResponse
         ? await deserializeProcessedResponse(agentMap, state, stateJson.lastProcessedResponse)
@@ -1041,7 +1101,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') {
@@ -1055,6 +1115,20 @@ async function buildRunStateFromJson(initialAgent, stateJson, options = {}) {
     }
     return state;
 }
+/**
+ * @internal
+ */
+export async function rehydrateProcessedResponseTools(initialAgent, state, executionTools) {
+    if (!state._lastProcessedResponse) {
+        return;
+    }
+    const agentIdentity = buildAgentIdentityMap(initialAgent);
+    const serializedProcessedResponse = serializeProcessedResponse(state._lastProcessedResponse, agentIdentity.byAgent);
+    state._lastProcessedResponse = await deserializeProcessedResponse(agentIdentity.byIdentity, state, serializedProcessedResponse, {
+        executionTools,
+        allowSerializedExecutionToolPlaceholder: false,
+    });
+}
 /**
  * @internal
  */
@@ -1090,6 +1164,249 @@ 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),
+        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
  */
@@ -1128,23 +1445,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) {
@@ -1154,7 +1471,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);
@@ -1178,7 +1495,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'
@@ -1197,13 +1522,15 @@ function deserializeInterruptions(serializedInterruptions, agentMap, currentAgen
 /**
  * @internal
  */
-async function deserializeProcessedResponse(agentMap, state, serializedProcessedResponse) {
+async function deserializeProcessedResponse(agentMap, state, serializedProcessedResponse, options = {}) {
     const currentAgent = state._currentAgent;
-    const configuredTools = await currentAgent.getAllTools(state._context);
+    const configuredTools = options.executionTools ?? (await currentAgent.getAllTools(state._context));
     const allTools = [
         ...configuredTools,
         ...state.getToolSearchRuntimeTools(currentAgent),
     ];
+    const baseAgentTools = currentAgent.tools;
+    const allowSerializedExecutionToolPlaceholder = options.allowSerializedExecutionToolPlaceholder ?? true;
     const tools = new Map(allTools
         .filter((tool) => tool.type === 'function')
         .map((tool) => [getFunctionToolQualifiedName(tool) ?? tool.name, tool]));
@@ -1250,17 +1577,33 @@ async function deserializeProcessedResponse(agentMap, state, serializedProcessed
         functions: await Promise.all(serializedProcessedResponse.functions.map(async (functionCall) => {
             const toolIdentity = resolveFunctionToolCallName(functionCall.toolCall, tools) ??
                 functionCall.tool.name;
-            if (!tools.has(toolIdentity)) {
+            const resolvedTool = tools.get(toolIdentity) ??
+                getSerializedFunctionToolPlaceholder({
+                    agent: currentAgent,
+                    baseAgentTools,
+                    serializedTool: functionCall.tool,
+                    toolCall: functionCall.toolCall,
+                    toolIdentity,
+                    allowSerializedExecutionToolPlaceholder,
+                });
+            if (!resolvedTool) {
                 throw new UserError(`Tool ${toolIdentity} not found`);
             }
             return {
                 toolCall: functionCall.toolCall,
-                tool: tools.get(toolIdentity),
+                tool: resolvedTool,
             };
         })),
         computerActions: serializedProcessedResponse.computerActions.map((computerAction) => {
             const toolName = computerAction.computer.name;
-            const computerTool = resolveComputerTool(toolName);
+            const computerTool = resolveComputerTool(toolName) ??
+                getSerializedComputerToolPlaceholder({
+                    agent: currentAgent,
+                    baseAgentTools,
+                    serializedTool: computerAction.computer,
+                    toolName,
+                    allowSerializedExecutionToolPlaceholder,
+                });
             if (!computerTool) {
                 throw new UserError(`Computer tool ${toolName} not found`);
             }
@@ -1271,22 +1614,38 @@ async function deserializeProcessedResponse(agentMap, state, serializedProcessed
         }),
         shellActions: (serializedProcessedResponse.shellActions ?? []).map((shellAction) => {
             const toolName = shellAction.shell.name;
-            if (!shellTools.has(toolName)) {
+            const shellTool = shellTools.get(toolName) ??
+                getSerializedShellToolPlaceholder({
+                    agent: currentAgent,
+                    baseAgentTools,
+                    serializedTool: shellAction.shell,
+                    toolName,
+                    allowSerializedExecutionToolPlaceholder,
+                });
+            if (!shellTool) {
                 throw new UserError(`Shell tool ${toolName} not found`);
             }
             return {
                 toolCall: shellAction.toolCall,
-                shell: shellTools.get(toolName),
+                shell: shellTool,
             };
         }),
         applyPatchActions: (serializedProcessedResponse.applyPatchActions ?? []).map((applyPatchAction) => {
             const toolName = applyPatchAction.applyPatch.name;
-            if (!applyPatchTools.has(toolName)) {
+            const applyPatchTool = applyPatchTools.get(toolName) ??
+                getSerializedApplyPatchToolPlaceholder({
+                    agent: currentAgent,
+                    baseAgentTools,
+                    serializedTool: applyPatchAction.applyPatch,
+                    toolName,
+                    allowSerializedExecutionToolPlaceholder,
+                });
+            if (!applyPatchTool) {
                 throw new UserError(`Apply patch tool ${toolName} not found`);
             }
             return {
                 toolCall: applyPatchAction.toolCall,
-                applyPatch: applyPatchTools.get(toolName),
+                applyPatch: applyPatchTool,
             };
         }),
         mcpApprovalRequests: (serializedProcessedResponse.mcpApprovalRequests ?? []).map((approvalRequest) => ({