Migrate hosted agent isolation keys to user identity

Current Azure Developer CLI Foundry extensions use --user-identity for delegated end-user requests. The earlier --isolation-key, --user-isolation-key, and --chat-isolation-key flags aren't supported. This article shows how to update scripts that used those flags.

Prerequisites

Choose the current identity model

For ordinary calls, omit --user-identity. Foundry uses the identity from your Microsoft Entra token.

For a trusted service acting on behalf of its own authenticated customers, pass --user-identity. Remote calls send x-ms-user-identity; local calls send x-agent-user-id. The header doesn't replace authentication.

Earlier flag Current approach
--isolation-key Use the signed-in identity, or --user-identity for delegated requests. There isn't a separate CLI session-ownership key.
--user-isolation-key Use --user-identity after configuring delegation permissions. This isn't a rename of the old header.
--chat-isolation-key Track a separate session or conversation ID for each chat. There isn't an equivalent chat-isolation header flag.

Your application must derive the identifier from a trusted, authenticated identity. It must also keep each user's session IDs separate. Foundry doesn't enforce a boundary between delegated end users who access the same session. See Isolate sessions for your own users.

Invoke for an application user

Start a new session when switching users. These examples use my-agent, the agent service name in azure.yaml:

azd ai agent invoke my-agent \
  --user-identity "contoso:customer-123" \
  --new-session \
  "Summarize my open tickets"

Record the returned session ID for this customer. Pass it explicitly on subsequent calls:

azd ai agent invoke my-agent \
  --user-identity "contoso:customer-123" \
  --session-id <customer-session-id> \
  "Show more detail"

The CLI saves the last session per agent, not per application user. Don't rely on that saved selection when testing multiple users.

Manage the same user's sessions, files, and logs

Repeat the same identity on each operation. You can create a session before invoking the agent, for example to upload input files first:

azd ai agent sessions create \
  --agent-name my-agent \
  --version 3 \
  --user-identity "contoso:customer-123"

Use the returned session ID for file and log operations:

azd ai agent files upload my-agent ./seed.json \
  --session-id <customer-session-id> \
  --user-identity "contoso:customer-123"

azd ai agent files list \
  --agent-name my-agent \
  --session-id <customer-session-id> \
  --user-identity "contoso:customer-123"

azd ai agent monitor my-agent --follow \
  --session-id <customer-session-id> \
  --user-identity "contoso:customer-123"

To stop compute while preserving files, use sessions stop. To permanently remove the session and its filesystem, use sessions delete:

azd ai agent sessions stop <customer-session-id> \
  --agent-name my-agent \
  --user-identity "contoso:customer-123"

azd ai agent sessions delete <customer-session-id> \
  --agent-name my-agent \
  --user-identity "contoso:customer-123"

Distinguish identity from custom request headers

For application-specific metadata, invoke accepts repeatable --client-header "x-client-<name>: <value>" flags. Only the x-client-* family is accepted, and the A2A protocol doesn't support this flag. These headers don't configure platform user isolation.

Use --output raw to inspect the response status, headers, and body. Response headers don't necessarily echo request headers, so raw output alone doesn't prove that the agent received a particular header.

Troubleshoot migrated scripts

Symptom What to check
Unknown isolation-key flag Replace the retired flags using the current identity model, rather than changing only the header name.
403 after adding --user-identity Confirm the calling identity has the custom UserIdentityImpersonation permission. Built-in roles don't grant it.
A different customer reuses an existing session Pass --new-session when switching customers, then maintain a user-to-session mapping.
Files or logs aren't accessible Pass the correct session ID and the identity used for that session.
Local tests don't enforce isolation Local headers support testing call context, not platform isolation. Verify isolation against a deployed agent.

Related content

  • Last updated on