Ferramenta de organização baseada em intenção no Foundry (versão prévia)

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPTool, WebSearchTool

# Create Foundry project client
endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
project = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
)

# Create toolbox version with web search and MCP tools
toolbox_version = project.beta.toolboxes.create_toolbox_version(
    toolbox_name="my-toolbox",
    description="Toolbox with web search and an MCP server",
    tools=[
        WebSearchTool(),
        MCPTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="never",
            project_connection_id="my-key-auth-connection",
        ),
    ],
)
print(f"Created toolbox: {toolbox_version.name}, version: {toolbox_version.version}")

using Azure.Identity;
using Azure.AI.Projects;

// Create Foundry project client
var projectEndpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>";
AIProjectClient projectClient = new(new Uri(projectEndpoint), new DefaultAzureCredential());
AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

ProjectsAgentTool webTool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateWebSearchTool());

ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    serverLabel: "myserver",
    serverUri: new Uri("https://your-mcp-server.example.com"),
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
        GlobalMcpToolCallApprovalPolicy.NeverRequireApproval
    )
));

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [webTool, mcpTool],
    description: "Toolbox with web search and an MCP server"
);
Console.WriteLine($"Created toolbox: {toolboxVersion.Name}, version: {toolboxVersion.Version}");

POST {project_endpoint}/toolboxes/my-toolbox/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Toolbox with web search and an MCP server",
  "tools": [
    {
      "type": "web_search",
      "description": "Search the web for current information"
    },
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "never",
      "project_connection_id": "my-key-auth-connection"
    }
  ]
}

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

// Create Foundry project client
const projectEndpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>";

const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());

const toolboxVersion = await project.beta.toolboxes.createVersion(
  "my-toolbox",
  [
    {
      type: "web_search",
      description: "Search the web for current information",
    },
    {
      type: "mcp",
      server_label: "myserver",
      server_url: "https://your-mcp-server.example.com",
      require_approval: "never",
      project_connection_id: "my-key-auth-connection",
    },
  ],
  {
    description: "Toolbox with web search and an MCP server",
  },
);
console.log(`Created toolbox: ${toolboxVersion.name}, version: ${toolboxVersion.version}`);

Use o Foundry Toolkit em Visual Studio Code para criar e publicar uma caixa de ferramentas na exibição Tools.

1. Selecione o Foundry Toolkit na Barra de Atividades.
2. Em Meus Recursos, expanda o nome do projeto>Ferramentas.
3. Selecione o ícone + Adicionar Caixa de Ferramentas .
4. Na guia Criar uma Caixa de Ferramentas Personalizada , insira o nome e a descrição da caixa de ferramentas, adicione as ferramentas desejadas e selecione Publicar.

A publicação de uma nova caixa de ferramentas cria sua primeira versão. Essa versão se torna a versão padrão automaticamente.

Ao usar azd, você declara recursos de caixa de ferramentas em um agent.yaml arquivo em vez de chamar o SDK. Defina suas ferramentas na resources seção e implante usando azd ai agent init. Para agent.yaml obter exemplos para cada tipo de ferramenta, consulte Configurar ferramentas. Para obter o fluxo de trabalho de implantação completo, consulte Implantar com o azd.

# 1. Create a manifest directory with your agent.yaml + source files
mkdir my-agent/manifest
# Copy agent.yaml, main.py, Dockerfile, requirements.txt into my-agent/manifest/

# 2. Initialize the azd project (note: -m is REQUIRED)
cd my-agent
$PROJECT_ID = "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"
azd ai agent init -m https://github.com/microsoft/hosted-agents-vnext-private-preview/main/samples/python/toolbox/azd/agent.yaml --project-id $PROJECT_ID -e my-env
# Or equivalently: azd ai agent init -m manifest/ --project-id $PROJECT_ID -e my-env
# ↑ If your agent.yaml declares {{ param }} secrets (e.g., github_pat), you will be prompted to enter
#   them interactively HERE — before init completes. This is the only safe time to supply credentials.
# NOTE: Do NOT use --no-prompt here — it skips the prompt and leaves {{ param }} credentials empty (see Troubleshooting: Credentials Empty with --no-prompt)

# 3. CRITICAL post-init fixes (see "Post-Init Checklist" below)
azd env set enableHostedAgentVNext "true" -e my-env
azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "gpt-4o" -e my-env  # must match the deployment name in azure.yaml

# 4. Provision infrastructure (creates connections via Bicep)
azd provision -e my-env

# 5. Deploy agent (creates toolboxes, container image, agent version)
azd deploy -e my-env

# 6. Invoke the agent (MUST run from the scaffolded project directory)
azd ai agent invoke --new-session "tell me about the latest news in Microsoft Foundry" --timeout 120

Agent.yaml:

kind: hosted
name: toolbox-azd-test
description: LangGraph agent wired for toolbox MCP.
metadata:
  tags:
    - AI Agent Hosting
    - LangGraph

