Tutorial: Constrói uma aplicação web agente no Azure App Service com LangGraph ou Foundry Agent Service (Python)

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 pré-construído com memória e um conjunto de ferramentas CRUD para gestão de tarefas (ver quickstart do LangGraph).

# 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)
print("LangGraph Task Agent initialized successfully")

Ao processar mensagens de utilizador, o agente é invocado usando ainvoke() com a mensagem do utilizador e um ID de thread para garantir a continuidade da conversa.

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

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 credenciais do Azure.
• Obtém um cliente OpenAI a partir do cliente do projeto.
• Recupera o agente da Foundry pelo nome.
• Cria uma nova conversa para a sessão.

# 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
            
# Create a conversation for this session
conversation = self.openai_client.conversations.create()
self.conversation_id = conversation.id
print("Foundry agent initialized successfully")

Este código de inicialização não define qualquer funcionalidade para o agente, porque normalmente construiria o agente no portal Foundry. Como parte do cenário de exemplo, também segue o padrão OpenAPI mostrado em Adicionar uma aplicação App Service como uma ferramenta no Foundry Agent Service (Python), e disponibiliza a sua funcionalidade CRUD como um endpoint OpenAPI. Isso permite adicioná-lo ao agente mais tarde como uma ferramenta chamável.

O código 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 utilizador, o agente é invocado adicionando a mensagem do utilizador à conversa e ligando responses.create() com a referência do agente:

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

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

1. No portal da Foundry, certifique-se de que o botão de radio superior da New Foundry está ativado e crie um projeto.

2. Implemente um modelo à sua escolha (veja Microsoft Foundry Quickstart: Criar recursos).

3. Do topo do parque de diversões de modelos, copie o nome do modelo.

4. A forma mais fácil de obter o endpoint Azure OpenAI continua a ser através do portal clássico. Selecione o botão de opção New Foundry, depois Azure OpenAI, e depois copie o URL no Azure OpenAI endpoint para mais tarde.

   

1. No portal da Foundry, certifique-se de que o botão de radio superior da New Foundry está ativado e crie um projeto.

2. Na página inicial, copie o endpoint do Projeto para usar mais tarde.

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

4. Na área de teste do novo agente, crie uma ferramenta personalizada OpenAPI para chamar a sua aplicação web selecionando Ferramentas>Adicionar>ferramenta personalizada OpenAPI>>Criar. No painel Configuração , adicione uma ação com a ferramenta de especificação OpenAPI. Use o esquema OpenAPI que você obtém do aplicativo Web implantado e da autenticação anônima . Para obter etapas detalhadas, consulte Como usar a ferramenta de especificação OpenAPI.

   O código do url aplicativo já está configurado para incluir o servidor e operationIdo , que são necessários para o agente. Para mais informações, consulte Ligar à Especificação OpenAPI.

5. Certifica-te de selecionar Guardar.

6. Selecione Experimentar no playground e teste o seu agente Foundry com prompts como "Mostra-me todas as tarefas" e "Por favor, adiciona uma tarefa."

   Se você receber uma resposta válida, o agente está fazendo chamadas de ferramenta para o ponto de extremidade OpenAPI em seu aplicativo Web implantado.

1. No menu superior do novo portal da Foundry, selecione Operar, depois selecione Administrador. Na fila do seu projeto Foundry, deve ver dois links. O elemento na coluna Nome é o recurso do projeto Foundry, e o elemento na coluna Recurso Pai é o recurso Foundry.

   

2. Selecione o recurso Foundry no recurso Pai e depois selecione Gerir este recurso no portal Azure. A partir do portal Azure, pode atribuir acesso baseado em funções para o recurso à aplicação web implementada.

3. Adicione o seguinte papel para a identidade gerida da aplicação App Service:

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

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

1. No menu superior do novo portal da Foundry, selecione Operar, depois selecione Administrador. Na fila do seu projeto Foundry, deve ver dois links. O elemento na coluna Nome é o recurso do projeto Foundry, e o elemento na coluna Recurso Pai é o recurso Foundry.

   

2. Selecione o recurso do projeto Foundry na coluna Nome e depois selecione Gerir este recurso no portal Azure. A partir do portal Azure, pode atribuir acesso baseado em funções para o recurso à aplicação web implementada.

3. Adicione o seguinte papel para a identidade gerida da aplicação App Service:

   Recurso de destino	Função obrigatória	Necessário para
   Projeto Foundry	Utilizador do Azure AI	A ler e a ligar para o agente da Foundry.

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