Foundry Agent Blueprint

Foundry Agent Blueprint

How to design an agent on Azure AI Foundry Agent Service and map the agentic decisions to Foundry primitives. This skill is the design layer; for hands-on provisioning, CLI, and SDK detail, load the installed microsoft-foundry, azure-ai, and vscode-microsoft-foundry skills, and verify against Microsoft Learn.

Service capabilities and names evolve. Confirm the current Foundry Agent Service features, model catalog entries, and limits on Microsoft Learn before locking a recommendation. Do not quote limits or prices without a source.

When to invoke

• "Design an agent on Azure AI Foundry Agent Service."
• "Map model, memory, tools, and guardrails to Foundry primitives."
• "Choose Foundry model catalog deployments and connections."
• "Plan Foundry tools such as OpenAPI, MCP, code interpreter, or file search."
• "Create a Foundry evaluation and tracing blueprint."

Criteria

Foundry primitives, mapped to the seven decisions

Blueprint steps

1. Project and models. Create a Foundry project. Pick models from the catalog for each routing tier (a small model for routing and extraction, a workhorse for general steps, a premium or frontier model for hard steps). Create deployments.
2. Connections. Add the connections the agent needs: Azure AI Search for retrieval, Azure Managed Redis for cache and memory, storage for files, and any other data source. Use managed identity on connections where supported.
   • Note from prior experience: a Foundry AzureStorageAccount connection target must be the Blob URI (https://<account>.blob.core.windows.net), not the ARM resource id.
3. Agent definition. Define the agent with its instructions, model, and tools. Keep the tool surface small and well described (see tools and MCP in agentic-architecture-patterns).
4. Threads. Use threads for short term memory. Add long term memory through a retrieval tool or connection, scoped by tenant and user.
5. Guardrails and identity. Give the agent an Entra Agent ID, use managed identity for service access, and enable Content Safety and Prompt Shields.
6. Evaluation. Build an eval set and run the Foundry evaluators (relevance, groundedness, coherence, safety, task success). Gate changes in CI.
7. Observability. Enable tracing and route telemetry to App Insights with OpenTelemetry GenAI conventions.

Tools available in Foundry agents

• Function tools for your own code.
• OpenAPI tools to call governed HTTP APIs (register them in azure-api-center, front them with apim-ai-gateway).
• MCP tools to attach Model Context Protocol servers (build them with mcp-builder).
• File search for grounded retrieval over uploaded documents.
• Code interpreter for computation and data tasks.

Provisioning and quotas

• For provisioning steps, identity setup, and SDK usage, route to microsoft-foundry and azure-ai.
• For model and Cognitive Services quota, the az quota list path can return a bad request; raise a support quota request for Cognitive Services instead. New subscriptions may need Microsoft.ContainerRegistry registered before creating an ACR for hosted-agent demos.

References

• Azure AI Foundry Agent Service
• Azure AI Foundry model catalog
• Foundry tools
• Evaluate generative AI with Azure AI Foundry

Output template

Return exactly this structure:

Foundry Agent Blueprint

**Status:** PASS | FAIL | BLOCKED
**Summary:** One sentence describing the recommended Foundry agent design.

### Details
- Agent purpose: target runtime and task scope
- Models and routing: catalog deployments, tiers, and rationale
- Connections: Azure AI Search, Azure Managed Redis, storage, Bing, or other data sources
- Tools: function, OpenAPI, MCP, file search, code interpreter, and governance notes
- Memory and context: threads, runs, retrieval, tenant and user scoping
- Guardrails and identity: Entra Agent ID, managed identity, Content Safety, Prompt Shields
- Evaluation and observability: eval set, evaluators, tracing, App Insights, OpenTelemetry

### Validation
- Decision coverage: PASS | FAIL with evidence for the seven decisions
- Currentness check: PASS | FAIL | SKIPPED with Microsoft Learn verification status
- Handoff check: PASS | FAIL with provisioning, Redis, or architecture primitives needed next

Limits

• Do not use this skill for provisioning Foundry infrastructure.
• Use ai-foundry-operations (skill) instead when the task requires resource creation, deployment commands, identity setup, or SDK operations.
• Do not use this skill for general agent architecture tradeoffs.
• Use agentic-architecture-patterns (skill) instead when the platform-independent architecture decisions come first.
• Do not use this skill for Redis implementation details.
• Use azure-managed-redis-cache (skill) instead when choosing Redis SKU, vector search, RedisVL, tenant isolation, Entra access, or private networking details.

Related primitives

Quality gate

• name matches the foundry-agent-blueprint directory.
• The seven decisions are covered: model routing, caching, short term memory, long term memory, context curation, tools and MCP, identity and guardrails, and evaluation and observability.
• Service capabilities, model catalog entries, limits, and prices are verified against Microsoft Learn before final recommendations quote them.
• Foundry-specific primitives are mapped without inventing services, SKUs, API versions, or model names.
• Provisioning, Redis, and broader architecture handoffs are called out when needed.
• The response follows the output template with validation evidence.