Tutorial: Criar um aplicativo Web agente no Serviço de Aplicativo do Azure com o LangGraph ou o Serviço do Foundry Agent (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 predefinido com memória e um conjunto de ferramentas CRUD para gerenciamento de tarefas (consulte o início rápido 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 usuário, o agente é invocado usando ainvoke() a mensagem do usuário e uma ID de thread para 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 as credenciais do Azure.
• Obtém um cliente OpenAI 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")

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
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 do Foundry, verifique se o botão de opção Novo Foundry no topo está definido como ativo e 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. A maneira mais fácil de obter o endpoint do Azure OpenAI ainda é a partir do portal clássico. Selecione o botão de opção Novo Foundry e, em seguida, OpenAI do Azure; depois, copie a URL no ponto de extremidade do OpenAI do Azure para uso posterior.

   

1. No portal do Foundry, verifique se o botão de opção Novo Foundry no topo está definido como ativo e crie um projeto.

2. Na página inicial, copie o ponto de extremidade do projeto para uso posterior.

3. Selecione Iniciar a criação>do agente de criação e siga o prompt.

4. No playground do novo agente, crie uma ferramenta OpenAPI para chamar seu aplicativo web selecionando Tools>Adicionar>Personalizado>Ferramenta OpenAPI>Criar. No painel Instalação, adicione uma ação com a ferramenta de especificação do OpenAPI. Use o esquema do OpenAPI obtido do aplicativo Web implantado e da autenticação anônima. Para conferir etapas detalhadas, veja Como usar a ferramenta de especificação do OpenAPI.

   O código do aplicativo já está configurado para incluir a url e a operationId do servidor, que são necessários para o agente. Para obter mais informações, consulte Connect to OpenAPI Specification.

5. Certifique-se de selecionar Salvar.

6. Selecione Experimentar no playground e teste seu agente do Foundry com prompts como "Mostrar-me todas as tarefas" e "Adicione uma tarefa".

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

1. No menu superior do novo portal do Foundry, selecione Operar e, em seguida, selecione Administrador. Na linha do projeto foundry, você deverá ver dois links. O que está na coluna Nome é o Recurso do Projeto Foundry, e o da coluna Recurso Pai é o Recurso Foundry.

   

2. Selecione o recurso Foundry no recurso Pai e, em seguida, selecione Gerenciar esse recurso no portal do Azure. No portal do Azure, você pode atribuir acesso baseado em função para o recurso ao aplicativo Web implantado.

3. Adicione a seguinte função à identidade gerenciada do App Service:

   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.

1. No menu superior do novo portal do Foundry, selecione Operar e, em seguida, selecione Administrador. Na linha do projeto foundry, você deverá ver dois links. O que está na coluna Nome é o Recurso do Projeto Foundry, e o da coluna Recurso Pai é o Recurso Foundry.

   

2. Selecione o recurso do projeto Foundry na coluna Nome e, em seguida, selecione Gerenciar esse recurso no portal do Azure. No portal do Azure, você pode atribuir acesso baseado em função para o recurso ao aplicativo Web implantado.

3. Adicione a seguinte função à identidade gerenciada do App Service:

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

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