# template: contains the ContainerAgent definition (kind: hosted).
# These fields are used to generate src/<agent>/agent.yaml during init.
template:
  kind: hosted
  protocols:
    - protocol: responses
      version: 1.0.0
  environment_variables:
    # FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_AGENT_TOOLBOX_* are injected
    # automatically by the platform at runtime — do NOT declare them here.
    - name: AZURE_OPENAI_ENDPOINT
      value: ${AZURE_OPENAI_ENDPOINT}
    - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
      value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o}
    - name: TOOLBOX_NAME
      value: ${TOOLBOX_NAME=agent-tools}

# parameters: secret values prompted at init time (or set via azd env).
# azd uppercases the param name to find the env var: github_pat → GITHUB_PAT.
parameters:
  github_pat:
    secret: true
    description: GitHub Personal Access Token (classic ghp_... or fine-grained github_pat_...)

# resources: connections and toolboxes scaffolded into azure.yaml by azd ai agent init.
resources:
  - kind: connection
    name: github-mcp-conn
    target: https://api.githubcopilot.com/mcp
    category: remoteTool
    credentials:
      type: CustomKeys
      keys:
        Authorization: "Bearer {{ github_pat }}"

  - kind: toolbox
    name: agent-tools
    tools:
      - type: web_search
      - type: mcp
        server_label: github
        server_url: https://api.githubcopilot.com/mcp
        project_connection_id: github-mcp-conn

No Foundry Toolkit for Visual Studio Code, copie o ponto de extremidade do consumidor da caixa de ferramentas da exibição Toolboxes.

1. Selecione o Foundry Toolkit na Barra de Atividades.
2. Em Meus Recursos, expanda o nome do projeto>Ferramentas.
3. Na guia Caixas de Ferramentas , localize sua caixa de ferramentas.
4. Na coluna URL do Ponto de Extremidade , copie o ponto de extremidade.

O valor da URL do Endpoint é o endpoint de consumo da ferramenta. Para construir um endpoint específico para uma versão, use o padrão do desenvolvedor mostrado na tabela anterior.

Instale o SDK do cliente MCP:

pip install mcp

Conectar à caixa de ferramentas e listar ferramentas

import asyncio
from azure.identity import DefaultAzureCredential
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

url = "https://<account>.services.ai.azure.com/api/projects/<proj>/toolboxes/<name>/versions/<version>/mcp?api-version=v1"

token = DefaultAzureCredential().get_token("https://ai.azure.com/.default").token
headers = {
    "Authorization": f"Bearer {token}",
    "Foundry-Features": "Toolboxes=V1Preview",
}

async def verify_toolbox():
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools_result = await session.list_tools()
            print(f"Tools found: {len(tools_result.tools)}")
            for tool in tools_result.tools:
                print(f"  - {tool.name}: {(tool.description or '')[:80]}")

            # Call a tool (replace with actual tool name and arguments)
            result = await session.call_tool("<tool_name>", arguments={})
            print(result)

asyncio.run(verify_toolbox())

Utilize o endpoint específico da versão (/versions/{version}/mcp) para validar uma versão antes de promovê-la.

1. Inicializar a sessão MCP:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json
Foundry-Features: Toolboxes=V1Preview

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}

2. Enviar a notificação inicializada:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json
Foundry-Features: Toolboxes=V1Preview

{"jsonrpc":"2.0","method":"notifications/initialized"}

3. Listar as ferramentas disponíveis:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json
Foundry-Features: Toolboxes=V1Preview

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

4. Chame uma ferramenta:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json
Foundry-Features: Toolboxes=V1Preview

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"<TOOL_NAME>","arguments":{}}}

Instale o SDK do cliente MCP:

npm install @modelcontextprotocol/sdk

Conectar à caixa de ferramentas e listar ferramentas

import { DefaultAzureCredential } from "@azure/identity";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const url = "https://<account>.services.ai.azure.com/api/projects/<proj>/toolboxes/<name>/versions/<version>/mcp?api-version=v1";

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://ai.azure.com/.default");

