Support long-running agent work with unified invocation lifecycle commands

[m5i-work]

Summary

Expose orthogonal primitives for creating and managing agent work while keeping a single lifecycle command group across protocols.

• azd ai agent invoke creates work.
• azd ai agent invocations show|follow|cancel manages existing work.
• --long-running requests continued service-side execution after client disconnection.
• --no-wait controls when the CLI returns.

“Invocations” in the command group is the noun form of invoke, not a restriction to the wire protocol named invocations. Each supported operation maps to the selected protocol's service API. This avoids adding a new resource noun for every future protocol.

CLI contract

# Create work and wait for completion; infer the protocol from the agent
azd ai agent invoke "message"

# Responses: continue service-side execution after disconnection, remain attached
azd ai agent invoke "message" --long-running

# Responses: return after receiving the service-assigned ID
azd ai agent invoke "message" --long-running --no-wait

# Manage current work using the selected agent's protocol
azd ai agent invocations show
azd ai agent invocations follow
azd ai agent invocations cancel

# Select protocol and service-assigned ID explicitly
azd ai agent invocations show --protocol responses --id <response-id>
azd ai agent invocations follow --protocol responses --id <response-id>
azd ai agent invocations cancel --protocol responses --id <response-id>

azd ai agent invoke "message" --protocol invocations
azd ai agent invocations show --protocol invocations --id <invocation-id>
azd ai agent invocations cancel --protocol invocations --id <invocation-id>

--id is optional: omission selects the current ID for the selected agent and protocol. Explicit targeting does not change current selection. There is no separate responses command group, and no compatibility aliases for --background, --resumable, --response-id, or --invocation-id.

Protocol selection

Use the same selection model as invoke:

1. With --agent-endpoint, derive the protocol and agent from the URL. Do not also supply --protocol, --agent-name, or --version to lifecycle commands.
2. Otherwise use explicit --protocol when supplied.
3. Otherwise infer the protocol from the selected agent when unambiguous. Multi-protocol agents require explicit selection.

--agent-name selects an agent in multi-agent projects, following the existing sessions command convention. Do not infer protocols from ID prefixes. Resolve the protocol before reading its current ID.

Explicit --id with --agent-endpoint works without project-backed local state. Authentication and any required --user-identity must still be provided by the caller.

Supported operations

Operation	Responses protocol	Invocations protocol
invoke	Responses create	Existing synchronous, SSE, raw, and 202/poll behavior
invoke --long-running	Supported	Unsupported for now
invocations show	Response snapshot GET	One-shot Invocation GET
invocations follow	One streaming GET, replay from the beginning	Unsupported for now
invocations cancel	Response cancel POST	Invocation cancel POST, if the agent implements it

An unsupported operation fails clearly before issuing a lifecycle request. A CLI-supported operation can still fail if the deployed agent does not implement the corresponding endpoint.

The service team may add long-running support to protocols such as A2A later. Future protocol implementations can support appropriate operations under this same group. This change does not add or promise lifecycle support for A2A, Activity, WebSocket, or voice, and does not invent semantics where no service contract exists.

Execution and waiting

--long-running means: continue service-side execution after this client disconnects. It is not a minimum-duration setting and does not promise crash recovery, checkpointing, or automatic reconnect.

For Responses, it sends store=true and background=true. The API field is still called background; only the CLI flag is renamed.

--no-wait requires --long-running. It reads through the first complete SSE event that identifies the Response, saves the current ID when local state is available, prints the ID, and detaches without waiting for completion. A save failure is surfaced rather than silently claiming the current ID was saved.

Without --no-wait, remain attached until completion or disconnection. After disconnection, users can run invocations follow again. Never retry the creating POST automatically.

For now, --long-running is remote Responses-only and rejects an explicitly supplied total --timeout or --output raw. Ordinary foreground/raw and existing Invocations create/poll behavior remain unchanged.

Service behavior and steering

Responses

• POST /responses creates a Response from supplied input.
• background controls whether service-side work continues after disconnection.
• Reusing conversation.id preserves history. If work is active and the agent supports steering, another Response can steer it. Otherwise concurrency behavior belongs to the service and agent.
• Repeated steering inputs are valid; later input supersedes earlier input.
• Steering works across foreground and background execution modes.
• GET /responses/{id} returns a snapshot.
• GET /responses/{id}?stream=true replays buffered events and follows new events. The tested service requires creation with background=true for replay/follow, including completed Responses. Foreground snapshots can still be shown.
• POST /responses/{id}/cancel requests cancellation without stopping the hosted session.

Invocations

• POST /invocations creates an Invocation.
• GET /invocations/{id} retrieves it.
• POST /invocations/{id}/cancel requests cancellation, subject to agent support.

azd does not block a new invoke because another Response is active, and performs no previous-Response status preflight. Existing session/conversation reuse remains unchanged. There is no separate --steer, --resume, --continue, or invoke-level --cancel operation.

