Setting the file. One moment.
Chapter 36 · Microsoft Foundry
Subchapter 36.63
foundry-agent/invoke/invoke.mdMarkdown6 KBView on GitHub
Invoke Prompt Agents with Foundry MCP. Invoke Hosted Agents and manage their sessions, files, and logs with azd.
| Agent type | Protocol | Invoke path | State management |
|---|---|---|---|
| Prompt | — | Foundry MCP agent_invoke | conversationId; no hosted session or file operations |
| Hosted | responses | azd ai agent invoke | azd sessions, files, conversations, and monitor commands |
| Hosted | invocations | azd ai agent invoke --protocol invocations | azd sessions, files, conversations, and monitor commands |
| Hosted | activity | Microsoft 365 channel, such as Teams | Activity conversation and channel state |
| Hosted | invocations_ws | WebSocket client; follow invocations-ws | Agent-managed state keyed by agent_session_id |
Treat an azure.yaml service with host: azure.ai.agent as Hosted. If the type is still unknown, use agent_get only to classify the agent. Do not use MCP invoke, session, or file tools for a Hosted Agent.
Inside an azd project, run:
azd ai agent show --output jsonVerify that the deployed version is active. When multiple agent services exist, use the service name in subsequent commands.
When invoking outside an azd project with a known protocol endpoint, skip this step.
Single-agent project:
azd ai agent invoke "hello, are you up?"Multi-agent project:
azd ai agent invoke my-agent "hello, are you up?"Protocol examples:
azd ai agent invoke --protocol invocations --input-file request.jsonFor invocations, inspect the agent source or OpenAPI contract before preparing the request body. See Invocations Protocol Guide for request schema discovery and examples.
Outside an azd project, use a full protocol endpoint supplied by the user or previously returned by azd ai agent show:
azd ai agent invoke --agent-endpoint "<full-agent-protocol-endpoint>" "Hello!"Invoke supports default and raw output. Do not pass --output json.
Remote invocation can incur model usage charges. Run it only when it is within the user’s request.
azd ai agent invoke does not support the Activity protocol. For local invocation, use azd ai agent run and Microsoft 365 Agents Playground. For a deployed service, follow its generated TEAMS_APP_SETUP.md and invoke through Teams or the configured channel.
If Activity coexists with Responses or Invocations, pass --protocol responses or --protocol invocations explicitly to test that non-Activity protocol. A successful CLI response does not validate the Activity protocol path.
A normal remote invoke does not require a separate session create command. azd reuses the saved session for that agent. If none exists, the server assigns one and azd persists the returned session ID for later invoke, file, and monitor commands.
| Intent | Option |
|---|---|
| Reuse the current session | No session flag |
| Select and persist a known session | --session-id <id> |
| Start fresh session-backed state | --new-session |
| Target a deployed version | --version <version> |
For the responses protocol, azd creates a platform-managed conversation and can persist its conversationId for reuse. Use --new-conversation to reset response history or --conversation-id <id> to select one. For invocations, memory is session-backed, so --new-conversation has no effect.
Use explicit session commands only when a session must exist before invoke or file operations, or when inspecting and controlling its lifecycle. Read Session Management.
File commands use the session saved by invoke or explicit session creation unless --session-id overrides it. Read File Operations.
Use the same saved session for logs:
azd ai agent monitor
azd ai agent monitor --session-id <id> --followUse stop when the filesystem must remain available:
azd ai agent sessions stop <session-id>A later invocation can resume the stopped session. Use delete only for permanent cleanup:
azd ai agent sessions delete <session-id>Delete removes both compute and persistent filesystem state.
agent_get to verify the Prompt Agent.agent_invoke(projectEndpoint, agentName, inputText).conversationId for later turns.Prompt Agents do not use hosted sessions or hosted file operations.
| Error | Resolution |
|---|---|
| Agent service cannot be resolved | Use the azure.yaml service name, correct the service block, or use --agent-endpoint outside the project |
| Hosted version is not active | Inspect azd ai agent show --output json and deployment logs |
| Session is missing or expired | Run azd ai agent sessions list, then use a valid ID or invoke with --new-session |
| Conversation is missing after a session was deleted | For the responses protocol, retry with --new-session --new-conversation |
session_not_ready or 424 FailedDependency | Inspect azd ai agent monitor, wait for readiness, and retry the same azd invoke |
| Invocations schema mismatch | Inspect the handler or OpenAPI contract and correct the input file |
| File operation fails | Run azd ai agent sessions show <id> and verify the path with azd ai agent files list or stat |
| Header-based isolation fails | Pass the same --user-identity on invoke, session, file, and monitor commands |
| Permission error | Follow troubleshoot |