Catalogue › Microsoft Foundry › foundry-agent-architecture

Foundry agent architecture

Architects a single agent, or a small set of cooperating agents, on Foundry Agent Service - its responsibilities, instructions, model, tools, knowledge, state, identity and the surfaces it is published to - so it can be built, secured and operated. Use when a Foundry agent has been approved, when an agent prototype needs a production design, or when a Copilot Studio agent is being rebuilt in Foundry.

Department

Microsoft Foundry

Lifecycle

Mobilise, Deliver

Maturity

builder, scaler, ai-enterprise

Risk tiers

1, 2, 3, 4

Platforms

ai-foundry, azure, entra, m365-agents

Editions

starter, scale, enterprise

Reviewers

design-authority, security-privacy, responsible-ai

Status

draft

Copilot Cowork

Microsoft Foundry plugin for Copilot Cowork, or this skill on its own: Download SKILL.md

Licence

CC BY 4.0, by Simon Foote

Purpose

An agent on Foundry Agent Service combines a model, instructions, tools, knowledge and conversation state behind an identity, and every one of those is a design decision with security, cost and quality consequences. This skill produces the agent's architecture: what it is responsible for, what it may do, how it holds state, which identity it acts with and where it is surfaced. Agent designs go wrong when one agent is given every tool "in case", when its identity has far more access than its users, and when the prototype's shortcuts become production by default.

When to use

• A Foundry agent has been approved by ai-foundry:foundry-solution-assessment and needs a design before build.
• A prototype agent works in a notebook or playground and needs a production architecture.
• An agent built in Copilot Studio or Agent Builder is being rebuilt, wholly or partly, on Foundry.
• An agent is being split into several cooperating agents, or several agents are being consolidated.

When not to use

• Designing a multi-step workflow where the autonomy, checkpoints and stop conditions are the main question - use ai-foundry:agentic-workflow-design.
• Designing the contract of an individual tool or function - use ai-foundry:foundry-tool-design.
• Connecting external MCP servers to the agent - use ai-foundry:mcp-integration.
• Designing an agent in Copilot Studio - use copilot-studio:studio-agent-design.
• Designing a declarative Microsoft 365 agent - use m365-agents:agent-use-case-design.

Questions to ask first

1. What is the agent responsible for, in one sentence, and what must it refuse or hand over?
2. Who are its users, and does it act with their identity, its own identity or both?
3. Which actions can it take that change something outside the conversation, and which need a person to approve them?
4. What must it remember within a conversation and across conversations, and for how long may that be kept?
5. Where will people reach it: inside an application, through an API, in Microsoft 365 or Teams, or as a step in another agent?

Required inputs

• The approved solution design on the foundry-solution-design template, with risk tier.
• The model selection record from ai-foundry:model-selection, or at least a shortlist.
• A list of candidate actions and knowledge sources with their owners.
• The organisation's Azure identity and network standards.

Where actions, owners or identity standards are missing, mark them [To confirm: ...] in the architecture and do not design around assumptions. An action with no owner is removed from scope until it has one.

Decision framework

Practitioner approach

Write the responsibility statement first and keep it narrow: who the agent serves, what outcome it helps with, and the boundary where it refuses or hands over. Every later decision is tested against this statement. If the team cannot agree it, the agent is really several agents or no agent.

Decide the shape. A single agent is simpler to evaluate, secure and support, so it is the default. Split into several agents only when parts genuinely need different permissions, models, owners or instructions that would conflict. When agents cooperate, name the coordinating agent, what each specialist may do, and how results and failures pass between them. If the cooperation is really a defined sequence with checkpoints, hand the flow to ai-foundry:agentic-workflow-design and keep this design to the agents themselves.

Design identity before tools. For each action, decide whether it runs as the signed-in user, so the user's permissions apply, or as a managed identity for the agent. User-delegated access is the safer default because it prevents the agent becoming a route around permissions. Where a managed identity is unavoidable, scope it to the minimum resources and operations, and record why. Bring ai-architecture:ai-identity-design in for anything non-trivial.

List the tools and knowledge the responsibility needs, and only those. For each tool record its owner, whether it reads or writes, and whether a person confirms before it runs. Detailed contracts go to ai-foundry:foundry-tool-design; external MCP servers to ai-foundry:mcp-integration; grounding choices to ai-foundry:foundry-grounding-strategy.

