Tutorial: Constrói uma aplicação web agente no Serviço de Aplicações do Azure com LangGraph ou Foundry Agent Service (Python)

Este tutorial demonstra como adicionar capacidade de agente a um aplicativo CRUD FastAPI controlado por dados existente. Faz isto usando duas abordagens diferentes: LangGraph e Foundry Agent Service.

Se a sua aplicação web já tem funcionalidades úteis, como compras, reservas de hotel ou gestão de dados, é relativamente simples adicionar funcionalidades de agente à sua aplicação web, envolvendo essas funcionalidades num plugin (para LangGraph) ou como endpoint OpenAPI (para Foundry Agent Service). Neste tutorial, você começa com um aplicativo de lista de to-do simples. No final, você poderá criar, atualizar e gerenciar tarefas com um agente em um aplicativo do Serviço de Aplicativo.

Tanto o LangGraph como o Foundry Agent Service permitem-lhe construir aplicações web agentes com capacidades baseadas em IA. O LangGraph é semelhante ao Microsoft Agent Framework e é um SDK. A tabela a seguir mostra algumas das considerações e compensações:

Neste tutorial, aprenderás como:

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa - Crie uma conta gratuitamente.
• Conta do GitHub para usar o GitHub Codespaces - Saiba mais sobre o GitHub Codespaces.

Abra o exemplo com Codespaces

A maneira mais fácil de começar é usando o GitHub Codespaces, que fornece um ambiente de desenvolvimento completo com todas as ferramentas necessárias pré-instaladas.

1. Navegue até o repositório GitHub em https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-python.

2. Selecione o botão Código , selecione a guia Espaços de código e selecione Criar espaço de código na principal.

3. Aguarde alguns instantes até que o Codespace seja inicializado. Quando estiver pronto, você verá um ambiente de desenvolvimento totalmente configurado em seu navegador.

4. Execute o aplicativo localmente:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   uvicorn src.app:app --host 0.0.0.0 --port 3000
   

5. Quando vir que a sua aplicação em execução na porta 3000 está disponível, selecione Abrir no Browser e adicione algumas tarefas.

   Os agentes não estão totalmente configurados, por isso ainda não funcionam. Você os configurará mais tarde.

Revise o código do agente

Ambas as abordagens usam o mesmo padrão de implementação, onde o agente é inicializado no início do aplicativo e responde às mensagens do usuário por solicitações POST.

self.memory = InMemorySaver()
# App Service authentication protects this sample, which intentionally
# keeps one server-managed conversation thread per worker process.
self.thread_id = "authenticated-conversation"

try:
    endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    deployment_name = os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME")
    
    if not endpoint or not deployment_name:
        print("Azure OpenAI configuration missing for LangGraph agent")
        return
    
    # Initialize Azure OpenAI client
    credential = DefaultAzureCredential()
    azure_ad_token_provider = get_bearer_token_provider(
        credential, "https://cognitiveservices.azure.com/.default"
    )
    
    self.llm = AzureChatOpenAI(
        azure_endpoint=endpoint,
        azure_deployment=deployment_name,
        azure_ad_token_provider=azure_ad_token_provider,
        api_version="2024-10-21"
    )
    
    # Define tools
    tools = [
        self._create_task_tool(),
        self._get_tasks_tool(),
        self._get_task_tool(),
        self._update_task_tool(),
        self._delete_task_tool()
    ]
    
    # Create the agent
    self.agent = create_react_agent(self.llm, tools, checkpointer=self.memory)

config = {"configurable": {"thread_id": self.thread_id}}

# Process the message
result = await self.agent.ainvoke(
    {"messages": [("user", message)]},
    config=config
)

# Create the project client using Azure credentials
self.project_client = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential()
)

# Get the OpenAI client for conversation operations
self.openai_client = self.project_client.get_openai_client()

# Find the existing agent by name
self.agent = self.project_client.agents.get(agent_name)

if not self.agent:
    print(f"Agent with name '{agent_name}' not found in project.")
    return
            
# App Service authentication protects this sample, which intentionally
# keeps one server-managed conversation per worker process.
conversation = self.openai_client.conversations.create()
self.conversation_id = conversation.id

@router.get(
    "/tasks",
    response_model=List[TaskItem],
    operation_id="getAllTasks",
    description="Retrieve all tasks in the task list."
)
async def get_all_tasks():
    """Get all tasks"""
    try:
        tasks = await task_service.get_all_tasks()
        return tasks
    except Exception as e:
        print(f"Error getting tasks: {e}")
        import traceback
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=f"Failed to get tasks: {str(e)}")

# Add user message to the conversation
await asyncio.to_thread(
    self.openai_client.conversations.items.create,
    conversation_id=self.conversation_id,
    items=[{"type": "message", "role": "user", "content": message}],
)

# Create response using the agent
response = await asyncio.to_thread(
    self.openai_client.responses.create,
    conversation=self.conversation_id,
    extra_body={"agent": {"name": self.agent.name, "type": "agent_reference"}},
    input="",
)

Implantar o aplicativo de exemplo

O repositório de exemplo contém um modelo Azure Developer CLI (AZD), que cria uma aplicação de Serviços de Aplicação e implementa a sua aplicação de exemplo. A identidade gerida atribuída pelo sistema de App Service é mantida para chamadas de IA do Azure de saída. Uma identidade gerida separada atribuída pelo utilizador e uma credencial de identidade federada permitem que a autenticação de Serviços de Aplicações atue como a aplicação Microsoft Entra gerada sem um segredo do cliente.

1. No terminal, inicia sessão no Azure usando o Azure Developer CLI:

   azd auth login
   

   Siga as instruções para concluir o processo de autenticação.

2. Implemente a aplicação Serviço de Aplicações do Azure usando o modelo AZD:

   azd up
   

