Adicionar um aplicativo do App Service como uma ferramenta no Serviço do Agente do Foundry (Python)

Neste tutorial, você aprenderá a expor a funcionalidade de um aplicativo FastAPI por meio do OpenAPI, adicioná-la como uma ferramenta ao Serviço do Foundry Agent e interagir com seu aplicativo usando linguagem natural no playground de agentes.

Se seu aplicativo Web já tiver recursos úteis, como compras, reservas de hotéis ou gerenciamento de dados, é fácil disponibilizar esses recursos para um agente de IA no Serviço do Foundry Agent. Ao simplesmente adicionar um esquema OpenAPI ao seu aplicativo, você permite que o agente entenda e use os recursos do aplicativo quando ele responder aos prompts dos usuários. Isso significa que tudo o que seu aplicativo pode fazer, seu agente de IA também pode fazer, com esforço mínimo além de criar um ponto de extremidade OpenAPI para seu aplicativo. Neste tutorial, você começa com um aplicativo de classificação de restaurante simples. No final, você poderá ver as classificações de restaurantes, bem como criar novos restaurantes e novas críticas com um agente por meio da IA de conversa.

Pré-requisitos

Este tutorial pressupõe que você esteja trabalhando com o exemplo usado na implantação de um aplicativo Web Python FastAPI com PostgreSQL no Azure.

No mínimo, abra o aplicativo de exemplo no GitHub Codespaces e implante o aplicativo executando azd up.

Adicionar a funcionalidade OpenAPI ao seu aplicativo Web

O FasAPI já contém a funcionalidade OpenAPI no caminho padrão /openapi.json. Você só precisa fazer algumas alterações no código existente para torná-lo chamado remotamente por um agente.

1. Abra src/fastapi_app/app.py e localize a linha 24, em que o aplicativo FastAPI é declarado. Substitua app = FastAPI() pelo seguinte código:

   if os.getenv("WEBSITE_HOSTNAME"):
       server_url = f"https://{os.getenv('WEBSITE_HOSTNAME')}"
   else:
       server_url = "http://localhost:8000"
   app = FastAPI(
       title="Restaurant Review API",
       version="1.0.0",
       description="Can show restaurant ratings HTML and add new restaurants and reviews.",
       servers=[{"url": server_url}],
   )
   

   Esse código adiciona metadados ao esquema OpenAPI, como title e description. Mais importante, ele adiciona a URL do servidor do ponto de extremidade da API.

2. Abra src/fastapi_app/app.py, adicione operation_id às APIs GET / e /details/{id}. Essas duas APIs retornam documentos HTML que um agente de IA pode analisar. Para todas as outras APIs, adicione o parâmetro include_in_schema=False.

   @app.get("/", response_class=HTMLResponse, operation_id="getRestaurantsWithRatingsHtml")
       ...    
   
   @app.get("/create", response_class=HTMLResponse, include_in_schema=False)
       ...    
   
   @app.post("/add", response_class=RedirectResponse, include_in_schema=False)
       ...
   
   @app.get("/details/{id}", response_class=HTMLResponse, operation_id="getRestaurantDetails")
       ...    
   
   @app.post("/review/{id}", response_class=RedirectResponse, include_in_schema=False)
       ...
   

   Você usa include_in_schema=False para excluir GET /create, POST /add e POST /review/{id} porque eles fazem parte da funcionalidade baseada em formulário, enquanto o agente de IA precisa enviar dados JSON.

3. Para adicionar o restaurante e adicionar a funcionalidade de revisão usando JSON, adicione o seguinte código:

   from typing import Optional
   from fastapi import Body, HTTPException
   
   @app.post("/api/restaurants", response_model=Restaurant, status_code=status.HTTP_201_CREATED, operation_id="createRestaurant")
   async def create_restaurant_json(
       name: str = Body(...),
       street_address: str = Body(...),
       description: str = Body(...),
       session: Session = Depends(get_db_session),
   ):
       restaurant = Restaurant(name=name, street_address=street_address, description=description)
       session.add(restaurant)
       session.commit()
       session.refresh(restaurant)
       return restaurant
   
   
   @app.post("/api/restaurants/{id}/reviews", response_model=Review, status_code=status.HTTP_201_CREATED,operation_id="createReview")
   async def create_review_for_restaurant_json(
       id: int,
       user_name: str = Body(...),
       rating: Optional[int] = Body(None),
       review_text: str = Body(...),
       session: Session = Depends(get_db_session),
   ):
       if not session.get(Restaurant, id):
           raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Restaurant not found")
   
       review = Review(
           restaurant=id, user_name=user_name, rating=rating, review_text=review_text, review_date=datetime.now()
       )
       session.add(review)
       session.commit()
       session.refresh(review)
       return review
   

   Esse código mostra apenas a criação de API para fins de brevidade e paridade com o aplicativo de exemplo existente. Se desejar, você também pode adicionar outras APIs, como atualizar e excluir.

