Invoke a hosted agent with the Azure Developer CLI

Use azd ai agent invoke to send messages to your agent, either the deployed version in Microsoft Foundry or a locally running instance. You learn how to choose an agent, use direct endpoints, manage sessions, send files, pin versions, and inspect raw responses.

Prerequisites

Invoke the deployed agent

  • Send a prompt to the deployed agent:

    azd ai agent invoke "What is Microsoft Foundry?"

Invoke a specific agent

  • If your project contains multiple agents, specify which one to invoke:

    azd ai agent invoke my-agent "What is Microsoft Foundry?"

Invoke a specific deployed endpoint

When you want to invoke a specific deployed agent without depending on the active azd environment or azure.yaml, use --agent-endpoint to point directly at the deployed agent's URL. This pattern is useful from a script outside the project, from a coding agent, or when you test a specific agent version.

  • Pass the deployed agent endpoint:

    azd ai agent invoke \
   --agent-endpoint "https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/endpoint/protocols/openai/responses?api-version=v1" \
   "Summarize today's release notes."

    Copy the callable protocol endpoint from azd ai agent show or azd ai agent endpoint show. A version-management URL ending in /versions/3 isn't an invocation endpoint. --agent-endpoint bypasses azd environment and azure.yaml resolution.

Invoke locally

  • Invoke a local agent:

    azd ai agent invoke --local "Hello!"

    The agent must already be running with azd ai agent run in another terminal.

Invoke on a custom local port

  • If your agent is running on a non-default port, pass --port:

    azd ai agent invoke --local --port 9090 "Hello!"

Choose a protocol

When you omit --protocol, the CLI uses complete deployed endpoint data when available, then the agent definition. If it can't identify exactly one invocable protocol, pass --protocol explicitly. Redeploy to refresh endpoint data saved by older extensions.

  • responses -- sends a standard OpenAI Responses API request with {"input": "your message"}. Conversation history is managed automatically.
  • invocations -- sends whatever payload your agent code expects. Use --input-file (-f) with a JSON file matching the schema your handler defines.
  • a2a -- invokes a deployed Agent-to-Agent endpoint. Pass a message, or use --input-file with a complete JSON-RPC request. This protocol doesn't support --local.

For invocations agents, check the sample's README or inspect the handler entry point to understand the expected payload.

  • If your agent implements multiple protocols, pass --protocol (-p) to choose:

    azd ai agent invoke --protocol invocations -f request.json

Voice agent limitations

azd ai agent invoke doesn't implement voice conversations. When azure.yaml identifies the selected service as voice or prompt-voice, the command returns voice agents cannot be invoked with this command and directs you to the Foundry portal.

This restriction also applies to a voice wrapper that uses conversationEngine to reference a hosted target. Selecting --protocol responses doesn't bypass the voice-service check.

Use the playground to test a voice agent, as described in the voice agent quickstart.

Manage sessions

The CLI saves session and conversation selections locally per agent. A session preserves sandbox state, such as uploaded files. For the Responses protocol, a conversation preserves message history. Reusing a session alone doesn't provide conversation history for the Invocations protocol.

Start a new session

  • Discard the saved session and begin fresh:

    azd ai agent invoke --new-session "Start fresh"

Use a specific session ID

  • Pass an existing session ID:

    azd ai agent invoke --session-id my-session-123 "Continue conversation"

Choose conversation history separately

For the Responses protocol, start a new conversation with --new-conversation, or continue a known conversation with --conversation-id:

azd ai agent invoke --new-conversation "Start a new topic"
azd ai agent invoke --conversation-id <conversation-id> "Continue this topic"

--new-session also resets the saved conversation. For the distinction between conversation history and sandbox state, see Manage hosted agent sessions.

Send a file as input

For structured or large payloads, especially with the invocations protocol, pass a JSON file.

  1. Send a file:

    azd ai agent invoke -f request.json

  2. Or send a file to a specific agent:

    azd ai agent invoke my-agent -f request.json

Invoke a deployed version

When an agent has multiple deployed versions, pin a specific one with --version. azd creates or reuses a session backed by that version, so each version keeps its own conversation state.

  • Pin a version:

    azd ai agent invoke --version 3 "Use the v3 prompt"

    --version can't be combined with --local or --session-id because sessions are bound to a version when they're created.

