What is being compared—and why it matters
Microsoft Foundry Prompt Agents and Hosted Agents are two different ways to define an agent, not two labels for the same deployment package. A Prompt Agent uses declarative prompts and tools; a Hosted Agent packages custom code as a container. Those distinctions are the verified starting point for this comparison, not a claim that one option is universally more capable or safer. Microsoft’s Hosted Agents documentation describes the difference at that level.
The practical decision is about where your team wants to express behavior and where it is prepared to take responsibility. With a Prompt Agent, the central design work is defining instructions, selecting tools and governing how changes to those parts are reviewed. With a Hosted Agent, the team also owns the custom code and the processes around packaging, releasing and supporting it. These are differences in engineering responsibility; they do not, by themselves, establish the overall cost, reliability or security of either option.
This comparison focuses on current supported capabilities and the division of work. It does not attempt to restate how Foundry fits against other enterprise agent platforms, how to separate an agent’s runtime from its tools and data, or how to implement private networking and identity. For the broader platform choice, see the comparison of Microsoft Foundry, Bedrock AgentCore and Gemini Enterprise. Separate architecture reviews should resolve runtime, networking and identity requirements.
A useful first test is concrete: can the intended behavior be expressed through instructions and available tools, or does the application require custom code to implement important logic? If the answer is unclear, describe one representative task and trace its decisions before choosing a deployment model. That keeps the choice tied to actual requirements rather than to a preference for either configuration or code.
At-a-glance comparison
| Decision area | Prompt Agent | Hosted Agent |
|---|---|---|
| Definition | Declarative prompts and tools | Custom code packaged as a container |
| Main design emphasis | Instructions, tool selection and their governance | Application behavior in code, plus packaging and release ownership |
| A useful fit to investigate | A task whose behavior can be clearly expressed with prompts and governed tools | A task that requires explicit custom logic in the agent implementation |
| Main operational question | How are prompt and tool changes reviewed and controlled? | How are code changes, container releases and runtime responsibilities handled? |
| Shared concern | Tool permissions, identity, network paths and business outcome verification still need owners | Tool permissions, identity, network paths and business outcome verification still need owners |
The fit descriptions in the table are decision guidance, not additional claims about platform limits. A Prompt Agent may still need substantial engineering discipline, and adopting a Hosted Agent does not automatically make complex behavior correct or easier to operate. The right comparison is between the actual behavior you need and the team’s capacity to own its implementation.
A second distinction is important for tool design. Foundry’s Toolbox exposes curated tools through an MCP-compatible endpoint; versions and permissions require governance. The Toolbox overview supports those specific points. It does not remove the need to decide which tool is appropriate, who may invoke it, how changes are approved, or how a business action is confirmed. Do not treat an endpoint’s availability as evidence that every agent or application is automatically connected to it.
Behavior and change: declarative definition versus custom code
A declarative definition puts the team’s attention on what the agent is instructed to do and which tools it may use. That can make the design review easier to focus: reviewers can examine task instructions, boundaries, expected tool use and examples of acceptable results. The approach is a strong candidate when the core decision process can be stated clearly and the available tools already represent the actions the agent needs.
“Declarative” does not mean “no engineering.” Instructions can become difficult to maintain if different teams change them without a common review process, if the task boundary is vague, or if a prompt quietly accumulates unrelated responsibilities. A production owner still needs to record the intended behavior, approve material changes, evaluate representative cases and decide how to respond when the result is ambiguous. The maintenance burden is different from code maintenance, but it is still a burden.
With a Hosted Agent, custom code is the package boundary. That gives the team a place to implement explicit application logic when prompts and available tools do not adequately represent the required behavior. It also means code review, dependency choices, container construction and release procedures become part of the agent’s operating model. The source describes container packaging; it does not establish a specific language, build system or release service, so those choices should be validated against the team’s environment rather than assumed.
The code option can be a poor fit when a team adopts it only because it feels more familiar than prompt design. Familiarity with code does not eliminate the need to define behavioral expectations, review tool access, or verify what happened after an agent proposes an action. Equally, a Prompt Agent can be a poor fit when a task depends on custom application logic that is awkward to express through instructions and tools. Selecting the least complex adequate model is more useful than treating either model as a statement about engineering maturity.
Change control should follow the artifact that actually changes. For a prompt-led design, version and review prompt content and tool configuration as operationally significant changes. For a code-led design, review the custom implementation and the container release process. In either case, document the intended task, the accepted tool set, the owner who approves changes and the evidence required before a release reaches users. This is a proposed governance practice, not a built-in Foundry feature claim.
Tooling and the boundary between an agent and an action
Tools matter because an agent’s text is not the same thing as an action taken in a business system. A tool can represent a controlled way to request information or perform a defined operation. The design question is not simply whether an agent can see a tool; it is whether the tool’s purpose, permissions, input and resulting business effect are clear enough for the team to govern.
Foundry Toolbox provides a curated-tool pattern through an MCP-compatible endpoint, according to Microsoft’s overview. The documentation also makes versioning and permissions governance relevant. That should lead teams to assign an owner for the curated set, track which version is approved and review who can invoke each capability. Avoid presenting a broad collection of powerful operations as a neutral convenience: each additional tool expands the set of behaviors that must be understood and monitored.
A Prompt Agent’s declarative model does not make tool governance optional. Nor does container packaging make Hosted Agent tool access automatically safer. The decision about how a particular agent reaches a tool, what credentials or permissions are involved, and how network paths are arranged must be verified for the selected implementation. The agent model alone does not answer those questions.
For actions with consequences, place explicit controls around execution. Require approval before a consequential operation; bind that approval to the exact proposed payload, and make the approval expire. Then verify the resulting business state independently rather than treating the model’s statement that it completed the task as proof. These are design recommendations for accountable workflows, not claims that Foundry supplies a particular approval or verification mechanism. Do not promise exactly-once external effects: retries, timeouts and uncertain outcomes require a deliberate recovery design.
The useful comparison is therefore not “which option has tools?” but “where is tool policy defined, reviewed and enforced in this implementation?” Record the tool owner, the relevant version, the permission boundary, the approval point and the method for confirming the outcome. If the answers are missing, resolve that design gap before increasing the agent’s authority.
Operations and responsibility: what moves, and what does not
The two models shift engineering effort; they do not remove operational ownership. A Prompt Agent makes prompt and tool definition central to its design. The team must keep those definitions understandable, review updates and decide how to evaluate whether behavior still matches the intended task. A Hosted Agent adds custom code and container packaging to the work the team must own. It consequently needs a clear owner for code changes, artifact creation, release decisions and the way operational issues are investigated.
Do not infer from the word “Hosted” that every responsibility for the application has moved to Microsoft, or infer from “Prompt” that the model needs no operational care. Confirm operational details for the specific Foundry configuration and deployment your organization intends to use. Record the applicable availability, quota and regional requirements in the deployment decision.
A practical responsibility split names a business owner and a technical owner. The business owner defines what counts as a correct, acceptable outcome and which actions require human review. The technical owner maintains the selected agent definition, tool boundaries and release controls. Security, identity and network owners review the access paths and permissions relevant to the design. These responsibilities can sit with a small team, but they should not be left implicit.
For Azure implementations, keep the agent choice separate from the surrounding architecture decision. An illustrative target-state view is below. It is a planning diagram, not a statement that every depicted connection is automatically supported or preconfigured. Validate the chosen agent’s actual integration, authentication and network requirements before implementation.
flowchart TD
accTitle: Illustrative Azure agent deployment view
accDescr: A user reaches an Azure application, which selects a Foundry agent pattern. The application and agent design must validate a governed route to curated tools and enterprise systems.
A["User or operator"] --> B["Azure application boundary"]
B --> C["Microsoft Foundry project"]
C --> D["Prompt Agent"]
C --> E["Hosted Agent container"]
D --> F["Validated tool route"]
E --> F
F --> G["Curated tools and business systems"]The diagram deliberately places a validation boundary between either agent choice and business systems. It represents a proposed design principle: document the route and verify compatibility, identity, permissions and network behavior for the actual configuration. It does not assert that every Foundry agent can use every Toolbox endpoint, that the same authentication mechanism applies to both patterns, or that a network path exists without additional work.
Private connectivity is also not an inbound-only question. The route from an application to Foundry and the route from an agent or associated component to a tool or business system have different owners and constraints. The detailed network design belongs in the guide to inbound and outbound private networking for Foundry agents, rather than being inferred from the Prompt-versus-Hosted choice.
Identity needs its own decision record as well. Identify which actor is making each request, what permission it needs and where that permission is checked. Do not assume that the identity of a user, the application and an agent’s access to a tool are interchangeable. For the distinct question of who may do what, use the Entra identity guide for AI agents. This comparison flags ownership; it does not prescribe a complete identity architecture.
Teams that need to establish these boundaries across applications can use enterprise platform engineering as a next step for shaping a repeatable platform approach. The decision still belongs to the organization operating the agent: the goal is to make the choices and ownership explicit, not to outsource accountability for the resulting behavior.
Pros and cons of Prompt Agents
Potential advantages. A Prompt Agent’s declarative prompts-and-tools definition can keep a straightforward task focused on its instructions and permitted actions, rather than introducing a custom container where one is not needed. It offers a natural option to evaluate when the behavior can be explained clearly and the required actions are represented by tools the team can govern. It can also help reviewers concentrate on the behavior contract rather than a larger custom implementation.
Potential disadvantages. A declarative definition can become a weak substitute for explicit logic if the task depends on rules that are difficult to express and review in instructions. Prompt changes can still alter operational behavior, so an informal edit process is not an adequate release strategy. Tool permissions, network paths, identity and outcome verification remain design responsibilities; choosing a Prompt Agent does not settle them.
A Prompt Agent is not automatically the “simple” choice. If the task’s instructions are long, the tool set is poorly bounded, or changes are made without evaluation, the apparent simplicity of the definition may conceal a difficult operational problem. Conversely, where the task is tightly scoped and its behavior is easy to describe, adding a custom code package may create work without resolving a real requirement.
Pros and cons of Hosted Agents
Potential advantages. A Hosted Agent is the option to examine when the required behavior depends on custom code. Packaging that code as a container gives the team a concrete application artifact around which to organize review and release processes. It provides an implementation location for logic that should not be left implicit in a prompt or delegated to an unsuitable tool boundary.
Potential disadvantages. The team takes on additional implementation and packaging work, and must maintain an accountable process for code, container changes and operational investigation. The fact that code is present does not guarantee that the behavior is correct, that the container is safely operated, or that tool calls have appropriate permissions. A code-first choice can also add complexity if the behavior did not require custom logic in the first place.
Hosted Agents are not a shortcut around product and governance decisions. Teams still need to establish what the agent is allowed to do, what evidence is needed to accept a result and what happens after an uncertain action. The container is one part of the deployment model, not a replacement for the operating model around it.
Hypothetical worked scenario: an internal service-request assistant
Consider a hypothetical mid-market company that wants an assistant to help employees prepare internal service requests. It should gather required information, identify missing fields, and, when authorized, pass a request to an approved business system. This is an illustrative scenario, not a PADISO project or a claim about a tested deployment. It helps expose the decision without assuming particular Foundry integrations.
Start by writing down the smallest useful task: collect the request details, check whether required information is present, explain any missing information and prepare a proposed submission. Then distinguish preparation from execution. An agent that drafts a request has a different consequence from one that submits it, so the organization should define the approval point and the evidence that confirms the request exists in the business system.
For the first implementation review, ask whether prompts and governed tools are sufficient to express that behavior. If the task is limited to gathering information, applying a clear request template and presenting a proposed action for review, a Prompt Agent is a reasonable candidate to assess. That is a recommendation from the task shape, not a guarantee that the design is supported end to end. Confirm the actual tool route and permissions before committing to the pattern.
Now add a hypothetical requirement: before submission, the system must apply custom application logic that evaluates a set of conditions not represented by the available tools. If the team cannot express and govern those rules satisfactorily through the declarative definition and tool boundary, a Hosted Agent becomes a candidate because its defining distinction is custom code packaged as a container. The team must then plan how that code and container are reviewed and released, and how the resulting behavior is checked.
For either candidate, make tool ownership explicit. If a curated tool is delivered through Foundry Toolbox, record the approved version and permissions, and verify the actual path from the selected agent design. Toolbox’s MCP-compatible endpoint is evidence about the endpoint format, not a substitute for that compatibility check. If an existing business-system operation is involved, the organization must separately establish the exact permission and confirmation behavior for that operation.
An illustrative approval sequence could require a human to review the exact request payload, approve that payload before submission, and have the approval expire rather than remain reusable indefinitely. After an attempted submission, the application should check the authoritative business record or provide a clear “outcome unknown” state for investigation. It should not claim success merely because the agent produced a confident completion message. These are proposed controls; implementation details depend on the actual systems and interfaces.
Suppose the submission request times out. The team should not blindly repeat an external action and assume the first attempt failed. It should determine whether the operation completed, whether a safe reconciliation method exists, and what information an operator needs to resolve uncertainty. This is why exactly-once behavior should not be promised as a property of the agent model. The failure-handling design is a separate requirement for either option.
The worked scenario shows the decision’s useful boundary. Choose Prompt when the task can be defined through prompts and properly governed tools; investigate Hosted when custom code is genuinely required and the team is prepared to own its lifecycle. If the business cannot yet describe the task, permissions or success evidence, defer the deployment-model decision and clarify those conditions first.
Failure analysis: where each choice can disappoint
A Prompt Agent can fail operationally through unclear instructions, uncontrolled edits or a tool set whose permissions exceed the task. A team may mistakenly attribute every unexpected result to the model when the real cause is an ambiguous task definition, an inappropriate tool or a missing review step. Record enough context to distinguish those possibilities, and ensure a named owner can revise the definition through an approved process.
A Hosted Agent can fail through defects in custom logic, packaging or release handling. Adding code creates more implementation work to review, but does not make the result inherently more predictable. The team needs a way to connect an observed business failure to the relevant application version, tool interaction and release decision, within the operational facilities actually available in its chosen environment. Do not assume a particular logging or tracing feature unless it has been verified for that configuration.
Both models can fail at the tool boundary. A tool may be misconfigured, unavailable, over-permissioned or changed without the agent owner knowing. A request may be rejected, may time out after an external effect, or may return information that does not prove the intended business result. Version governance and permissions are specifically relevant to Toolbox; the broader operational safeguards in this paragraph are design recommendations, not claims about automatic platform behavior.
Both models can also fail at the handoff between people and automation. An approval that is too broad can authorize a different action from the one the reviewer considered; an approval that never expires can outlive its context. A result message that is not checked against business state can mislead the operator. Bind approvals to exact actions, expire them and verify outcomes through an appropriate authoritative source.
A useful incident review asks which layer produced the failure: task definition, custom implementation, tool version, access permission, network route, external system or human approval. It should also identify who can make the next safe decision. This classification avoids a reflexive rewrite of prompts or code when the cause lies elsewhere, and it helps keep remediation within the team that owns the relevant boundary.
Decision artifact: responsibility matrix and printable worksheet
Use the matrix as a starting point for an Azure design review. “Owner” means the role accountable for defining and confirming the decision, not a statement that the role must perform every technical task. Adapt the roles to your organization. The exact authentication and connectivity mechanisms are implementation-specific and are intentionally left for validation.
| Concern | Prompt Agent owner | Hosted Agent owner | Azure platform / security owner | Evidence to record |
|---|---|---|---|---|
| Task and acceptable result | Define intended instructions and result boundary | Define intended application behavior and result boundary | Confirm the design fits organizational platform controls | Task statement and acceptance criteria |
| Agent artifact | Maintain prompt and tool definition changes | Maintain custom code and container release changes | Confirm relevant deployment process for the selected configuration | Reviewed change and approved version |
| Tool selection | Confirm the required tools and their intended use | Confirm code’s tool interactions and intended use | Review tool permission and access boundaries | Tool owner, approved version and permissions |
| Identity | Specify which user or application actions require authorization | Specify which application actions require authorization | Validate the applicable identity and permission design | Actor, required permission and enforcement point |
| Network path | Identify required access to Foundry and tools | Identify required access to Foundry and tools | Validate ingress and egress paths for the actual deployment | Approved path and responsible network owner |
| Consequential action | Define review before an action is executed | Define review before an action is executed | Confirm control points in the implementation | Exact approved payload and expiry rule |
| Outcome verification | Define how the business result is confirmed | Define how the business result is confirmed | Confirm an authoritative verification source is available | Verification evidence and uncertain-outcome procedure |
| Incident response | Own prompt/tool-definition diagnosis | Own code/container diagnosis | Coordinate identity, network or platform investigation | Escalation owner and safe recovery action |
The shared columns are intentional: selecting Hosted does not transfer identity, network or business acceptance decisions to the container, and selecting Prompt does not make them disappear. The matrix also avoids treating a team name as sufficient evidence. A design review should be able to point to the person or function accountable for each decision and to the record that demonstrates it was made.
Printable decision worksheet
- Task boundary: We can describe the user’s task, the agent’s allowed work and what it must not do. Write the task in a sentence and list the conditions that require human review. If the boundary remains disputed, resolve it before choosing a model.
- Behavior fit: We have tested the design conceptually against representative cases and can explain whether prompts and tools are sufficient. If custom logic is needed, name the rule and explain why the prompt-and-tool definition is inadequate.
- Model selection: We selected Prompt Agent for a declarative task or Hosted Agent because custom code is required. Record the reason in terms of behavior, not personal preference or an unverified assumption about service characteristics.
- Artifact owner: A named team owns prompt and tool changes, or code and container changes, as appropriate. The owner can describe how changes are reviewed and approved before release.
- Tool governance: Each required tool has an owner, an approved version and a permission boundary. Where Toolbox is involved, the team has reviewed the relevant version and permissions and confirmed the actual integration path.
- Identity and networking: The design identifies actors, required permissions and network paths. The responsible owners have validated the intended configuration rather than relying on the agent model to imply access.
- Execution control: Consequential operations require approval before execution. Approval is bound to the exact payload and expires; the team has a safe response for a timeout or uncertain outcome.
- Business verification: The team can confirm the resulting business state independently of the model’s message. It knows who investigates when that evidence is absent or ambiguous.
- Operational handoff: An operator can identify the agent definition or release involved, contact the relevant owner and follow a documented recovery path without blindly repeating an external action.
For a short review meeting, print the worksheet and mark each item as complete, unresolved or not applicable. “Complete” should mean there is an owner and evidence, not merely that the topic came up in discussion. Any unresolved item should have a named person responsible for resolving it and a date or decision point before the agent is allowed to perform consequential work.
Verdict: choose by implementation need and ownership
Choose a Prompt Agent when the required task can be represented clearly through declarative prompts and governed tools, and the team is ready to manage prompt and tool changes as production behavior. Its appeal is not that it removes engineering work, but that it may avoid introducing a custom code container when one is not needed. Validate the tool route, access controls and business verification just as carefully as for any agent design.
Choose a Hosted Agent when the requirement genuinely calls for custom code and the team is prepared to own that code and its container packaging and release process. Do not select it simply because code feels familiar, and do not assume that code resolves ambiguous requirements or external-system failure handling. The implementation still needs explicit task boundaries, tool permissions, approval controls and independent outcome verification.
If neither case is established, the right verdict is to delay the deployment choice. Write a representative task, identify the necessary tools, name the required permissions and define what evidence would prove a business action succeeded. Then compare the two models against those specifics. For a deeper view of how agent runtime, tools and data should be separated in an overall design, continue with the Foundry architecture treatment of those distinct components.