Choose where agent control belongs

Learning objective

Choose Microsoft Foundry prompt agents, hosted agents, and workflows according to hosting, extensibility, and control requirements.

Core idea

Choose an agent runtime by identifying what you must control. A prompt agent delegates the execution loop to Microsoft Foundry. A hosted agent puts your code inside a Foundry-managed runtime. A workflow defines the sequence and conditions under which work proceeds; it doesn’t have to be a separate hosting choice.

The blueprint lists Foundry workflows alongside prompt and hosted agents. Microsoft’s workflow documentation marks the visual workflow experience as preview and schedules the designer and in-portal execution for retirement on December 1, 2026. It directs workflow development to Microsoft Agent Framework, with code or declarative YAML deployed as a hosted agent. Preserve the distinction between orchestration structure and the runtime that executes it.

For an architect, the result of this choice is a responsibility boundary: who owns instructions, executable code, request protocols, state, and operational behavior. Selecting managed hosting doesn’t remove responsibility for the business logic you deploy.

How it works

Delegate the agent loop with a prompt agent

A prompt agent is a configuration-defined agent. You specify its instructions, model, and tools; Foundry runs the agent. You can author the definition in the portal or through SDKs and REST APIs. The programmatic surface isn’t evidence that you must host an application container.

In the Python SDK, PromptAgentDefinition names this definition, and project.agents.create_version creates an agent version. Tools are part of the definition. For example, AzureAISearchTool can connect the agent to an indexed knowledge source. This is extensibility through supported tools rather than ownership of the execution loop.

Choose a prompt agent when instructions, model selection, and supported tools meet the contract. You own those choices, resource permissions, and answer validation.

A requirement for arbitrary application code between every model call changes the choice. Adding more text to instructions doesn’t turn a managed prompt agent into an application-defined orchestrator. Put deterministic checks in a suitable tool or choose a hosted implementation when the whole loop must be under your control.

Bring executable logic with a hosted agent

A hosted agent runs your agent code on Microsoft-managed infrastructure. You can bring a container image or source code packaged as a ZIP that Foundry builds into an image. The platform manages endpoints, scaling, identity, session persistence, and lifecycle; your code handles requests and its own agent behavior.

Microsoft documents support for your own code and multiple frameworks, including Microsoft Agent Framework and LangGraph. Hosted Agents, the managed hosting service, is generally available. That status doesn’t make every integration package generally available: the Python agent-framework-foundry-hosting integration is prerelease. Separate the service support decision from the package version you adopt.

Hosted agents reach Foundry tools through a Toolbox MCP endpoint, rather than attaching tools directly to the agent definition. For Agent Framework, use FoundryToolbox in Python or AddFoundryToolboxes in .NET; other runtimes use standard MCP clients. See 1.2.2 for Toolbox curation.

The request protocol is an architectural choice. With Responses, Foundry manages conversation history and associates a session with the conversation. With Invocations, your agent accepts arbitrary JSON and you manage conversation history yourself. Invocations (WebSocket) provides bidirectional streaming over one persistent connection, such as a real-time voice agent. Choose the contract your consumers need rather than translating every workload into chat messages.

Hosted agents receive a dedicated Microsoft Entra agent identity and endpoint at deployment. The project’s managed identity serves platform infrastructure operations; it isn’t the agent container’s runtime identity. Assign downstream access to the identity that actually performs the operation; see 1.2.3.

Managed compute also has a state boundary. Hosted sessions persist $HOME and /files across idle eviction, but your design still needs explicit application state and memory choices. See 1.2.5 for conversations, checkpoints, and semantic memory. A process-local variable isn’t a durable coordination record merely because the platform hosts the process.

Make workflow control explicit

The visual Foundry workflow experience describes predefined sequences, branches, variable handling, and human interaction. Its templates include sequential, group chat, and human-in-the-loop patterns. These describe control flow rather than a promise that each agent inside the flow is deterministic.

For an existing visual workflow, export the YAML definition before the retirement boundary. Microsoft identifies three migration paths: Microsoft Agent Framework for code or YAML orchestration, Azure Logic Apps when a visual business-process designer is the requirement, and A2A for lightweight direct agent handoffs. The workflow documentation says Foundry continues to run YAML-based definitions when deployed as hosted agents after the visual experience retires.

For a new solution, select Microsoft Agent Framework when explicit orchestration is required, then choose its hosting boundary. Don’t choose the retiring portal designer as the foundation of a long-lived system. A workflow requiring an approval gate must encode that gate in executable control flow; a prompt asking an agent to seek approval doesn’t establish the same boundary.

Key distinctions and trade-offs

The following choices divide responsibility:

Prompt agents reduce the code you operate. Hosted agents broaden extensibility while adding code and dependency maintenance. Workflows make the allowed progression visible, but don’t replace validation of the outputs that move through it. A hosted workflow combines managed infrastructure with application-owned control.

Avoid inferring feature status from neighboring features. A generally available hosted runtime can execute code that uses preview memory or a prerelease framework integration. Record those choices independently in the architecture.

Architecture / decision scenario

A claims platform needs three capabilities: answer policy questions, calculate a settlement with proprietary rules, and require human approval before payment.

Use a prompt agent for policy questions when instructions and an Azure AI Search tool meet the contract. Use a hosted agent for the proprietary calculation because the team must execute and version its own code. Select Responses for conversational consumers, or Invocations when the calculation accepts a structured claim and returns structured results without needing platform-managed chat history.

Express the approval sequence as an Agent Framework workflow. Deploy that workflow as a hosted agent if Foundry should manage its runtime. The approval outcome controls whether the payment operation becomes reachable; neither the question-answering agent nor the calculator can bypass that sequence by producing persuasive text.

If the team already has a portal workflow, export its YAML and validate the migration against the December 1, 2026 retirement boundary. If maintaining a visual business-process canvas is mandatory, evaluate the documented Logic Apps path instead. This decision exercises hosting, extensibility, and control separately rather than expecting one agent type to satisfy every requirement.

Common exam traps

• Treating SDK authoring of a prompt agent as self-hosted execution.
• Assuming a hosted agent means you operate the underlying scaling infrastructure.
• Equating a workflow with a third permanent Foundry hosting type.
• Recommending the preview visual workflow designer without its retirement boundary.
• Applying the hosted service’s GA status to a prerelease integration package.
• Assuming Invocations provides the conversation history managed by Responses.

What to remember

Use prompt agents for configuration-defined behavior and hosted agents for application-defined code. Use workflows to establish explicit control flow, then choose where they run. Account for the visual workflow retirement, and distinguish managed runtime guarantees from the responsibilities and feature statuses inside your implementation.

Knowledge check

References

• Microsoft, What is Microsoft Foundry Agent Service?
• Microsoft, Hosted agents in Foundry Agent Service
• Microsoft, Foundry Hosted Agents
• Microsoft, Build a workflow in Microsoft Foundry (Preview)
• Microsoft, Connect an Azure AI Search index to Foundry agents