Decide state and memory deliberately. Conversation threads and any cross-session memory are personal data in many cases; set what is stored, where and for how long, and agree retention with the data owner and DPO.

Choose one launch surface. Each surface brings its own authentication, audience and transcript handling, so adding surfaces later is a change, not a configuration tweak. Finally, record the architecture in the agent section of the foundry-solution-design template with a simple diagram, and list what remains unknown until evaluation, such as whether the chosen model calls tools reliably enough.

Outputs

• The agent architecture section of the foundry-solution-design template: responsibility, agent shape, identity per action, tool and knowledge list with owners, state and retention, surfaces and diagram.
• A tool inventory handed to ai-foundry:foundry-tool-design.
• Open questions to resolve through evaluation.

Microsoft platform considerations

Foundry Agent Service manages agents, threads, tool calls and runs on the organisation's Azure resources, and its capabilities, tool types and connected surfaces are changing quickly. Check the current source records for which tools, knowledge connections and publishing channels are available before designing around them, and whether a capability is in preview. Where the agent is surfaced in Microsoft 365, the extensibility guidance governs how it appears and which identity flows apply.

Adoption considerations

Agents surfaced to people need a clear statement of what they do and do not do, visible in the surface itself. Plan launch communications with the business owner, and keep the first audience small enough to learn from.

Knowledge considerations

Each knowledge source needs an owner, a refresh route and an audience consistent with the agent's users. Grounding approach and retrieval design are separate decisions handled by ai-foundry:foundry-grounding-strategy.

Security and privacy considerations

The agent's identity, tool permissions, network exposure and stored threads are the main attack and leakage surfaces. Design for least privilege, user-delegated access where possible and prompt-injection resistance in tools that read untrusted content. security-privacy:ai-identity-and-access-review reviews the result from tier 2.

Responsible AI considerations

Any action that affects people, money, safety or rights needs a defined human checkpoint, designed with responsible-ai:human-oversight. Users must be able to tell they are dealing with AI and how to reach a person.

Evaluation requirements

Plan evaluation for task quality, tool-call correctness, refusal of out-of-scope requests and behaviour under prompt-injection attempts, with thresholds agreed before testing. Agent-level evaluation design goes to ai-foundry:model-evaluation and safety testing to ai-foundry:foundry-safety-evaluation.

Value measures

Carry the solution's value measure into the agent design: the task outcome it should improve, its baseline and the business owner. Report usage and outcomes for the agent at audience level, never by individual user.

Scale notes

Starter

Build one narrow agent with read-only tools first, user-delegated access and one surface. Add write actions only after it has run well.

Scale

Reuse agreed patterns for identity, state retention and tool registration across agents, so each new agent starts from a reviewed baseline.

Enterprise

Maintain an agent catalogue with owners, identities and tool permissions, and require architecture review for any agent that coordinates others or acts across business areas.

Hand-offs

• To ai-foundry:foundry-tool-design for each tool's contract.
• To ai-foundry:foundry-grounding-strategy for knowledge.
• To ai-foundry:foundry-prompt-engineering for instructions.
• To ai-foundry:foundry-deployment-architecture for environments and topology.
• To ai-foundry:foundry-observability so tracing is designed in from the start.

Reviewer gates

From risk tier 2, security-privacy reviews identity, tool permissions and state retention, responsible-ai reviews human checkpoints on consequential actions, and design-authority checks conformance to the reference architecture.

Failure modes

• The agent is given every available tool, and a prompt-injection in a document triggers an action nobody intended.
• A managed identity with broad access serves all users, so the agent returns content users could not open themselves.
• Conversation threads are kept indefinitely because nobody set retention, and become an unplanned store of personal data.
• The prototype's single shared key and open endpoint go into production unchanged.

Sources

references/sources.md in this skill lists the source records behind this skill, what each is authoritative for, how volatile it is and what you may do with it. Product availability, licensing, limits and preview status change often, so check the current source before stating them, and cite what you used.

Never

• Give an agent a tool without a named owner and a stated reason linked to its responsibility.
• Let an agent identity hold broader access than the users it serves without a recorded justification.
• Allow consequential write actions without a designed human checkpoint.
• Design around a preview capability without recording it as a risk and checking the current source.