Hosted Session Management with azd
Use azd to manage session-backed compute and filesystem state for Hosted Agents.
Automatic Session Handling
For responses and invocations, start with azd ai agent invoke. Do not create a session first unless the workflow needs a known session before invocation.
Within an azd project, azd resolves session state for a normal remote invoke in this order:
- Use and persist an explicit
--session-id. - Reuse the session saved for the agent endpoint.
- If no session exists, let the server assign one, capture the returned session ID, and save it for later commands.
--new-session ignores the saved session and starts fresh session-backed state. --version <version> creates or reuses a session bound to that deployed version. Do not combine --version with --session-id.
File and monitor commands automatically use the session saved by invoke or sessions create. They also accept --session-id <id>.
Session and Conversation State
| State | Used by | azd behavior |
|---|---|---|
| Session | All directly invocable Hosted protocols | Persisted per agent; controls compute affinity and filesystem state |
| Conversation | responses |
Platform-managed; azd can persist the conversationId for reuse |
Use --new-conversation to reset responses history without replacing the session. Use --new-session to reset session-backed memory for invocations. --new-conversation has no effect for invocations. For completely fresh responses state, combine --new-session and --new-conversation.
Explicit Session Commands
Create a session when files must be uploaded before the first invoke, when a caller-selected ID is required, or when binding to a specific version:
azd ai agent sessions create
azd ai agent sessions create my-agent <version>
azd ai agent sessions create --session-id my-sessionThe create command auto-detects a single agent and resolves the deployed version from the azd environment. It prints JSON by default and persists agent_session_id as the current session.
Inspect and enumerate sessions:
azd ai agent sessions show <session-id>
azd ai agent sessions list
azd ai agent sessions list --limit 10 --output table
azd ai agent sessions list --pagination-token <token>Use --agent-name <service-name> for show, stop, delete, or list when the project has multiple agent services. For header-based isolation, pass the same --user-identity on every session, invoke, file, and monitor command.
Stop Versus Delete
azd ai agent sessions stop <session-id>
azd ai agent sessions delete <session-id>stop terminates running compute and preserves the persistent filesystem. It is idempotent, and a later invocation can resume the session.
delete synchronously removes compute and filesystem state. If the deleted ID is the saved current session, azd clears it from its session store.
Common Patterns
Continue a multi-turn interaction:
azd ai agent invoke "First question"
azd ai agent invoke "Follow-up question"Reset responses history while keeping session files:
azd ai agent invoke --new-conversation "Start a new topic"Reset session-backed memory:
azd ai agent invoke --new-session "Start fresh"Preserve files without keeping compute running:
azd ai agent sessions stop <session-id>WebSocket Sessions
invocations_ws is not called by azd ai agent invoke. Its client supplies agent_session_id on the WebSocket URL. Follow Invocations WebSocket for that connection lifecycle.