Tutorial: Criar um aplicativo Web agente no Serviço de Aplicativo do Azure com o LangGraph ou o Serviço do Foundry Agent (Python)

Este tutorial demonstra como adicionar a funcionalidade de agente a um aplicativo CRUD FastAPI controlado por dados. Ele faz isso usando duas abordagens diferentes: LangGraph e Foundry Agent Service.

Se seu aplicativo Web já tiver recursos úteis, como compras, reservas de hotéis ou gerenciamento de dados, é relativamente simples adicionar funcionalidade de agente ao seu aplicativo Web encapsulando essas funcionalidades em um plug-in (para LangGraph) ou como um ponto de extremidade OpenAPI (para o Serviço do Foundry Agent). Neste tutorial, você começará com um aplicativo simples de lista de tarefas pendentes. Ao final, você poderá criar, atualizar e gerenciar tarefas com um agente em um aplicativo do Serviço de Aplicativo.

LangGraph

Serviço do Foundry Agent

O LangGraph e o Foundry Agent Service permitem criar aplicativos Web agente com recursos controlados por IA. O LangGraph é semelhante ao Microsoft Agent Framework e é um SDK. A seguinte tabela mostra algumas das considerações e compensações:

Consideração	LangGraph ou Microsoft Agent Framework	Serviço de Agente da Fábrica
Performance	Rápido (executado localmente)	Mais lento (gerenciado, serviço remoto)
Desenvolvimento	Código completo, controle máximo	Pouco código, integração rápida
Testing	Testes manuais/de unidade no código	Playground interno para testes rápidos
Escalabilidade	Gerenciado pelo aplicativo	Gerenciado pelo Azure, escalado automaticamente
Proteções de segurança	Implementação personalizada necessária	Segurança e moderação de conteúdo embutidas
Identidade	Implementação personalizada necessária	ID de agente integrado e autenticação
Enterprise	Integração personalizada necessária	Implantação integrada do Microsoft 365/Teams e chamadas integradas de ferramentas no Microsoft 365.

Neste tutorial, você aprenderá como:

• Converter a funcionalidade de um aplicativo existente em um plug-in para o LangGraph.
• Adicionar o plug-in a um agente do LangGraph e usá-lo em um aplicativo Web.
• Converta a funcionalidade de aplicativo existente em um endpoint OpenAPI para o Foundry Agent Service.
• Chame um agente do Foundry em um aplicativo Web.
• Atribuir as permissões necessárias para a conectividade da identidade gerenciada.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa – Crie uma conta gratuitamente.
• Uma conta do GitHub para usar o GitHub Codespaces – Saiba mais sobre o GitHub Codespaces.

Abrir a amostra com o Codespaces

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

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

2. Selecione o botão Código, selecione a guia Codespaces e selecione Criar codespace em main.

3. Aguarde alguns instantes para que o Codespace seja inicializado. Quando ele estiver pronto, você verá um ambiente de desenvolvimento totalmente configurado no 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 você receber a mensagem Seu aplicativo em execução na porta 3000 está disponível, selecione Abrir no Navegador e adicione algumas tarefas.

   Os agentes não estão totalmente configurados, portanto, ainda não funcionam. Você vai configurá-los mais tarde.

Revisar o código do agente

As duas abordagens usam o mesmo padrão de implementação, em que o agente é inicializado na inicialização do aplicativo e responde às mensagens do usuário por solicitações POST.

LangGraph

O LangGraphTaskAgent é inicializado no construtor em src/agents/langgraph_task_agent.py. O código de inicialização faz o seguinte:

• Configura o cliente AzureChatOpenAI usando variáveis de ambiente.
• Cria o agente ReAct predefinido com memória e um conjunto de ferramentas CRUD para gerenciamento de tarefas (consulte o início rápido do LangGraph).
• Seleciona uma thread de conversa gerenciada pelo servidor para a amostra autenticada.

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)

Ao processar mensagens de usuário, o agente invoca ainvoke() com o ID da thread gerenciada pelo servidor:

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

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

A solicitação do navegador contém apenas a mensagem. Ele não pode selecionar outro thread fornecendo um identificador de sessão ou conversa.

Serviço do Foundry Agent

O FoundryTaskAgent é inicializado no construtor de src/agents/foundry_task_agent.py. O código de inicialização faz o seguinte:

• Cria um AIProjectClient usando as credenciais do Azure.
• Obtém um cliente OpenAI do cliente do projeto.
• Recupera o agente da Foundry pelo nome.
• Cria uma conversa autenticada gerenciada no servidor.

# 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

