Azure AI Projects SDK para .NET

Azure.AI.Projects (.NET)

SDK de alto nível para operações em projetos Azure AI Foundry, incluindo agentes, conexões, conjuntos de dados, implantações, avaliações e índices.

Instalação

dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

# Opcional: Para agentes versionados com extensões OpenAI
dotnet add package Azure.AI.Projects.OpenAI --prerelease

# Opcional: Para operações de agente de baixo nível
dotnet add package Azure.AI.Agents.Persistent --prerelease

Versões Atuais: GA v1.1.0, Preview v1.2.0-beta.5

Variáveis de Ambiente

PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>  # Obrigatório: endpoint do projeto Azure AI
MODEL_DEPLOYMENT_NAME=gpt-4o-mini  # Obrigatório: nome da implantação do modelo
CONNECTION_NAME=<your-connection-name>  # Opcional: nome da conexão do projeto
AI_SEARCH_CONNECTION_NAME=<ai-search-connection>  # Opcional: nome da conexão do Azure AI Search
AZURE_TOKEN_CREDENTIALS=prod  # Obrigatório apenas se DefaultAzureCredential for usado em produção

Autenticação

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

var endpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
// Desenvolvimento local: DefaultAzureCredential. Produção: defina AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<credential_especifica>
var credential = new DefaultAzureCredential(
    DefaultAzureCredential.DefaultEnvironmentVariableName
);
// Ou use uma credencial específica diretamente em produção:
// Consulte https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes
// var credential = new ManagedIdentityCredential();
AIProjectClient projectClient = new AIProjectClient(
    new Uri(endpoint), 
    credential);

Hierarquia do Cliente

AIProjectClient
├── Agents          → AIProjectAgentsOperations (agentes versionados)
├── Connections     → ConnectionsClient
├── Datasets        → DatasetsClient
├── Deployments     → DeploymentsClient
├── Evaluations     → EvaluationsClient
├── Evaluators      → EvaluatorsClient
├── Indexes         → IndexesClient
├── Telemetry       → AIProjectTelemetry
├── OpenAI          → ProjectOpenAIClient (preview)
└── GetPersistentAgentsClient() → PersistentAgentsClient

Fluxos de Trabalho Principais

1. Obter o Cliente de Agentes Persistentes

// Obtém o cliente de agentes de baixo nível a partir do cliente do projeto
PersistentAgentsClient agentsClient = projectClient.GetPersistentAgentsClient();

// Cria um agente
PersistentAgent agent = await agentsClient.Administration.CreateAgentAsync(
    model: "gpt-4o-mini",
    name: "Tutor de Matemática",
    instructions: "Você é um tutor pessoal de matemática.");

// Cria uma thread e executa
PersistentAgentThread thread = await agentsClient.Threads.CreateThreadAsync();
await agentsClient.Messages.CreateMessageAsync(thread.Id, MessageRole.User, "Resolva 3x + 11 = 14");
ThreadRun run = await agentsClient.Runs.CreateRunAsync(thread.Id, agent.Id);

// Polling até a conclusão
do
{
    await Task.Delay(500);
    run = await agentsClient.Runs.GetRunAsync(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);

// Obtém as mensagens
await foreach (var msg in agentsClient.Messages.GetMessagesAsync(thread.Id))
{
    foreach (var content in msg.ContentItems)
    {
        if (content is MessageTextContent textContent)
            Console.WriteLine(textContent.Text);
    }
}

// Limpeza
await agentsClient.Threads.DeleteThreadAsync(thread.Id);
await agentsClient.Administration.DeleteAgentAsync(agent.Id);

2. Agentes Versionados com Ferramentas (Preview)

using Azure.AI.Projects.OpenAI;

// Cria um agente com ferramenta de busca na web
PromptAgentDefinition agentDefinition = new(model: "gpt-4o-mini")
{
    Instructions = "Você é um assistente útil que pode pesquisar na web",
    Tools = {
        ResponseTool.CreateWebSearchTool(
            userLocation: WebSearchToolLocation.CreateApproximateLocation(
                country: "US",
                city: "Seattle",
                region: "Washington"
            )
        ),
    }
};

AgentVersion agentVersion = await projectClient.Agents.CreateAgentVersionAsync(
    agentName: "myAgent",
    options: new(agentDefinition));

// Obtém o cliente de respostas
ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);

// Cria uma resposta
ResponseResult response = responseClient.CreateResponse("Qual é a previsão do tempo em Seattle?");
Console.WriteLine(response.GetOutputText());

// Limpeza
projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

3. Conexões

// Lista todas as conexões
foreach (AIProjectConnection connection in projectClient.Connections.GetConnections())
{
    Console.WriteLine($"{connection.Name}: {connection.ConnectionType}");
}

// Obtém uma conexão específica
AIProjectConnection conn = projectClient.Connections.GetConnection(
    connectionName, 
    includeCredentials: true);

// Obtém a conexão padrão
AIProjectConnection defaultConn = projectClient.Connections.GetDefaultConnection(
    includeCredentials: false);

4. Implantações

// Lista todas as implantações
foreach (AIProjectDeployment deployment in projectClient.Deployments.GetDeployments())
{
    Console.WriteLine($"{deployment.Name}: {deployment.ModelName}");
}

// Filtra por editor
foreach (var deployment in projectClient.Deployments.GetDeployments(modelPublisher: "Microsoft"))
{
    Console.WriteLine(deployment.Name);
}

// Obtém uma implantação específica
ModelDeployment details = (ModelDeployment)projectClient.Deployments.GetDeployment("gpt-4o-mini");

5. Conjuntos de Dados

// Faz upload de um único arquivo
FileDataset fileDataset = projectClient.Datasets.UploadFile(
    name: "meu-dataset",
    version: "1.0",
    filePath: "data/training.txt",
    connectionName: connectionName);