4. Inicie o servidor de desenvolvimento para o aplicativo de exemplo com os seguintes comandos:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r src/requirements.txt
   pip install -e src
   python3 src/fastapi_app/seed_data.py
   python3 -m uvicorn fastapi_app:app --reload --port=8000
   

5. Selecione Abrir no Navegador.

6. Exiba o esquema OpenAPI adicionando /openapi.json à URL, que é o caminho padrão usado pelo FastAPI para atender ao esquema.

7. De volta ao terminal do codespace, implante suas alterações confirmando suas alterações (método GitHub Actions) ou execute azd up (método Azure Developer CLI).

8. Depois que suas alterações forem implantadas, navegue até https://<your-app's-url>/openapi.json e copie o esquema para mais tarde.

Criar um agente no Microsoft Foundry

1. No portal Foundry, no menu superior direito, selecione New Foundry.

2. Se esta for a primeira vez no novo portal do Foundry, selecione o nome do projeto e selecione Criar novo projeto.

3. Dê um nome ao projeto e selecione Criar.

4. Selecione Começar a construir, em seguida, Criar agente.

5. Dê um nome ao seu agente e selecione Criar. Quando o agente estiver pronto, você deverá ver a área de testes do agente.

   Observe os modelos que você pode usar e as regiões disponíveis.

6. No ambiente de trabalho do agente, expanda Ferramentas selecione Adicionar>Personalizada>Ferramenta OpenAPI>Criar.

7. Dê à ferramenta um nome e uma descrição. Na caixa de esquema OpenAPI 3.0+ , cole o esquema que você copiou anteriormente.

8. Selecione Criar ferramenta.

9. Clique em Salvar.

Testar o agente

1. Em Instruções, forneça algumas instruções simples, como "Use a ferramenta restaurantReview para ajudar a gerenciar as avaliações de restaurantes".

2. Converse com o agente com as seguintes sugestões de prompt:

   • "Mostre-me a lista de avaliações de restaurantes."
   • "Crie um restaurante. Use sua imaginação para os detalhes."
   • "Eu não gostei da comida neste restaurante. Crie uma revisão de 2 estrelas."

   

Melhores práticas de segurança

Ao expor APIs por meio do OpenAPI no Serviço de Aplicativo do Azure, siga estas práticas recomendadas de segurança:

• Autenticação e Autorização: Proteja seus endereços OpenAPI com a autenticação do Microsoft Entra. Para instruções passo a passo, consulte Pontos de extremidade OpenAPI Seguros para o Serviço de Agente da Fábrica. Você também pode proteger seus pontos de extremidade por meio do Gerenciamento de API do Azure com o Microsoft Entra ID e garantir que somente usuários ou agentes autorizados possam acessar as ferramentas.
• Validar dados de entrada: Sempre valide os dados de entrada para evitar entradas inválidas ou mal-intencionadas. Para aplicativos Python, use bibliotecas como Pydantic para impor regras de validação de dados com modelos de esquema de solicitação dedicados (como RestaurantCreate e ReviewCreate). Consulte a documentação deles para obter melhores práticas e detalhes de implementação.
• Use HTTPS: O exemplo depende do Serviço de Aplicativo do Azure, que impõe HTTPS por padrão e fornece certificados TLS/SSL gratuitos para criptografar dados em trânsito.
• Limitar CORS: Restrinja o CORS (compartilhamento de recursos entre origens) somente a domínios confiáveis. Para obter mais informações, consulte Habilitar CORS.
• Aplicar limitação de taxa: use o Gerenciamento de API ou middleware personalizado para evitar ataques de abuso e negação de serviço.
• Ocultar pontos de extremidade confidenciais: Evite expor APIs internas ou de administrador em seu esquema OpenAPI.
• Examine o esquema OpenAPI: Verifique se o esquema OpenAPI não vaza informações confidenciais (como URLs internas, segredos ou detalhes de implementação).
• Mantenha as dependências atualizadas: Atualize regularmente os pacotes Do NuGet e monitore os avisos de segurança.
• Monitorar e atividade de log: Habilite o registro em log e monitore o acesso para detectar atividades suspeitas.
• Use identidades gerenciadas: Ao chamar outros serviços do Azure, use identidades gerenciadas em vez de credenciais codificadas.

Para obter mais informações, consulte Proteger seu aplicativo do Serviço de Aplicativo e Práticas recomendadas para segurança da API REST.

Próxima etapa

Agora você habilitou seu aplicativo do Serviço de Aplicativo para ser usado como uma ferramenta pelo Serviço de Agente da Fábrica e para interagir com as APIs do seu aplicativo através de linguagem natural no ambiente de teste dos agentes. A partir daqui, você pode continuar a adicionar recursos ao seu agente no portal do Foundry, integrá-lo aos seus próprios aplicativos usando o SDK do Microsoft Foundry ou a API REST ou implantá-lo como parte de uma solução maior. Os agentes criados no Microsoft Foundry podem ser executados na nuvem, integrados a chatbots ou inseridos em aplicativos Web e móveis.

Para seguir a próxima etapa e aprender a executar seu agente diretamente no Serviço de Aplicativo do Azure, confira o tutorial a seguir:

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?