Microsoft Agent Framework Basic Sample

Exemplo mínimo de aplicação ASP.NET usando o Microsoft Agent Framework com Azure AI Agents (Persistent Agents).

Visão geral

Este projeto mostra uma aplicação Web minimalista em .NET 9 que integra com Azure AI Agents (Persistent Agents) usando a biblioteca Azure.AI.Agents.Persistent e os pacotes Microsoft.Agents.AI / Microsoft.Agents.AI.AzureAI.

Ele oferece dois endpoints mínimos:

• POST /ai-agent — cria um agente persistente (recebe name e instructions por query string).
• GET /ai-agent/run — executa uma thread em um agente já criado (recebe agentId, userInput por query string).

O código principal está em src/MicrosoftAgentFrameworkBasic/.

Requisitos

• .NET 9 SDK
• Uma instância compatível de Azure AI Services (Agent endpoint) com credenciais configuradas para DefaultAzureCredential (Managed Identity, Azure CLI, Visual Studio, ou variáveis de ambiente).

Pacotes usados (definidos em MicrosoftAgentFrameworkBasic.csproj):

• Azure.AI.Agents.Persistent
• Azure.Identity
• Microsoft.Agents.AI
• Microsoft.Agents.AI.AzureAI
• Microsoft.AspNetCore.OpenApi
• Scalar.AspNetCore

Configuração

As configurações ficam em appsettings.json / appsettings.Development.json na seção AzureAiSettings:

"AzureAiSettings": {
  "Uri": "https://<seu-endpoint>.services.ai.azure.com/api/projects/default",
  "Model": "<modelo>"
}

O projeto usa DefaultAzureCredential. Para desenvolvimento local você pode autenticar com az login (Azure CLI) ou definir as variáveis de ambiente apropriadas.

Como executar

1. Abra um terminal na raiz do repositório.
2. Navegue até a pasta do projeto:

cd src/MicrosoftAgentFrameworkBasic

3. Restaure e execute:

dotnet restore
dotnet run

Em ambiente de desenvolvimento, a aplicação habilita OpenAPI e uma referência de API através de Scalar.AspNetCore.

Endpoints

• Criar agente

  POST /ai-agent?name={name}&instructions={instructions}

  Retorna o agentId criado.

• Rodar agente

  GET /ai-agent/run?agentId={agentId}&userInput={texto}

  Retorna a resposta do agente para o userInput informado.

Estrutura do projeto

• Program.cs — bootstrap da aplicação e registro dos serviços.
• Application/AzureAiSettings.cs — classe de configuração para AzureAiSettings.
• Application/Service.cs — lógica que interage com PersistentAgentsClient para criar/rodar agentes.
• Application/Module.cs — define os endpoints mínimos.

Testes e validação rápida

Não há testes automatizados incluídos neste repositório. Para validar manualmente:

1. Execute a aplicação.
2. Use curl ou Postman para chamar os endpoints descritos acima.

Exemplo rápido (substitua valores):

# criar agente
curl -X POST "https://localhost:5001/ai-agent?name=Joker&instructions=You%20are%20good%20at%20telling%20jokes."

# rodar agente (substitua AGENT_ID e texto)
curl "https://localhost:5001/ai-agent/run?agentId=AGENT_ID&userInput=Tell%20me%20a%20joke"

Melhorias sugeridas

• Validar e propagar erros do cliente Azure para respostas HTTP mais claras.
• Adicionar testes unitários e integração com mocks do PersistentAgentsClient.
• Implementar autenticação/autorização nos endpoints HTTP.

Licença

Licença MIT.

---