Current selection

Keep one current service-assigned ID per agent context and protocol. Responses and Invocation IDs remain in separate internal maps even though the public command group is shared.

• An identified foreground or long-running Responses create replaces the current Response ID.
• An identified successful remote Invocations create replaces the current Invocation ID.
• A create that fails before providing an ID leaves the previous current selection unchanged.
• Normal attached execution may continue with a warning if current-ID persistence fails. Foreground raw output does not guarantee ID extraction.
• Explicit show/follow/cancel never changes current selection.
• Concurrent creates may overwrite current selection; use explicit IDs to manage concurrent work.

Only IDs are saved as lifecycle state—no status, event sequence, session, or conversation metadata. Existing session/conversation stores remain independent create-time context. No backward-compatibility migration is required.

Show, follow, and cancel

Show: perform one GET. Return JSON by default, with --output table for a summary following sessions show. Do not poll or use cached status.

Follow: for Responses, perform one GET /responses/{id}?stream=true and replay from the beginning every time. Do not send starting_after, track event cursors, suppress events by sequence, reconnect automatically, or silently fall back to show. A disconnect reports the ID and follow guidance. Completed work replays and exits successfully; failed/incomplete/cancelled outcomes retain their existing error behavior.

Cancel: POST to the selected protocol's cancel endpoint. If a rejected cancel is followed by a GET confirming terminal service state, report that state and succeed. Otherwise retain the cancel failure. Do not clear current selection or stop/delete the session.

Delivery

• feat(ai): add unified invocation lifecycle commands #9900: shared invocations show|follow|cancel commands with Responses support, --long-running, and simplification of the merged feat(ai): add attached resumable Responses invoke #9703 implementation.
• feat(ai): add Invocations protocol lifecycle support #9901: Invocations-protocol show/cancel and current-ID storage in the shared dispatcher, without changing existing create/poll behavior.

The superseded #9704–#9706 stack remains closed. No event cursor, periodic persistence, automatic reconnect, active-response guard, or dedicated steering command is retained.

[ankitbko]

1. How does it work for Invocation?
2. I am assuming --continue flag is making a GET call with the response ID. Should we make it explicit GET command, there is also a DELETE path also BTW

[m5i-work]

1. How does it work for Invocation?

The proposal is Responses only. None of the new long-running flags are allowed for Invocations. Existing vanilla azd ai agent invoke has no behavior change for Invocations.

2. I am assuming --continue flag is making a GET call with the response ID. Should we make it explicit GET command, there is also a DELETE path also BTW

Right, it's a GET. The extension follows a single-context model, it only tracks last session/conversation/response etc. So a flag under invoke command might be simpler now. Explicit responses get/follow/delete commands are a reasonable future direction when explicit targeting or multiple saved responses are added.

[ankitbko]

Wei Meng (@m5i-work) But invocation can also be long running. What is reconnect behavior there?

[trangevi]

How does this scope in the context of sessions and conversations? You mentioned "the extension follows a single-context model", but that's just in terms of default behavior, a user can always specify explicit session/conversation IDs, so if we don't have a corresponding response ID, what happens if a user attempts to use something like --continue but they specify a different session/conversation (whatever makes sense from a scope perspective)? Or the other way around, they invoked against a specific session/conversation, and then do a --continue invoke without providing the same ID?

Basically, what does the support matrix look like for these different scopes of invoking an agent? And how do we clearly explain that matrix to users?

[m5i-work]

Travis Angevine (@trangevi) Today, azd remembers one selected session and conversation per agent. Selecting another is possible but then azd simply forgets about the old one.

This MVP extends that single-context model with at most one current background response. --continue and --cancel use its saved session/conversation. Switching context while it is active is rejected. The idea is to deliver a simple UX enough for developers while avoiding too much refactoring. As noted in "Future optimizations", we can turn to a multi-context model via --response-id + multiple saved responses.

Single-background should be a straightforward model for existing users. Also, the CLI will show error and explain the valid next action when it rejects a command:

• invoke --continue or invoke --cancel with a session/conversation override: reject it because those operations use the context saved with the current response; tell the user to remove the override.
• A normal or background invoke that switches context while the current response is active: reject it and offer three paths—follow with invoke --continue, steer with invoke "" --continue, or stop it with invoke --cancel.

Updated spec to make the support matric clear and explicit.

[m5i-work]

Wei Meng (@m5i-work) But invocation can also be long running. What is reconnect behavior there?

Background/reconnect/steering require an established service contract but the invocations protocol is opaque. The best-effort MVP we can deliver is an azd ai agent invoke --continue that blindly GET with the previous invocation id. But it can fail in many ways due to undefined behaviors like:

• The agent doesn't run in background. Detaching from it simply terminates execution
• The agent doesn't support GET /invocation/{id}
• The agent doesn't support stream replay after reconnect

Ankit Sinha (@ankitbko) What do you think?