Deployment Pattern for Foundry Toolboxes with Independent Lifecycles
Foundry Toolbox deployments should be owned by a project-level pipeline, not by any agent's lifecycle, to keep shared tool changes from redeploying unrelated agents. Each Toolbox version is an immutable configuration snapshot that requires explicit promotion, and agents consume the default version through a stable endpoint while candidates are validated against version-specific endpoints. The pattern keeps governance decisions about testing, approval, and access with the team rather than encoding them in the platform.

A Foundry Toolbox is a versioned collection of tools — web search, capabilities exposed by Model Context Protocol (MCP) servers, or third-party applications — served through a single MCP-compatible endpoint. It centralizes tool access, credentials, governance, and versioning so an integration is configured once and reused across agents.
The recommended deployment pattern defines each Toolbox in its own azure.yaml, deploys it independently of project infrastructure and agents, and passes environment-specific Bicep outputs through GitHub Actions.
The core design rule is that no agent lifecycle should own Toolbox version changes. A Toolbox lives within a Foundry Project, but creating one with the SDK does not attach it to an agent. Coupling appears when an agent's deployment pipeline also owns and publishes the Toolbox; tool changes then redeploy unrelated agents, and shared tool availability depends on one agent's release cadence. Keeping version changes on a project-level pipeline lets agents consume the Toolbox endpoint.
Toolbox versions are immutable snapshots of configuration; changes create a new version rather than modifying an existing one. The first version becomes default automatically, and later versions require explicit promotion. Agents using the stable consumer endpoint receive the default version; developers can validate candidates against a version-specific endpoint before promoting. Rollback means promoting a previously retained version. A version captures configuration, not a frozen copy of the external services it calls, so rollback does not reverse changes made downstream.
The deployment workflow provisions the Foundry Project and required connections first, then creates and deploys Toolbox versions through the project endpoint. The sample workflow runs Toolbox deployment as a separate step in the same GitHub Actions job, after infrastructure provisioning, so the Toolbox's azd environment receives environment-specific Bicep outputs. The postdeploy hook promotes immediately, which differs from a production process that validates a candidate before promotion.
Operational prerequisites include OpenID Connect authentication for GitHub Actions, Foundry User role on the project for the deployment identity, Azure Developer CLI 1.37.0+, and a target region supporting the Toolbox's tool types and models. Credentials should be in managed identities or approved secret stores, not Bicep outputs.
The platform handles versioning and promotion, but teams still decide how changes are tested, approved, retained, and retired. Ownership, candidate validation, and access remain organizational decisions.
Read the original at techcommunity.microsoft.com →