Set a custom timeout

  • Pass a timeout in seconds:

    azd ai agent invoke --timeout 300 "Process this large dataset"

    The default timeout is 1800 seconds (30 minutes). Use --timeout 0 for no timeout.

Pass an end-user identity

Pass --user-identity to send a request on behalf of an end user. For remote requests, azd sends the value in the x-ms-user-identity header. The flag works with the Responses, Invocations, and A2A protocols.

The request still authenticates with the caller's Microsoft Entra credential. The header identifies the represented user; it doesn't replace authentication or grant the delegation permission listed in the prerequisites.

  • Send an end-user identity to the deployed agent:

    azd ai agent invoke my-agent \
   --user-identity "user-123" \
   "Hello!"

    Replace user-123 with a stable identifier for the authenticated end user. Include --user-identity on every invoke; the flag defaults to empty. Without it, Foundry uses the caller's own identity.

azd saves session and conversation IDs per agent, not per --user-identity value. Changing the identity doesn't select different saved state. When switching users with the Responses protocol, start a new session and conversation:

azd ai agent invoke my-agent --protocol responses \
  --user-identity "user-456" \
  --new-session --new-conversation \
  "Start a conversation for this user"

To resume a user's existing Responses state, pass that user's --session-id and --conversation-id with the same --user-identity. Don't reuse another user's conversation ID.

Use --user-identity, not --client-header, for x-ms-user-identity. The --client-header flag accepts only x-client-* names and rejects identity headers.

For identifier requirements and isolation behavior, see Isolate hosted agent sessions per user. Current versions of the agents extension don't accept the earlier --user-isolation-key, --chat-isolation-key, or --isolation-key flags.

Pass identity to a local agent

With --local, azd sends the same flag value as x-agent-user-id instead of x-ms-user-identity:

azd ai agent invoke my-agent --local \
  --user-identity "user-123" \
  "Hello!"

Use this header to test how your local agent handles user context. Local runs don't enforce Foundry's isolation or delegation permissions.

Send application-specific headers

Use repeatable --client-header "Name: Value" flags for request metadata, such as a correlation ID or tenant label:

azd ai agent invoke \
  --client-header "x-client-request-id: request-123" \
  --client-header "x-client-tenant: contoso" \
  "Hello!"

Only x-client-* header names are accepted. Responses and Invocations endpoints forward these headers to your agent. The A2A protocol doesn't support this flag. Use --user-identity, not --client-header, for delegated identity.

Run work after the client disconnects

For the Responses protocol, --long-running starts service-side background work. The command stays attached until completion unless you also pass --no-wait:

azd ai agent invoke --long-running --no-wait "Run the long task"

The command returns after it receives the service-assigned response ID. Inspect, follow, or request cancellation of that work:

azd ai agent invocations show --protocol responses
azd ai agent invocations follow --protocol responses
azd ai agent invocations cancel --protocol responses

These commands default to the latest saved ID for the selected agent and protocol. Pass --id <response-id> to target another response without changing that selection. Use --agent-name or --agent-endpoint to choose a target, and repeat --user-identity for delegated requests. A direct endpoint identifies the protocol; don't combine it with --protocol or --agent-name.

Responses supports show, follow, and cancel. Invocations supports show and cancel, but not follow. A2A doesn't support these lifecycle commands. The service can reject operations an individual agent doesn't implement.

Background execution doesn't enable crash recovery or automatic reconnection. Configure the agent's recovery behavior separately; see Recover long-running work after a crash.

Inspect platform latency

Remote hosted-agent Responses and Invocations requests collect platform latency diagnostics by default. When the service returns timing headers, the CLI displays a summary. Disable collection and the summary with --debug-latency=false.

Local, prompt-agent, and A2A invocations don't collect platform latency. Explicit --debug-latency=true is rejected for these routes. This setting is independent of the global --debug flag.

Inspect the raw HTTP response

When you need to see exactly what the server returned, including response headers like the agent version, status line, and the unmodified body, pass --output raw (-o raw).

  • Request raw output:

    azd ai agent invoke --output raw "Hello!"

    In raw mode, friendly summary lines like Session: and Invocation: are suppressed and the HTTP response is dumped verbatim. This mode is useful for debugging server behavior and confirming which agent version handled the call.

Related content

  • Last updated on