Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Um recurso do Foundry fornece acesso unificado a modelos, agentes e ferramentas. Este artigo explica qual SDK e endpoint utilizar para a sua situação.
| SDK | Para que serve | Ponto final |
|---|---|---|
| Foundry SDK | Capacidades específicas de fundição com interfaces compatíveis com OpenAI. Inclui acesso aos modelos diretos do Foundry por meio da API de Respostas (não Conclusões de Chat). | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| SDK de OpenAI | Modelos e recursos mais recentes do SDK do OpenAI com a superfície completa da API OpenAI. Os modelos Foundry Direct estão disponíveis através da API Chat Completions (não Responses). | https://<resource-name>.openai.azure.com/openai/v1 |
| SDKs do Foundry Tools | Soluções predefinidas (Visão, Fala, Segurança de Conteúdo e muito mais). | Pontos de extremidade específicos da ferramenta (varia de acordo com o serviço). |
| Estrutura do Agente | Orquestração de multiagentes em código. Independente de nuvem. | Usa o endpoint do projeto por meio do SDK do Foundry. |
Escolha seu SDK:
- Usar o SDK do Foundry ao criar aplicativos com agentes, avaliações ou recursos específicos do Foundry
- Use o SDK do OpenAI quando a compatibilidade máxima do OpenAI for necessária ou usando modelos diretos do Foundry por meio de Preenchimentos de Chat
- Use Foundry Tools SDKs ao trabalhar com serviços de IA específicos (Visão, Fala, Linguagem, etc.)
- Usar o Agent Framework ao criar sistemas de vários agentes no código (orquestração local)
Observação
Tipos de recurso: Um recurso do Foundry fornece todos os pontos de extremidade listados anteriormente. Um recurso Azure OpenAI fornece apenas o ponto de extremidade /openai/v1.
Authentication: Exemplos aqui usam Microsoft Entra ID (DefaultAzureCredential). As chaves de API funcionam em /openai/v1. Passe a chave como api_key em vez de um provedor de token.
Pré-requisitos
-
Uma conta Azure com uma assinatura ativa. Se você não tiver uma, crie uma conta de Azure free, que inclui uma assinatura de avaliação gratuita.
Tenha uma das seguintes Azure funções RBAC para criar e gerenciar recursos do Foundry:
- Usuário de IA do Azure (função de privilégio mínimo para desenvolvimento)
- Azure AI Project Manager (para gerenciar projetos do Foundry)
- Colaborador ou Proprietário (para permissões no nível da assinatura)
Para obter detalhes sobre as permissões de cada função, consulte o controle de acesso baseado em Role para Microsoft Foundry.
Instale os runtimes de idioma necessários, as ferramentas globais e as extensões do VS Code, conforme descrito em Preparar seu ambiente de desenvolvimento.
Importante
Antes de começar, verifique se o ambiente de desenvolvimento está pronto.
Este artigo se concentra em etapas específicas do cenário , como instalação do SDK, autenticação e execução de código de exemplo.
Verificar pré-requisitos
Antes de prosseguir, confirme:
- Azure assinatura está ativa:
az account show - Você tem a função RBAC necessária: verifique o portal do Azure → recurso Foundry → controle de acesso (IAM)
- Tempo de execução do idioma instalado:
- Python:
python --version(≥3.8)
- Python:
- Tempo de execução do idioma instalado:
- Node.js:
node --version(≥18)
- Node.js:
- Tempo de execução do idioma instalado:
- .NET:
dotnet --version(≥6.0)
- .NET:
- Tempo de execução do idioma instalado:
- Java:
java --version(≥11)
- Java:
Foundry SDK
O Foundry SDK conecta-se a um único endpoint de projeto que fornece acesso às funcionalidades mais populares do Foundry:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
Observação
Se sua organização usar um subdomínio personalizado, substitua <resource-name><your-custom-subdomain> na URL do ponto de extremidade.
Essa abordagem simplifica a configuração do aplicativo. Em vez de gerenciar vários pontos de extremidade, você configura apenas um.
Instalar o SDK
| Versão do SDK | Versão do Portal | Situação | Pacote Python |
|---|---|---|---|
| 2.x | Fundição (nova) | Estável | azure-ai-projects>=2.0.0 |
| 1.x | Foundry (clássico) | Estável | azure-ai-projects==1.0.0 |
A biblioteca de clientes Azure AI Projects para Python é uma biblioteca unificada que permite que você use várias bibliotecas de cliente juntas conectando-se a um único ponto de extremidade de projeto.
Execute este comando para instalar os pacotes para projetos do Foundry.
pip install azure-ai-projects >=2.0.0
| Versão do SDK | Versão do Portal | Situação | Pacote Java |
|---|---|---|---|
| 2.0.0 | Fundição (nova) | Estável | azure-ai-projectsazure-ai-agents |
| Versão do SDK | Versão do Portal | Situação | Pacote JavaScript |
|---|---|---|---|
| 2.0.1 | Fundição (nova) | Estável | @azure/ai-projects |
| 1.0.1 | Clássico da fundição | Estável | @azure/ai-projects |
| Versão do SDK | Versão do Portal | Situação | Pacote .NET |
|---|---|---|---|
| 2.0.0 (GA) | Fundição (nova) | Estável | Azure.AI.ProjectsAzure.AI.Projects.AgentsAzure.AI.Extensions.OpenAI |
| 1.1.0 (GA) | Clássico da fundição | Estável | Azure.AI.Projects |
Importante
Não instale Azure.AI.Projects.OpenAI (versão prévia) junto com Azure.AI.Extensions.OpenAI (GA). Ambos os pacotes definem os mesmos tipos em namespaces diferentes, o que causa erros de referência ambíguos. Use apenas Azure.AI.Extensions.OpenAI para cenários de agente.
A biblioteca de clientes Azure AI Projects para Java é uma biblioteca unificada que permite que você use várias bibliotecas de cliente juntas conectando-se a um único ponto de extremidade de projeto.
Adicione esses pacotes à sua instalação para projetos do Foundry.
package com.azure.ai.agents;
import com.azure.core.util.Configuration;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
A biblioteca de clientes Azure AI Projects para JavaScript é uma biblioteca unificada que permite que você use várias bibliotecas de cliente juntas conectando-se a um único ponto de extremidade de projeto.
Execute este comando para instalar os pacotes JavaScript para projetos do Foundry.
npm install @azure/ai-projects @azure/identity dotenv
A biblioteca de clientes Azure AI Projects para .NET é uma biblioteca unificada que permite que você use várias bibliotecas de clientes juntas conectando-se a um único ponto de extremidade de projeto.
Execute esses comandos para adicionar os pacotes necessários ao seu projeto de .NET.
dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity
Usando o SDK do Foundry
O SDK expõe dois tipos de cliente porque o Foundry e o OpenAI têm formas de API diferentes:
- Project client – Use para operações nativas do Foundry em que o OpenAI não tem equivalente. Exemplos: listar conexões, recuperar propriedades do projeto, habilitar o rastreamento.
-
Cliente compatível com OpenAI – Use a funcionalidade da Foundry que se baseia em conceitos do OpenAI. A API de Respostas, agentes, avaliações e ajuste fino usam padrões de solicitação/resposta no estilo OpenAI. Esse cliente também fornece acesso a modelos diretos do Foundry (modelos não Azure-OpenAI hospedados na Foundry). O endpoint do projeto atende a esse tráfego na rota
/openai.
A maioria dos aplicativos usa os dois clientes. Use o cliente do projeto para configuração e configuração e use o cliente compatível com OpenAI para executar agentes, avaliações e modelos de chamada (incluindo modelos diretos do Foundry).
Criar um cliente de projeto:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
project_client = AIProjectClient(
endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
credential=DefaultAzureCredential())
Crie um cliente compatível com OpenAI do seu projeto:
with project_client.get_openai_client() as openai_client:
response = openai_client.responses.create(
model="gpt-5.2",
input="What is the size of France in square miles?",
)
print(f"Response output: {response.output_text}")
Saída esperada:
Response output: France has an area of approximately 213,011 square miles (551,695 square kilometers).
Criar um cliente de projeto:
import com.azure.ai.projects.ProjectsClient;
import com.azure.ai.projects.ProjectsClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;
String endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
ProjectsClient projectClient = new ProjectsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(endpoint)
.buildClient();
```**Create and use an OpenAI-compatible client from your project:**
```java
OpenAIClient openAIClient = projectClient.getOpenAIClient();
Criar um cliente de projeto:
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";
const projectEndpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const deploymentName = "gpt-5.2";
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
Crie um cliente compatível com OpenAI do seu projeto:
const openAIClient = await project.getOpenAIClient();
const response = await openAIClient.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
Criar um cliente de projeto:
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
AIProjectClient projectClient = new(
endpoint: new Uri(endpoint),
tokenProvider: new DefaultAzureCredential());
Crie um cliente compatível com OpenAI do seu projeto:
var responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForModel("gpt-5.2");
var response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
O que você pode fazer com o SDK do Foundry
- Access Foundry Models, incluindo Azure OpenAI
- Usar o Serviço do Foundry Agent
- Executar avaliações em lote
- Habilitar o rastreamento de aplicativo
- Ajustar um modelo
- Obtenha pontos de extremidade e chaves para Foundry Tools, orquestração local e muito mais
Resolução de problemas
Erros de autenticação
Se você vir DefaultAzureCredential failed to retrieve a token:
Verify CLI do Azure é autenticado:
az account show az login # if not logged inVerifique as atribuições de funções RBAC:
- Confirme se você tem pelo menos a função de usuário de IA Azure no projeto Foundry
- Consulte Atribuir funções do Azure
Para identidade gerenciada em produção:
- Verifique se a identidade gerenciada tem a função apropriada atribuída
- Consulte Configurar identidades gerenciadas
Erros de configuração de ponto de extremidade
Se você vir Connection refused ou 404 Not Found:
- Verificar se os nomes de recursos e projetos correspondem à sua implantação real
-
Verificar o formato da URL do ponto de extremidade: Deve ser
https://<resource-name>.services.ai.azure.com/api/projects/<project-name> -
Para subdomínios personalizados: substitua
<resource-name>pelo subdomínio personalizado
Incompatibilidades de versão do SDK
Se os exemplos de código falharem com AttributeError ou ModuleNotFoundError:
Verifique a versão do SDK:
pip show azure-ai-projects # Python npm list @azure/ai-projects # JavaScript dotnet list package # .NETReinstalar com sinalizadores de versão corretos: consulte os comandos de instalação em cada seção de idioma acima
SDK de OpenAI
Utilize o SDK do OpenAI quando quiser a superfície completa da API OpenAI e a compatibilidade máxima do cliente. Este endpoint fornece acesso aos modelos Azure OpenAI e aos modelos diretos do Foundry (por meio da API de Responses). Ele não fornece acesso a recursos específicos do Foundry, como agentes e avaliações.
O trecho de código a seguir mostra como usar o ponto de extremidade Azure OpenAI /openai/v1 diretamente.
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
base_url = "https://<resource-name>.openai.azure.com/openai/v1/",
api_key=token_provider,
)
response = client.responses.create(
model="model_deployment_name",
input= "What is the size of France in square miles?"
)
print(response.model_dump_json(indent=2))
Saída esperada:
{
"id": "resp_abc123",
"object": "response",
"created": 1234567890,
"model": "gpt-5.2",
"output_text": "France has an area of approximately 213,011 square miles (551,695 square kilometers)."
}
Para obter mais informações, consulte linguagens de programação suportadas pelo Azure OpenAI
O trecho de código a seguir mostra como usar o ponto de extremidade Azure OpenAI /openai/v1 diretamente.
import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import java.util.function.Supplier;
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
String endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
String deploymentName = "gpt-5.2";
Supplier<String> bearerTokenSupplier = AuthenticationUtil.getBearerTokenSupplier(
tokenCredential, "https://ai.azure.com/.default");
OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
.baseUrl(endpoint)
.credential(BearerTokenCredential.create(bearerTokenSupplier))
.build();
ResponseCreateParams responseCreateParams = ResponseCreateParams.builder()
.input("What is the speed of light?")
.model(deploymentName)
.build();
Response response = openAIClient.responses().create(responseCreateParams);
System.out.println("Response output: " + response.getOutputText());
Para obter mais informações sobre como usar o SDK do OpenAI, consulte Azure linguagens de programação com suporte do OpenAI
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://ai.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const client = new OpenAI({ baseURL: endpoint, apiKey: azureADTokenProvider });
const response = await client.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
Para obter mais informações sobre como usar o SDK do OpenAI, consulte Azure linguagens de programação com suporte do OpenAI
- Instale o pacote OpenAI: execute este comando para adicionar a biblioteca de clientes OpenAI ao seu projeto de .NET.
dotnet add package OpenAI ```When it succeeds, the .NET CLI confirms that it installed the `OpenAI` package. This snippet configures `DefaultAzureCredential`, builds `OpenAIClientOptions`, and creates a `ResponsesClient` for the Azure OpenAI v1 endpoint. ```csharp using Azure.Identity; using OpenAI; using OpenAI.Responses; using System.ClientModel.Primitives; #pragma warning disable OPENAI001 const string directModelEndpoint = "https://<resource-name>.openai.azure.com/openai/v1/"; const string deploymentName = "gpt-5.2"; BearerTokenPolicy tokenPolicy = new( new DefaultAzureCredential(), "https://ai.azure.com/.default"); OpenAIClient openAIClient = new( authenticationPolicy: tokenPolicy, options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ResponsesClient client = openAIClient.GetResponsesClient(); CreateResponseOptions options = new() { Model = deploymentName, InputItems = { ResponseItem.CreateUserMessageItem("What is the size of France in square miles?") }, Temperature = (float)0.7, }; var modelDirectResponse = client.CreateResponse(options); Console.WriteLine($"[ASSISTANT]: {modelDirectResponse.Value.GetOutputText()}"); #pragma warning restore OPENAI001
Para obter mais informações sobre como usar o SDK do OpenAI, consulte Azure linguagens de programação com suporte do OpenAI
Usando a Estrutura do Agente para orquestração local
Microsoft Agent Framework é um SDK de software livre para a criação de sistemas de vários agentes em código (por exemplo, .NET e Python) com uma interface independente do provedor de nuvem.
Use o Agent Framework quando quiser definir e orquestrar agentes localmente. Emparelhe-o com o SDK do Foundry quando quiser que esses agentes sejam executados em modelos do Foundry ou quando desejar que o Agent Framework orquestrá agentes hospedados no Foundry.
Para obter mais informações, consulte a visão geral do Microsoft Agent Framework.
SDKs do Foundry Tools
As Ferramentas Foundry (anteriormente Azure Serviços de IA) são soluções pontuais pré-construídas com SDKs dedicados. Utilize os seguintes pontos de extremidade para trabalhar com o Foundry Tools.
Qual endpoint você deve usar?
Escolha um ponto de extremidade com base em suas necessidades:
Use o ponto de extremidade dos serviços de IA do Azure para acessar Pesquisa Visual Computacional, Segurança de Conteúdo, Inteligência de Documentos, Linguagem, Tradução e Ferramentas do Token Foundry.
Ponto de extremidade do Foundry Tools: https://<your-resource-name>.cognitiveservices.azure.com/
Observação
Os pontos de extremidade usam o nome do recurso ou um subdomínio personalizado. Se sua organização configurou um subdomínio personalizado, substitua your-resource-name por your-custom-subdomain em todos os exemplos de ponto de extremidade.
Para Foundry Tools de Fala e Tradução, use os pontos de extremidade nas tabelas a seguir. Substitua os espaços reservados pelas informações do seu recurso.
Pontos de Extremidade de Fala
| Ferramenta de Fundição | Ponto final |
|---|---|
| Conversão de Fala em Texto (Padrão) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| Texto para Fala (Neural) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| Voz Personalizada | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Pontos de Extremidade de Tradução
| Ferramenta de Fundição | Ponto final |
|---|---|
| Tradução de texto | https://api.cognitive.microsofttranslator.com/ |
| Tradução de Documento | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
As seções a seguir incluem links de início rápido para os SDKs do Foundry Tools e informações de referência sobre os SDKs.