O ID de conversa do Foundry permanece no servidor e não é retornado nem aceito pelo navegador. Ambas as implementações do agente mantêm o estado da conversa na memória do processo, portanto o exemplo de aprendizado implantado executa um worker do Gunicorn. Se você aumentar o número de trabalhadores ou reduzir a escala do app, use um armazenamento de conversas externo para compartilhar o estado entre trabalhadores e instâncias.

Esse código de inicialização não define nenhuma funcionalidade para o agente, pois você normalmente compilaria o agente no portal do Foundry. Como parte do cenário exemplificado, ele também segue o padrão OpenAPI mostrado em Adicionar um aplicativo do Serviço de Aplicativo como uma ferramenta no Foundry Agent Service (Python) e disponibiliza sua funcionalidade CRUD como um endpoint OpenAPI. Isso permite adicioná-lo ao agente posteriormente como uma ferramenta invocável.

O código do OpenAPI é definido em src/routes/api.py. Por exemplo, a rota "GET /tasks" define um parâmetro personalizado operation_id , conforme exigido pela ferramenta de especificação OpenAPI no Microsoft Foundry, e description ajuda o agente a determinar como chamar a API:

@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)}")

Ao processar mensagens de usuário, o agente é invocado adicionando a mensagem do usuário à conversa e chamando responses.create() com a referência do agente:

# 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 template de CLI para Desenvolvedores do Azure (AZD), que cria um aplicativo de Serviço de Aplicativos e implanta sua aplicação de exemplo. A identidade gerenciada atribuída ao sistema de App Service é mantida para chamadas de IA do Azure de saída. Uma identidade gerenciada separada atribuída pelo usuário e uma credencial federada permitem que a autenticação do App Service atue como a aplicação Microsoft Entra gerada sem um segredo cliente.

1. No terminal, faça login no Azure usando o Azure Developer CLI:

   azd auth login
   

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

2. Implante o aplicativo Serviço de Aplicativo do Azure usando o modelo AZD:

   azd up
   

3. Quando solicitado, dê as seguintes respostas:

   Pergunta	Resposta
   Insira um novo nome de ambiente:	Digite um nome exclusivo.
   Selecione uma assinatura do Azure a ser usada:	Selecione a assinatura.
   Escolha o grupo de recursos a ser usado:	Selecione Criar um grupo de recursos.
   Escolha uma localização na qual o grupo de recursos será criado:	Selecione Suécia Central.
   Insira um nome para o novo grupo de recursos:	Digite ENTER.

4. Na saída do AZD, localize a URL do seu aplicativo e navegue até ela no navegador. Também copie o valor do público da identidade gerenciada do Foundry OpenAPI para usar mais tarde. A saída tem esta aparência:

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

5. Quando a Microsoft solicitar, faça login usando uma conta no tenant de implantação e verifique se a lista de tarefas está carregada.

6. No mesmo navegador autenticado, anexe /openapi.json ao endpoint do App Service. Copie ou salve o esquema OpenAPI gerado para depois.

   Observação

   A autenticação por App Service retorna um redirecionamento HTTP 302 para requisições de navegador não autenticadas. Este exemplo contém tanto uma interface de navegador quanto APIs, então o redirecionamento oferece uma experiência de login utilizável. Aplicativos apenas de API geralmente usam HTTP 401.

Criar e configurar o recurso microsoft foundry

LangGraph

1. No portal da Foundry, crie um projeto.

2. Implante um modelo de sua escolha (consulte o Início Rápido do Microsoft Foundry: Criar recursos).

3. Na parte superior da área de testes do modelo, copie o nome dele.

4. Na página inicial, copie o endpoint do Azure OpenAI para depois.

Serviço do Foundry Agent

1. No portal da Foundry, crie um projeto.

2. Na página inicial, copie o endpoint do Project para uso posterior.

3. Selecione Começar a construir e siga o prompt.

4. Selecione ferramentas Adicionar>>ferramentas>Ferramenta OpenAPI personalizada>>Criar. No painel Instalação, adicione uma ação com a ferramenta de especificação do OpenAPI.

5. Cole o esquema OpenAPI que você copiou do aplicativo App Service autenticado.

6. Para o método autenticação, selecione Identidade gerenciada.

7. Para Audiência, cole o valor de audiência de identidade gerenciada do Foundry OpenAPI a partir da saída do AZD. Ele se assemelha a:

   api://<generated-client-id>
   

8. Salve a ferramenta e o agente.

Permita que o recurso pai do Foundry chame a API da tarefa

1. No portal Foundry, selecione Gerenciar no menu superior.

2. Em Detalhes do projeto, selecione o recurso pai do seu projeto e selecione Abrir no portal do Azure.

