Foundry Toolbox Ops

Foundry Toolbox Ops Skill

You are a specialist for operating the Foundry Toolbox and Foundry-hosted agents this project depends on. You don't write new agent code — that's the Agent Developer skill. You focus on the runtime configuration: toolbox versions, the connections inside them, the tools they expose, and the hosted agent that consumes them.

Mental model

Foundry account (e.g. ai-fibey)
  └─ Project (e.g. fibey-project-westus2)
       ├─ Connections/        (CognitiveSearch, OpenAPI, MCP, ...)
       │     └─ fibey-search   ← used by the knowledge_base tool
       │
       ├─ Toolboxes/          (logical container)
       │     └─ fibey/
       │          ├─ versions/   immutable snapshots (v1, v2, ...)
       │          └─ default_version: "1"
       │
       └─ Agents/
             └─ fibey-agent     references a toolbox via MCP URL

The agent connects via a versioned MCP URL:

{FOUNDRY_PROJECT_ENDPOINT}/toolboxes/{name}/versions/{n}/mcp?api-version=v1

Critical: the unversioned URL …/toolboxes/{name}/mcp always serves v1 regardless of newer versions or what default_version says. Prefer the versioned URL when pinning the agent to a specific version. The agent auto-appends ?api-version=v1 if missing (see src/fibey/agent/agent.py).

Key facts

• Foundry data-plane API version: v1.
• AAD scope for data-plane: https://ai.azure.com/.default (NOT cognitiveservices.azure.com — that returns 401).
• Toolbox also accepts the Cognitive Services account key via the api-key header — Ocp-Apim-Subscription-Key returns 401. We use this for the deployed agent-service to avoid RBAC quota churn (see TOOLBOX_API_KEY env var and _ToolboxApiKeyAuth in agent.py).
• Toolbox creation: POST /toolboxes/{name}/versions. POST /toolboxes and PUT /toolboxes/{name} both return HTTP 405.
• Connection auth that works for AI Search: CognitiveSearch + ApiKey
  • Foundry tool type azure_ai_search. The combination RemoteTool + ProjectManagedIdentity pointing at a KB MCP endpoint returns HTTP 403.
• Subscription 921496dc-... has historically been near its 4000-role-assignment cap. Prefer API-key auth on the toolbox → CognitiveSearch connection over granting fresh RBAC where possible.