Keep entity identities stable across agents and memory

Learning objective

Preserve entity continuity across turns, agents, and retrieved memories.

Core idea

For an architect designing a multi-agent workflow, entity continuity means that every reference to a person, account, order, or case resolves to the intended business object. A conversation can retain all its messages and still confuse two people with the same name. A memory can retrieve a relevant preference and attach it to the wrong customer.

Carry a stable business identifier with the facts that describe the entity. Treat names, pronouns, and semantic similarity as clues for resolving that identifier, rather than as the identifier itself. Keep uncertainty explicit when the available evidence cannot distinguish candidates.

The Microsoft mechanisms transport and retrieve context; your application defines what counts as the same business entity. See 2.2.2 for handoff contracts, 2.2.6 for memory isolation, and 3.1.5 for cross-session memory tests. This lesson focuses on preserving the association between a fact and its subject along those paths.

How it works

Resolve references into a trusted record

Define an application-owned entity record containing a business ID, entity type, authorized tenant or account, display name, known aliases, and source references. These are fields you design, not a built-in Foundry entity schema. A source reference should identify the record or interaction supporting a fact; a correction should retain enough provenance to explain why the accepted value changed.

Separate recognition from resolution. Recognizing “Alex” as a person does not establish which Alex the user means. Resolve the mention against authorized candidates and the task’s established subject. If two candidates remain plausible, request a distinguishing attribute before continuing an action. Do not let the model invent an ID from the display name.

Pronouns require the same discipline. After a user discusses two orders, “cancel that one” is unresolved until the conversation establishes which order it denotes. Preserve the unresolved reference as a task state, rather than writing a guessed order ID into shared state. A clarification costs a turn; a wrong association can contaminate every downstream agent and memory update.

Preserve the subject across turns and agents

In Microsoft Agent Framework for Python, create a session with agent.create_session() and pass it as session=session to subsequent agent.run() calls. AgentSession.state is a mutable dictionary shared with context and history providers. It can carry your entity record alongside conversation state. Its session_id identifies the local session; service_session_id identifies remote history when service-managed history is used. Neither substitutes for a customer or order ID.

Reuse the authorized session for conversation continuity, but make the active business subject explicit in the context each specialist receives. A billing agent needs the resolved account and invoice IDs, not every personal detail collected by a support agent. Transfer aliases only when they help interpret the task, and preserve the original source references with disputed facts.

For Python workflows, WorkflowContext.set_state() and WorkflowContext.get_state() let downstream executors write and read a value under a consistent key. Store the accepted entity record under an application-defined key, such as active_case. Designate which executor can change the resolved subject; downstream specialists propose corrections for that owner to validate.

The .NET workflow state API differs: QueueStateUpdateAsync and ReadStateAsync use a shared non-null scopeName to share state across executors. Other executors see queued updates beginning in the next superstep. A reader using the private default scope or expecting immediate visibility can appear to lose continuity even though the correct record was written. Distinguish propagation timing from faulty entity resolution.

Reconcile retrieved memories with the active entity

Foundry Agent Service Memory and the Memory Store API are preview capabilities. Memory scope partitions records; it is not a universal entity resolver. Choose the scope through trusted application identity and retain business entity IDs inside the evidence you supply. A user can discuss several companies or orders within one legitimate scope.

The Python project_client.beta.memory_stores.search_memories() call accepts the store name and scope. Searching with items set to the messages retrieves contextual memories. Searching with a scope but without items or previous_search_id retrieves static user-profile memories. Select the mode according to the evidence needed, then inspect whether each returned fact belongs to the active subject.

A relevant memory about “Alex’s delivery preference” remains ambiguous if its provenance does not distinguish two Alexes. Keep it as unresolved evidence and retrieve an authoritative record or ask for clarification. Do not overwrite a resolved business ID because a memory ranks highly. Retrieval quality and subject correctness are separate checks; see 3.2.5 for recall-method selection.

For a verified correction to a specific stored item, the Python item-level operation is project_client.beta.memory_stores.update_memory(name=..., memory_id=..., content=...). Identify the item and verify its ownership before updating it. Updating memory content repairs stored evidence; it does not automatically repair copies already carried in agent sessions or workflow state. Refresh those copies through their designated owner.

Key distinctions and trade-offs

Session continuity versus entity continuity: Reusing the session preserves the conversation container. Preserving the business ID maintains the subject of its facts. Test both rather than inferring one from the other.

Isolation versus resolution: A correct memory scope excludes another user’s memory. It can still contain multiple entities mentioned by the same user. Resolve those entities within the authorized scope.

Alias versus identity: A display name or company nickname helps interpret a mention. A stable ID survives renaming and distinguishes matching names. Retain aliases without merging their records automatically.

Explicit records consume context and require correction logic. Free-form summaries are shorter but can erase the association between a fact and its subject. Prefer a compact record of critical IDs and commitments, with narrative context added only where it explains the task.

Architecture / decision scenario

A support conversation concerns customer Alex Morgan and two shipments. The user corrects the destination for shipment S-204, then delegates invoice review to a billing specialist. A retrieved memory mentions Alex’s usual delivery address, which differs from the correction.

The coordinator retains S-204 as the resolved subject in the Python session’s application-owned entity record and writes the accepted case state with WorkflowContext.set_state(). The billing executor reads that key with get_state() and receives the matching account and invoice IDs. It does not resolve the shipment again from the name Alex.

Memory search uses the authenticated customer’s scope and the correction messages as items. The application compares the returned preference with the shipment-specific correction and its source. It preserves the corrected destination for this shipment; a usual address is not evidence that every shipment must use it. If an individual memory item is demonstrably wrong, the owner updates that memory_id and refreshes the task record. A subsequent turn referring to “the corrected shipment” resolves to S-204, while an ambiguous reference to “the other one” requires clarification.

Common exam traps

• Treating a conversation ID as a business entity ID or an authorization check.
• Assuming a shared memory scope contains only one entity.
• Joining records because their names or embeddings are similar.
• Dropping IDs while retaining only a fluent handoff summary.
• Expecting .NET shared state updates to reach other executors in the same superstep.
• Assuming a memory correction rewrites active session and workflow copies.

What to remember

Preserve the subject as well as the fact. Use stable business IDs, authorized session and memory selection, explicit shared state, and source-backed correction rules. When identity remains ambiguous, retain the uncertainty instead of spreading a guessed association through the workflow.

Knowledge check

References

• Microsoft, Session
• Microsoft, Microsoft Agent Framework workflows: State
• Microsoft, Create and use memory in Foundry Agent Service