3. Copie o ID do Objeto (principal) da identidade atribuída ao sistema. Encontre essa identidade no Microsoft Entra ID e copie o ID da Aplicação dele. Para obter etapas detalhadas, consulte Encontrar a identidade do recurso Foundry pai.

4. No terminal Codespace, armazene o ID da aplicação no ambiente AZD e atualize a configuração de autenticação do App Service:

   azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
   azd provision
   

Atribuir as permissões necessárias

LangGraph

1. No portal Foundry, selecione Gerenciar no menu superior.

2. Em Detalhes do projeto, selecione o recurso pai do seu projeto e selecione Abrir no portal do Azure.

   Pelo portal Azure, você pode atribuir acesso baseado em função para o recurso.

3. Adicione a seguinte função tanto à identidade gerenciada do aplicativo do App Service quanto ao usuário que você usa com az login:

   Recurso de destino	Função necessária	Necessário para
   Fundição	Usuário dos Serviços Cognitivos OpenAI	O serviço de conclusão de chat no Microsoft Agent Framework.

   Para obter instruções, confira Atribuir funções do Azure usando o portal do Azure.

Serviço do Foundry Agent

1. No portal Foundry, selecione Gerenciar no menu superior.

2. Nos detalhes do Project, selecione Abrir no portal do Azure.

   Pelo portal do Azure, você pode atribuir acesso baseado em funções para o projeto.

3. Adicione a seguinte função tanto à identidade gerenciada do aplicativo do App Service quanto ao usuário que você usa com az login:

   Recurso de destino	Função necessária	Necessário para
   Projeto de fundimento	Usuário do Foundry	Lendo e chamando o agente do Foundry.

   Para obter instruções, confira Atribuir funções do Azure usando o portal do Azure.

Importante

Essa atribuição de função controla a chamada de saída do App Service para o projeto Foundry. A chamada OpenAPI hospedada usa a identidade gerenciada atribuída ao sistema de recursos do Foundry, que você adicionou à lista de permissões de autenticação do App Service.

Configurar variáveis de conexão no aplicativo de exemplo

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

   LangGraph

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

   Observação

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

   Serviço do Foundry Agent

   Variable	Description
   AZURE_AI_FOUNDRY_PROJECT_ENDPOINT	Ponto final do projeto Microsoft Foundry no novo portal do Foundry.
   AZURE_AI_FOUNDRY_AGENT_NAME	Nome do agente (do playground do agente no portal do Foundry).

   Observação

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

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

2. Entre no Azure com a CLI do Azure:

   az login
   

   Assim, a biblioteca de clientes da Identidade do Azure no código de exemplo poderá receber 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ê receber a mensagem 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 do Agente Foundry: Selecione Agente Foundry e peça ao agente para criar uma tarefa. O agente Foundry remoto chama o endpoint implantado e protegido /api/tasks usando identidade gerenciada.

   A tarefa criada pelo agente Foundry aparece na instância do App Service implantado, não no banco de dados SQLite local. A ferramenta OpenAPI do Foundry sempre utiliza a URL do servidor embutida no esquema OpenAPI.

6. De volta ao codespace do GitHub, implante as alterações do aplicativo.

   azd up
   

7. Navegue novamente até o aplicativo implantado e teste ambos os agentes de chat. O navegador envia apenas texto de mensagem; não envia um ID de sessão ou ID de conversa para nenhum dos agentes.

LangGraph

Serviço do Foundry Agent

Perguntas frequentes

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

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

Esta instrução se aplica ao caminho Foundry Agent Service neste tutorial. Ele não altera as implementações do LangGraph, Kernel semântico ou Microsoft Agent Framework mostradas na outra aba.

Crie ou selecione uma base de conhecimento do Foundry IQ e, em seguida, conecte a base de conhecimento ao agente do serviço de agente do Foundry. A conexão é exposta ao agente como uma ferramenta de conhecimento gerenciada do MCP.

O código do App Service continua a invocar o mesmo agente pelo nome através de seu cliente existente no Foundry e agent_reference. O aplicativo 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 exibir fontes, processe as anotações de citação retornadas pelo agente.

Limpar os recursos

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

azd down --purge

O hook AZD postdown também exclui o aplicativo do Microsoft Entra no nível do locatário criado para a autenticação do App Service.

Depois, exclua o recurso do Foundry se você o criou separadamente.

Mais recursos

• Integrar a IA aos seus aplicativos do Serviço de Aplicativo do Azure
• O que é o Serviço de Agente da Fábrica?
• LangGraph – Início Rápido
• Biblioteca de clientes do Azure AI Projects para Python