// Faz upload de uma pasta
FolderDataset folderDataset = projectClient.Datasets.UploadFolder(
    name: "meu-dataset",
    version: "2.0",
    folderPath: "data/training",
    connectionName: connectionName,
    filePattern: new Regex(".*\\.txt"));

// Obtém um dataset
AIProjectDataset dataset = projectClient.Datasets.GetDataset("meu-dataset", "1.0");

// Exclui um dataset
projectClient.Datasets.Delete("meu-dataset", "1.0");

6. Índices

// Cria um índice do Azure AI Search
AzureAISearchIndex searchIndex = new(aiSearchConnectionName, aiSearchIndexName)
{
    Description = "Índice de Exemplo"
};

searchIndex = (AzureAISearchIndex)projectClient.Indexes.CreateOrUpdate(
    name: "meu-indice",
    version: "1.0",
    index: searchIndex);

// Lista índices
foreach (AIProjectIndex index in projectClient.Indexes.GetIndexes())
{
    Console.WriteLine(index.Name);
}

// Exclui um índice
projectClient.Indexes.Delete(name: "meu-indice", version: "1.0");

7. Avaliações

// Cria configuração de avaliação
var evaluatorConfig = new EvaluatorConfiguration(id: EvaluatorIDs.Relevance);
evaluatorConfig.InitParams.Add("deployment_name", BinaryData.FromObjectAsJson("gpt-4o"));

// Cria avaliação
Evaluation evaluation = new Evaluation(
    data: new InputDataset("<dataset_id>"),
    evaluators: new Dictionary<string, EvaluatorConfiguration> 
    { 
        { "relevance", evaluatorConfig } 
    }
)
{
    DisplayName = "Avaliação de Exemplo"
};

// Executa avaliação
Evaluation result = projectClient.Evaluations.Create(evaluation: evaluation);

// Obtém avaliação
Evaluation getResult = projectClient.Evaluations.Get(result.Name);

// Lista avaliações
foreach (var eval in projectClient.Evaluations.GetAll())
{
    Console.WriteLine($"{eval.DisplayName}: {eval.Status}");
}

8. Obter Cliente de Chat do Azure OpenAI

using Azure.AI.OpenAI;
using OpenAI.Chat;

ClientConnection connection = projectClient.GetConnection(typeof(AzureOpenAIClient).FullName!);

if (!connection.TryGetLocatorAsUri(out Uri uri) || uri is null)
    throw new InvalidOperationException("URI inválida.");

uri = new Uri($"https://{uri.Host}");

AzureOpenAIClient azureOpenAIClient = new AzureOpenAIClient(uri, new DefaultAzureCredential());
ChatClient chatClient = azureOpenAIClient.GetChatClient("gpt-4o-mini");

ChatCompletion result = chatClient.CompleteChat("Liste todas as cores do arco-íris");
Console.WriteLine(result.Content[0].Text);

Ferramentas de Agente Disponíveis

Ferramenta	Classe	Propósito
Interpretador de Código	CodeInterpreterToolDefinition	Executar código Python
Pesquisa de Arquivos	FileSearchToolDefinition	Pesquisar arquivos enviados
Chamada de Função	FunctionToolDefinition	Chamar funções personalizadas
Base do Bing	BingGroundingToolDefinition	Pesquisa na web via Bing
Azure AI Search	AzureAISearchToolDefinition	Pesquisar índices do Azure AI
OpenAPI	OpenApiToolDefinition	Chamar APIs externas
Azure Functions	AzureFunctionToolDefinition	Invocar Azure Functions
MCP	MCPToolDefinition	Ferramentas de Protocolo de Contexto de Modelo

Referência de Tipos Principais

Tipo	Propósito
AIProjectClient	Ponto de entrada principal
PersistentAgentsClient	Operações de agente de baixo nível
PromptAgentDefinition	Definição de agente versionado
AgentVersion	Instância de agente versionado
AIProjectConnection	Conexão com recurso Azure
AIProjectDeployment	Informações de implantação do modelo
AIProjectDataset	Metadados do conjunto de dados
AIProjectIndex	Metadados do índice de busca
Evaluation	Configuração e resultados de avaliação

Melhores Práticas

1. Use DefaultAzureCredential para autenticação em produção
2. Use métodos assíncronos (*Async) para todas as operações de E/S
3. Faça polling com atrasos adequados (500ms recomendado) ao aguardar execuções
4. Limpe os recursos — exclua threads, agentes e arquivos quando terminar
5. Use agentes versionados (via Azure.AI.Projects.OpenAI) para cenários de produção
6. Armazene IDs de conexão em vez de nomes para configurações de ferramentas
7. Use includeCredentials: true apenas quando as credenciais forem necessárias
8. Lide com paginação — use AsyncPageable<T> para operações de listagem

Tratamento de Erros

using Azure;

try
{
    var result = await projectClient.Evaluations.CreateAsync(evaluation);
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Erro: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
}

SDKs Relacionados

SDK	Propósito	Instalação
Azure.AI.Projects	Cliente de projeto de alto nível (este SDK)	dotnet add package Azure.AI.Projects
Azure.AI.Agents.Persistent	Operações de agente de baixo nível	dotnet add package Azure.AI.Agents.Persistent
Azure.AI.Projects.OpenAI	Agentes versionados com OpenAI	dotnet add package Azure.AI.Projects.OpenAI

Links de Referência

Recurso	URL
Pacote NuGet	https://www.nuget.org/packages/Azure.AI.Projects
Referência da API	https://learn.microsoft.com/dotnet/api/azure.ai.projects
Código Fonte no GitHub	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects
Exemplos	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects/samples