const transport = new StreamableHTTPClientTransport(
  new URL(url),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${token.token}`,
        "Foundry-Features": "Toolboxes=V1Preview",
      },
    },
  },
);

const client = new Client({ name: "test", version: "1.0" });
await client.connect(transport);

// List available tools
const toolsResult = await client.listTools();
console.log(`Tools found: ${toolsResult.tools.length}`);
for (const tool of toolsResult.tools) {
  console.log(`  - ${tool.name}: ${(tool.description || "").slice(0, 80)}`);
}

// Call a tool (replace with actual tool name and arguments)
const result = await client.callTool({ name: "<tool_name>", arguments: {} });
console.log(result);

await client.close();

Use o endpoint da etapa 2 junto com um exemplo de agente hospedado estruturado para validar o carregamento da caixa de ferramentas no VS Code.

1. No Foundry Toolkit, em Meus Recursos>Seu nome de projeto>Ferramentas, localize a caixa de ferramentas que você deseja testar.
2. Selecione o modelo de código Scaffold.
3. Escolha uma pasta de projeto quando solicitado.
4. Siga as dependências geradas README.md para instalar, configurar variáveis de ambiente e executar o exemplo localmente.
5. Use o Inspetor do Agente ou execute python main.py para confirmar se as ferramentas da caixa de ferramentas carregam e respondem.

Para a validação de versão específica antes de promover uma nova versão da toolbox, use a aba Python ou API REST nesta etapa.

LangGraph

.env arquivo:

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
FOUNDRY_AGENT_TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
TOOLBOX_NAME=agent-tools
FOUNDRY_AGENT_TOOLBOX_FEATURES=Toolboxes=V1Preview
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

main.py (padrão de chave):

from langchain_azure_ai.tools import AzureAIProjectToolbox

toolbox = AzureAIProjectToolbox(toolbox_name=TOOLBOX_NAME)
tools = await toolbox.get_tools()

Consulte o exemplo completo para a implementação completa.

Estrutura do agente do Microsoft

Use MCPStreamableHTTPTool do SDK do Agent Framework para se conectar diretamente ao ponto de extremidade MCP da caixa de ferramentas.

.env arquivo:

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
FOUNDRY_AGENT_TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
FOUNDRY_AGENT_TOOLBOX_FEATURES=Toolboxes=V1Preview
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

main.py (padrão de chave):

# Auth: wrap token provider in an httpx.Auth subclass
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
http_client = httpx.AsyncClient(
    auth=_ToolboxAuth(token_provider),
    headers={"Foundry-Features": "Toolboxes=V1Preview"},
    timeout=120.0,
)

# Toolbox MCP endpoint (platform-injected at runtime via FOUNDRY_AGENT_TOOLBOX_ENDPOINT)
TOOLBOX_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1"

# Connect MCPStreamableHTTPTool to the toolbox endpoint
mcp_tool = MCPStreamableHTTPTool(
    name="toolbox",
    url=TOOLBOX_ENDPOINT,
    http_client=http_client,
    load_prompts=False,
)

agent = chat_client.as_agent(
    name="my-toolbox-agent",
    instructions="You are a helpful assistant with access to Foundry toolbox tools.",
    tools=[mcp_tool],
)
ResponsesAgentServerHost().run()

Consulte o exemplo completo para a implementação completa.

SDK do Copilot

Use o SDK do GitHub Copilot para criar um agente alimentado por caixas de ferramentas que conecta a invocação de ferramentas do Copilot ao ponto de extremidade MCP da caixa de ferramentas Foundry.

.env arquivo:

GITHUB_TOKEN=<your-github-token>
FOUNDRY_AGENT_TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1

agent.py (padrão de chave — ponte MCP):

# 1. Open an MCP session to the toolbox endpoint
bridge = McpBridge(endpoint=TOOLBOX_ENDPOINT, token=_get_toolbox_token())
await bridge.initialize()
mcp_tools = await bridge.list_tools()

# 2. Map MCP tool list to Copilot SDK tool definitions
#    Dots in tool names are replaced with underscores (Copilot SDK requirement)
copilot_tools = [
    {
        "name": t["name"].replace(".", "_"),
        "description": t.get("description", ""),
        "parameters": t.get("inputSchema", {}),
    }
    for t in mcp_tools
]

# 3. Wire tool calls back to the MCP session
async def tool_handler(name: str, arguments: dict) -> str:
    return await bridge.call_tool(name.replace("_", ".", 1), arguments)

# 4. Run the Copilot SDK agent
agent = Agent(
    tools=copilot_tools,
    tool_handler=tool_handler,
    token=os.environ["GITHUB_TOKEN"],
)

Consulte o exemplo completo para a implementação completa.

Estrutura do agente do Microsoft

Use ResponsesServer do SDK do Agent Framework com um ToolboxMcpClient personalizado para descobrir e invocar ferramentas do conjunto de ferramentas por meio do ponto de extremidade MCP.

Variáveis de ambiente:

AZURE_OPENAI_ENDPOINT=https://<account>.services.ai.azure.com
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
TOOLBOX_MCP_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1

Program.cs (padrão de chave):

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;

// Azure OpenAI endpoint and model deployment
var openAiEndpoint = "https://<account>.services.ai.azure.com";
var deployment = "gpt-4o";  // supports all toolbox tool types

// Toolbox MCP endpoint (platform-injected at runtime via TOOLBOX_MCP_ENDPOINT)
var toolboxEndpoint = "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1";

// Azure OpenAI client
var credential = new DefaultAzureCredential();
var openAIClient = new AzureOpenAIClient(new Uri(openAiEndpoint), credential);
var chatClient = openAIClient.GetChatClient(deployment);

// Toolbox MCP client — discovers tools via tools/list, calls them via tools/call
var toolboxClient = new ToolboxMcpClient(toolboxEndpoint, credential);

ResponsesServer.Run<ToolboxHandler>(configure: builder =>
{
    builder.Services.AddSingleton(new AgentConfig(chatClient, toolboxClient));
});

ToolboxMcpClient envolve chamadas diretas JSON-RPC para o ponto de extremidade MCP. ToolboxHandler conecta chamadas da ferramenta LLM de volta ao cliente MCP usando um loop de chamada de ferramenta padrão. Para obter a implementação completa de ambas as classes, consulte o exemplo completo.

Use o Foundry Toolkit para estruturar um exemplo de agente hospedado que já esteja conectado à caixa de ferramentas.

1. Selecione o Foundry Toolkit na Barra de Atividades.
2. Em Meus Recursos, expanda o nome do projeto>Ferramentas.
3. Na guia Caixa de Ferramentas, localize a caixa de ferramentas que você deseja consumir e selecione Template de código scaffold.
4. Na Paleta de Comandos, escolha uma pasta de projeto quando solicitado.
5. Abra o arquivo gerado README.md e siga as etapas de instalação, execução em ambiente local e implantação do scaffold.

O projeto gerado inclui o ponto de entrada do agente hospedado, os arquivos de implantação e uma README.md com as etapas exatas de configuração, execução e implantação. O agente estruturado manipula o cabeçalho Foundry-Features: Toolboxes=V1Preview para você.

Se você quiser integrar ferramentas a um projeto de agente hospedado existente em vez de gerar um novo exemplo, use o endpoint copiado da Etapa 2 com os padrões do Python ou .NET apresentados nesta seção.

Implantação com azd

Use a CLI do Desenvolvedor Azure (azd) para declarar recursos da caixa de ferramentas diretamente em um arquivo agent.yaml e implantar seu agente com um único comando. Usando essa abordagem, você não precisa criar a caixa de ferramentas separadamente por meio do SDK ou REST. azd provisiona a caixa de ferramentas, as conexões e a implantação do modelo em conjunto.

Estrutura de pastas:

my-agent/
├── agent.yaml          # Agent, toolbox, and connection declarations
├── main.py             # LangGraph agent
├── requirements.txt    # All dependencies (Azure SDK + PyPI packages)
├── Dockerfile          # Container build

agent.yaml (exemplo de Pesquisa na Web + MCP GitHub):

name: my-toolbox-agent
description: LangGraph agent with Azure AI Foundry toolbox MCP.
metadata:
  tags:
    - AI Agent Hosting
    - LangGraph
template:
  name: my-toolbox-agent
  kind: hosted
  protocols:
    - protocol: responses
      version: 1.0.0
  environment_variables:
    # FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_AGENT_TOOLBOX_* are injected
    # automatically by the platform at runtime — do NOT declare them here.
    - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
      value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o}
    - name: TOOLBOX_NAME
      value: ${TOOLBOX_NAME=agent-tools}
parameters:
  github_pat:
    secret: true
    description: GitHub Personal Access Token for MCP connection
resources:
  - kind: connection
    name: github-mcp-conn
    target: https://api.githubcopilot.com/mcp
    category: RemoteTool
    authType: CustomKeys
    credentials:
      keys:
        Authorization: "Bearer {{ github_pat }}"
  - kind: toolbox
    name: agent-tools
    description: Web search and GitHub MCP tools
    tools:
      - type: web_search
      - type: mcp
        server_label: github
        server_url: https://api.githubcopilot.com/mcp
        project_connection_id: github-mcp-conn

main.py segue o mesmo padrão LangGraph mostrado anteriormente. Ao usar azd, FOUNDRY_AGENT_TOOLBOX_ENDPOINT e TOOLBOX_{toolbox_name}_MCP_ENDPOINT são injetados automaticamente - nenhuma configuração de ponto de extremidade extra é necessária no código.

Implantar:

# 1. Place agent.yaml and source files in a manifest directory
mkdir my-agent/manifest
# Copy agent.yaml, main.py, Dockerfile, requirements.txt into my-agent/manifest/

# 2. Initialize the azd project (-m is required)
cd my-agent
PROJECT_ID="/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"
azd ai agent init -m manifest/ --project-id $PROJECT_ID -e my-env
# If agent.yaml declares {{ param }} secrets (for example, github_pat), you are prompted
# to enter them interactively here. Do NOT use --no-prompt — it leaves credentials empty.

# 3. Set required environment variables
azd env set enableHostedAgentVNext "true" -e my-env
azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "gpt-4o" -e my-env

# 4. Provision infrastructure (creates connections via Bicep)
azd provision -e my-env

# 5. Deploy agent (creates toolboxes, container image, agent version)
azd deploy -e my-env

# 6. Invoke the agent
azd ai agent invoke --new-session "Hello, what tools do you have?" --timeout 120

from azure.ai.projects.models import MCPTool

# Set require_approval on an MCP tool
toolbox_version = project.beta.toolboxes.create_toolbox_version(
    toolbox_name="my-toolbox",
    tools=[
        MCPTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="always",  # "always" | "never"
            project_connection_id="my-connection",
        )
    ],
)

{
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "always",
      "project_connection_id": "my-connection"
    }
  ]
}

ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    serverLabel: "myserver",
    serverUri: new Uri("https://your-mcp-server.example.com"),
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
        GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval
    )
));

const tools = [
  {
    type: "mcp",
    server_label: "myserver",
    server_url: "https://your-mcp-server.example.com",
    require_approval: "always",
    project_connection_id: "my-connection",
  },
];

Use a aba Python, .NET, JavaScript, API REST ou azd para configurar require_approval na definição da caixa de ferramentas. O fluxo de trabalho do Foundry Toolkit neste artigo se concentra em criar e consumir a caixa de ferramentas em Visual Studio Code.

resources:
  - kind: toolbox
    name: my-toolbox
    tools:
      - type: mcp
        server_label: myserver
        server_url: https://your-mcp-server.example.com
        require_approval: always
        project_connection_id: my-connection

# Create a new toolbox version
toolbox_version = project.beta.toolboxes.create_toolbox_version(
    toolbox_name="my-toolbox",
    description="Updated tools v2",
    tools=[...],
)
print(f"Created version: {toolbox_version.version}")

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Updated tools v2"
);
Console.WriteLine($"Created version: {toolboxVersion.Version}");

POST {project_endpoint}/toolboxes/my-toolbox/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Updated tools v2",
  "tools": [...]
}

const toolboxVersion = await project.beta.toolboxes.createVersion(
  "my-toolbox",
  [/* tools array */],
  { description: "Updated tools v2" },
);
console.log(`Created version: ${toolboxVersion.version}`);

Use a guia Python, .NET, JavaScript ou API REST para criar uma nova versão da caixa de ferramentas. O fluxo de trabalho do Foundry Toolkit neste artigo se concentra na criação de ferramentas e na estruturação de um agente hospedado que as utiliza.

Essa operação não é suportada pelo azd. Para criar uma versão da caixa de ferramentas, use a guia Python, .NET, REST API ou JavaScript.

# List all toolbox versions
versions = list(project.beta.toolboxes.list_toolbox_versions(toolbox_name="my-toolbox"))
for v in versions:
    print(f"{v.version} — created {v.created_at}")

List<ToolboxVersion> versions = await toolboxClient
    .GetToolboxVersionsAsync("my-toolbox")
    .ToListAsync();
Console.WriteLine($"Found {versions.Count} toolbox version(s).");
foreach (ToolboxVersion v in versions)
{
    Console.WriteLine($"  - {v.Name} ({v.Version})");
}

GET {project_endpoint}/toolboxes/my-toolbox/versions?api-version=v1
Authorization: Bearer {token}

const versions = project.beta.toolboxes.listVersions("my-toolbox");
for await (const v of versions) {
  console.log(`${v.version} — created ${v.createdAt}`);
}

Use a guia Python, .NET, JavaScript ou API REST para listar versões da caixa de ferramentas.

Essa operação não é suportada pelo azd. Para listar versões da caixa de ferramentas, use a guia Python, .NET, REST API ou JavaScript.

# Get a specific toolbox version
version_obj = project.beta.toolboxes.get_toolbox_version(
    toolbox_name="my-toolbox",
    version="<version_id>",
)

ToolboxVersion versionObj = await toolboxClient.GetToolboxVersionAsync(
    "my-toolbox",
    "<version_id>"
);
Console.WriteLine($"Retrieved toolbox: {versionObj.Name} ({versionObj.Id})");

GET {project_endpoint}/toolboxes/my-toolbox/versions/{version}?api-version=v1
Authorization: Bearer {token}

const versionObj = await project.beta.toolboxes.getVersion(
  "my-toolbox",
  "<version_id>",
);
console.log(`Retrieved version: ${versionObj.version}`);

Use a guia Python, .NET, JavaScript ou API REST para obter uma versão específica da caixa de ferramentas.

Essa operação não é suportada pelo azd. Para obter uma versão específica da caixa de ferramentas, use a guia Python, .NET, REST API ou JavaScript.

# Promote a version to default
toolbox = project.beta.toolboxes.update(
    toolbox_name="my-toolbox",
    default_version="<version_id>",
)
print(f"Active version: {toolbox.default_version}")

ToolboxRecord record = await toolboxClient.UpdateToolboxAsync(
    "my-toolbox",
    "<version_id>"
);
Console.WriteLine($"Active version: {record.DefaultVersion}");

PATCH {project_endpoint}/toolboxes/my-toolbox?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "default_version": "<version_id>"
}

default_version não pode estar vazio. Substitua-o por uma nova versão.

const toolbox = await project.beta.toolboxes.update(
  "my-toolbox",
  "<version_id>",
);
console.log(`Active version: ${toolbox.defaultVersion}`);

Use a aba Python, .NET, JavaScript ou API REST para promover uma versão de ferramentas como padrão.

Essa operação não é suportada pelo azd. Para promover uma versão para o padrão, use a guia Python, .NET, REST API ou a guia JavaScript.

# Delete a toolbox version
project.beta.toolboxes.delete_toolbox_version(
    toolbox_name="my-toolbox",
    version="<version_id>",
)

await toolboxClient.DeleteToolboxVersionAsync(
    "my-toolbox",
    "<version_id>"
);

DELETE {project_endpoint}/toolboxes/my-toolbox/versions/{version}?api-version=v1
Authorization: Bearer {token}

await project.beta.toolboxes.deleteVersion(
  "my-toolbox",
  "<version_id>",
);

Use a aba Python, .NET, JavaScript ou REST API para excluir uma versão da caixa de ferramentas.

Essa operação não é suportada pelo azd. Para excluir uma versão da caixa de ferramentas, use a guia Python, .NET, REST API ou JavaScript.

Autenticação baseada em chave:

{
  "description": "my-mcp-toolbox",
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "project_connection_id": "my-mcp-connection"
    }
  ]
}

Sem autenticação (servidor MCP público):

{
  "description": "Public MCP server",
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com"
    }
  ]
}

Autenticação baseada em identidade ou OAuth:

Para o OAuth (conector gerenciado, registro de aplicativo personalizado), identidade do agente ou autenticação do token Entra do usuário, primeiro crie a conexão apropriada em seu projeto do Foundry e, em seguida, referencie-a com project_connection_id:

{
  "description": "MCP server with OAuth/identity auth",
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "project_connection_id": "<OAUTH_OR_IDENTITY_CONNECTION_NAME>"
    }
  ]
}

A conexão authType determina o fluxo de autenticação. Os tipos de autenticação de conexão com suporte para MCP incluem CustomKeys, OAuth2 (gerenciado ou personalizado) AgenticIdentitye UserEntraToken. Consulte a guia azd para obter exemplos de configuração de conexão para cada tipo de autenticação.

from azure.ai.projects.models import MCPTool

tools = [
    MCPTool(
        server_label="myserver",
        server_url="https://your-mcp-server.example.com",
        project_connection_id="my-mcp-connection",
    )
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    serverLabel: "myserver",
    serverUri: new Uri("https://your-mcp-server.example.com")
));

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "my-mcp-toolbox"
);

const tools = [
  {
    type: "mcp",
    server_label: "myserver",
    server_url: "https://your-mcp-server.example.com",
    project_connection_id: "my-mcp-connection",
  },
];

Sem autenticação:

resources:
  - kind: toolbox
    name: mcp-tools
    description: Public MCP server tools
    tools:
      - type: mcp
        server_label: myserver
        server_url: https://your-mcp-server.example.com

Autenticação baseada em chave:

parameters:
  mcp_api_key:
    secret: true
    description: API key for the MCP server
resources:
  - kind: connection
    name: mcp-conn
    target: https://your-mcp-server.example.com
    category: RemoteTool
    authType: CustomKeys
    credentials:
      keys:
        Authorization: "Bearer {{ mcp_api_key }}"
  - kind: toolbox
    name: mcp-tools
    description: MCP server tools with key auth
    tools:
      - type: mcp
        server_label: myserver
        server_url: https://your-mcp-server.example.com
        project_connection_id: mcp-conn

OAuth – conector gerenciado:

Use esse padrão para servidores MCP que dão suporte ao fluxo OAuth gerenciado do Foundry. O valor connectorName deve corresponder a um conector gerenciado disponível no Catálogo de Ferramentas Foundry.

resources:
  - kind: connection
    name: github-oauth-conn
    category: RemoteTool
    authType: OAuth2
    target: https://api.githubcopilot.com/mcp
    connectorName: foundrygithubmcp
  - kind: toolbox
    name: oauth-tools
    description: GitHub OAuth MCP toolbox
    tools:
      - type: mcp
        server_label: github
        project_connection_id: github-oauth-conn

OAuth – registro de aplicativo personalizado:

Use esse padrão ao trazer seu próprio registro de aplicativo OAuth para o servidor MCP.

parameters:
  oauth_client_id:
    secret: true
    description: OAuth client ID
  oauth_client_secret:
    secret: true
    description: OAuth client secret
resources:
  - kind: connection
    name: mcp-oauth-custom-conn
    category: RemoteTool
    authType: OAuth2
    target: https://your-mcp-server.example.com
    authorizationUrl: https://auth.example.com/authorize
    tokenUrl: https://auth.example.com/token
    refreshUrl: https://auth.example.com/token
    scopes: []
    credentials:
      clientID: "{{ oauth_client_id }}"
      clientSecret: "{{ oauth_client_secret }}"
  - kind: toolbox
    name: oauth-custom-tools
    description: MCP toolbox with custom OAuth
    tools:
      - type: mcp
        server_label: myserver
        project_connection_id: mcp-oauth-custom-conn

Identidade do Agente (Entra ID):

Use esse padrão para servidores MCP que dão suporte à autenticação Microsoft Entra ID. A identidade do agente do Foundry é verificada em relação ao recurso de destino.

resources:
  - kind: connection
    name: language-mcp
    category: RemoteTool
    authType: AgenticIdentity
    audience: <entra-audience>
    target: https://<resource>.cognitiveservices.azure.com/language/mcp?api-version=2025-11-15-preview
  - kind: toolbox
    name: agent-identity-tools
    description: MCP toolbox with agent identity auth
    tools:
      - type: mcp
        server_label: language
        project_connection_id: language-mcp

Token de Entrada do Usuário (OBO 1P):

Use esse padrão para servidores MCP que exigem a identidade do usuário por meio do fluxo OBO (On-Behalf-Of). Foundry encaminha o token Entra do usuário para o servidor MCP.

resources:
  - kind: connection
    name: workiq-mail-conn
    category: RemoteTool
    authType: UserEntraToken
    audience: <entra-app-id>
    target: https://agent365.svc.cloud.microsoft/agents/servers/mcp_MailTools
  - kind: toolbox
    name: workiq-tools
    description: MCP toolbox with user Entra token auth
    tools:
      - type: mcp
        server_label: workiq
        project_connection_id: workiq-mail-conn

{
  "description": "Built-in web search",
  "tools": [
    {
      "type": "web_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>"
    }
  ]
}

Integração da Pesquisa Personalizada do Bing:

{
  "description": "Custom Bing Search instance",
  "tools": [
    {
      "type": "web_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "web_search": {
        "custom_search_configuration": {
          "project_connection_id": "<BING_CONNECTION_NAME>",
          "instance_name": "<BING_INSTANCE_NAME>"
        }
      }
    }
  ]
}

from azure.ai.projects.models import WebSearchTool

tools = [
    WebSearchTool()
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateWebSearchTool()
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Built-in web search"
);

const tools = [
  {
    type: "web_search",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
  },
];

resources:
  - kind: toolbox
    name: websearch-tools
    description: Web search toolbox
    tools:
      - type: web_search

Usando a Pesquisa Personalizada do Bing:

parameters:
  bing_api_key:
    secret: true
    description: Bing API key
resources:
  - kind: connection
    name: bing-custom-conn
    category: GroundingWithCustomSearch
    authType: ApiKey
    target: ""
    credentials:
      key: "{{ bing_api_key }}"
    metadata:
      ResourceId: /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Bing/accounts/<bing-account>
      type: bing_custom_search
  - kind: toolbox
    name: bing-custom-tools
    description: Bing Custom Search toolbox
    tools:
      - type: bing_custom_search
        custom_search_configuration:
          instance_name: your-bing-custom-instance
        project_connection_id: bing-custom-conn

{
  "description": "Azure AI Search over my data",
  "tools": [
    {
      "type": "azure_ai_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<INDEX_NAME>",
            "project_connection_id": "<CONNECTION_NAME>"
          }
        ]
      }
    }
  ]
}

from azure.ai.projects.models import AzureAISearchTool

tools = [
    AzureAISearchTool(
        index_name="<INDEX_NAME>",
        project_connection_id="<CONNECTION_NAME>",
    )
]

ProjectsAgentTool tool = new AzureAISearchTool(
    new AzureAISearchToolOptions(
        indexes: [
            new AzureAISearchIndexResource(
                indexName: "<INDEX_NAME>",
                projectConnectionId: "<CONNECTION_NAME>"
            )
        ]
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Azure AI Search over my data"
);

const tools = [
  {
    type: "azure_ai_search",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    azure_ai_search: {
      indexes: [
        {
          index_name: "<INDEX_NAME>",
          project_connection_id: "<CONNECTION_NAME>",
        },
      ],
    },
  },
];

parameters:
  ai_search_key:
    secret: true
    description: Azure AI Search admin key
resources:
  - kind: connection
    name: aisearch-conn
    category: CognitiveSearch
    authType: ApiKey
    target: https://your-search-service.search.windows.net/
    credentials:
      key: "{{ ai_search_key }}"
  - kind: toolbox
    name: search-tools
    description: Azure AI Search toolbox
    tools:
      - type: azure_ai_search
        index_name: your-index-name
        project_connection_id: aisearch-conn

{
  "description": "Code interpreter for data analysis",
  "tools": [
    {
      "type": "code_interpreter",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "container": {
            "type": "auto",
            "file_ids": ["<FILE_ID>"]
        }
    }
  ]
}

from azure.ai.projects.models import CodeInterpreterTool

tools = [
    CodeInterpreterTool()
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateCodeInterpreterTool(
        new CodeInterpreterToolContainer()
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Code interpreter for data analysis"
);

const tools = [
  {
    type: "code_interpreter",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    container: {
      type: "auto",
      file_ids: ["<FILE_ID>"],
    },
  },
];

resources:
  - kind: toolbox
    name: codeinterp-tools
    description: Code interpreter toolbox
    tools:
      - type: code_interpreter

{
  "description": "Search over uploaded documents",
  "tools": [
    {
      "type": "file_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "file_search": {
        "vector_store_ids": ["<VECTOR_STORE_ID>"]
      }
    }
  ]
}

from azure.ai.projects.models import FileSearchTool

tools = [
    FileSearchTool(
        vector_store_ids=["<VECTOR_STORE_ID>"]
    )
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateFileSearchTool(
        vectorStoreIds: ["<VECTOR_STORE_ID>"]
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Search over uploaded documents"
);

const tools = [
  {
    type: "file_search",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    file_search: {
      vector_store_ids: ["<VECTOR_STORE_ID>"],
    },
  },
];

resources:
  - kind: toolbox
    name: filesearch-tools
    description: File search toolbox
    tools:
      - type: file_search
        vector_store_ids:
          - ${FILE_SEARCH_VECTOR_STORE_ID}

Defina a ID do repositório de vetores antes de implantar:

azd env set FILE_SEARCH_VECTOR_STORE_ID "vs_xxxxxxxxxxxx"

Autenticação anônima:

{
  "description": "REST API via OpenAPI spec",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "anonymous"
        }
      }
    }
  ]
}

Autenticação de conexão do projeto:

Use esse padrão quando a API exigir uma chave ou token armazenado em uma conexão de projeto do Foundry.

{
  "description": "REST API with connection-based auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "connection",
          "security_scheme": {
            "project_connection_id": "<CONNECTION_NAME>"
          }
        }
      }
    }
  ]
}

Autenticação de identidade gerenciada:

Use esse padrão quando a API de destino for autenticada por meio de Microsoft Entra ID. A identidade gerenciada do projeto foundry chama a API em nome do agente. Verifique se a identidade gerenciada tem a função RBAC necessária no serviço de destino antes de usar esse padrão.

{
  "description": "REST API with managed identity auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "managed_identity",
          "security_scheme": {
            "audience": "<TARGET_SERVICE_AUDIENCE>"
          }
        }
      }
    }
  ]
}

from azure.ai.projects.models import OpenAPITool

tools = [
    OpenAPITool(
        name="my-api",
        spec={"<paste OpenAPI spec object here>"},
        auth={"type": "anonymous"},
    )
]

BinaryData specBytes = BinaryData.FromString("<OpenAPI spec JSON>");
ProjectsAgentTool tool = new OpenAPITool(
    new OpenApiFunctionDefinition(
        name: "my-api",
        spec: specBytes,
        openApiAuthentication: new OpenApiAnonymousAuthDetails()
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "REST API via OpenAPI spec"
);

const tools = [
  {
    type: "openapi",
    openapi: {
      name: "my-api",
      spec: { /* paste OpenAPI spec object here */ },
      auth: {
        type: "anonymous",
      },
    },
  },
];

Autenticação baseada em chave:

parameters:
  api_key:
    secret: true
    description: API key for the target service
resources:
  - kind: connection
    name: api-conn
    category: CustomKeys
    authType: CustomKeys
    target: https://api.example.com
    credentials:
      keys:
        key: "{{ api_key }}"
  - kind: toolbox
    name: openapi-tools
    description: OpenAPI key-auth toolbox
    tools:
      - type: openapi
        openapi:
          name: my-api
          spec:
            openapi: "3.0.1"
            info:
              title: "My API"
              version: "1.0"
            servers:
              - url: https://api.example.com/v1
            paths:
              /search:
                get:
                  operationId: search
                  parameters:
                    - name: query
                      in: query
                      required: true
                      schema:
                        type: string
                  responses:
                    "200":
                      description: OK
          auth:
            type: connection_auth
            connection_id: api-conn

{
  "description": "Delegate tasks to a specialist agent",
  "tools": [
    {
      "type": "a2a_preview",
      "name": "<AGENT_NAME>",
      "description": "<What this agent does>",
      "base_url": "<AGENT_BASE_URL>",
      "project_connection_id": "<CONNECTION_NAME>"
    }
  ]
}

from azure.ai.projects.models import A2APreviewTool

tools = [
    A2APreviewTool(
        name="<AGENT_NAME>",
        description="<What this agent does>",
        base_url="<AGENT_BASE_URL>",
        project_connection_id="<CONNECTION_NAME>",
    )
]

ProjectsAgentTool tool = new A2APreviewTool()
{
    ProjectConnectionId = "<CONNECTION_NAME>",
};

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Delegate tasks to a specialist agent"
);

const tools = [
  {
    type: "a2a_preview",
    name: "<AGENT_NAME>",
    description: "<What this agent does>",
    base_url: "<AGENT_BASE_URL>",
    project_connection_id: "<CONNECTION_NAME>",
  },
];

resources:
  - kind: connection
    name: a2a-conn
    category: RemoteA2A
    authType: None
    target: https://your-remote-agent.azurecontainerapps.io
  - kind: toolbox
    name: a2a-tools
    description: Agent-to-Agent toolbox
    tools:
      - type: a2a_preview
        project_connection_id: a2a-conn