3. Quando solicitado, dê as seguintes respostas:

   Question	Resposta
   Insira um novo nome de ambiente:	Escreva um nome exclusivo.
   Selecione uma Assinatura do Azure para usar:	Selecione uma subscrição.
   Escolha um grupo de recursos para usar:	Selecione Criar um novo grupo de recursos.
   Selecione um local para criar o grupo de recursos em:	Selecione Suécia Central.
   Insira um nome para o novo grupo de recursos:	Digite Enter.

4. Na saída AZD, localize a URL do seu aplicativo e navegue até ela no navegador. Copie também o valor da audiência da identidade gerida do Foundry OpenAPI para utilizar mais tarde. O resultado tem o seguinte aspeto:

    Deploying services (azd deploy)
   
      (✓) Done: Deploying service web
      - Endpoint: <URL>
   
    Foundry OpenAPI managed identity audience:
        api://<generated-client-id>
    

5. Quando a Microsoft te pedir, inicia sessão usando uma conta no tenant de implementação e verifica se a lista de tarefas está carregada.

6. No mesmo navegador autenticado, anexe /openapi.json ao endpoint do Serviço de Aplicações. Copie ou guarde o esquema OpenAPI gerado para mais tarde.

   Observação

   A autenticação do App Service devolve um redirecionamento HTTP 302 para pedidos de navegador não autenticados. Este exemplo contém tanto uma interface de navegador como APIs, pelo que o redirecionamento proporciona uma experiência de login utilizável. As aplicações só de API normalmente usam antes o HTTP 401.

Crie e configure o recurso Microsoft Foundry

Atribuir permissões necessárias

Configurar variáveis de conexão em seu aplicativo de exemplo

1. Abra .env. Usando os valores que copiou anteriormente do portal Foundry, configure as seguintes variáveis:

   • LangGraph
   • Serviço de Agente Foundry

   Variable	Description
   AZURE_OPENAI_ENDPOINT	Azure OpenAI endpoint (copiado da página inicial do portal Foundry).
   AZURE_OPENAI_DEPLOYMENT_NAME	Nome do modelo na implementação (copiado da área de testes do modelo no novo portal da Foundry).

   Observação

   Para manter o tutorial simples, você usará essas variáveis em .env em vez de substituí-las pelas configurações do aplicativo no Serviço de Aplicativo.

   Observação

   Para manter o tutorial simples, você usará essas variáveis em .env em vez de substituí-las pelas configurações do aplicativo no Serviço de Aplicativo.

   Os valores em .env configuram a ligação de saída da aplicação para o Foundry. AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID configura a ligação OpenAPI de entrada separada entre o Foundry e o App Service e é armazenada no ambiente AZD.

2. Entre no Azure com a CLI do Azure:

   az login
   

   Isso permite que a biblioteca de cliente do Azure Identity no código de exemplo receba um token de autenticação para o usuário conectado. Lembre-se de que você adicionou a função necessária para esse usuário anteriormente.

3. Execute o aplicativo localmente:

   source venv/bin/activate
   uvicorn src.app:app --host 0.0.0.0 --port 3000
   

4. Quando você vir Seu aplicativo em execução na porta 3000 está disponível, selecione Abrir no navegador.

5. Valide ambos os pivôs separadamente:

   • LangGraph:Selecione LangGraph Agent e peça ao agente para criar uma tarefa. O LangGraph chama a ferramenta de tarefas em processo.
   • Serviço Foundry Agent: Selecione Foundry Agent e peça ao agente para criar uma tarefa. O agente Foundry remoto invoca o endpoint /api/tasks implementado e protegido, utilizando a identidade gerida.

   A tarefa que o agente Foundry cria aparece na instância do App Service implementada, não na base de dados SQLite local. A ferramenta Foundry OpenAPI utiliza sempre a URL do servidor embutida no esquema OpenAPI.

6. De volta ao espaço de código do GitHub, implante as alterações do seu aplicativo.

   azd up
   

7. Navega novamente até à aplicação implementada e testa ambos os agentes de chat. O navegador envia apenas mensagens de texto; não envia um ID de sessão nem de conversa para nenhum dos agentes.

Perguntas mais frequentes

• Como posso adicionar geração aumentada de recuperação (RAG) ao agente da Foundry?

Como posso adicionar geração aumentada de recuperação (RAG) ao agente da Foundry?

Esta orientação aplica-se ao caminho Foundry Agent Service neste tutorial. Não altera as implementações do LangGraph, Kernel Semântico ou Microsoft Agent Framework mostradas no outro separador.

Crie ou selecione uma base de conhecimento Foundry IQ e depois ligue essa base ao agente do Serviço de Agentes da Foundry. A conexão é apresentada ao agente como uma ferramenta de conhecimento MCP gerida.

O código do App Service continua a invocar o mesmo agente pelo respetivo nome através do cliente Foundry existente e agent_reference. A aplicação web não precisa de uma integração direta com Pesquisa de IA do Azure nem de um cliente MCP próprio. Se a interface mostrar as fontes, processe as anotações de citação devolvidas pelo agente.

Limpeza de recursos

Quando terminar de usar o aplicativo, você poderá excluir os recursos do Serviço de Aplicativo para evitar incorrer em custos adicionais:

azd down --purge

O gancho AZD postdown também elimina a aplicação Microsoft Entra ao nível do tenant criada para autenticação de Serviços de Aplicações.

Depois, apaga o recurso Foundry se o criaste separadamente.

Mais recursos

• Integre a IA em seus aplicativos do Serviço de Aplicativo do Azure
• O que é o Foundry Agent Service?
• LangGraph - Guia de início rápido
• Biblioteca cliente Azure AI Projects para Python