Adicionar uma aplicação de App Service como ferramenta no Foundry Agent Service (Python)

Neste tutorial, vai aprender a expor a funcionalidade de uma aplicação FastAPI através do OpenAPI, adicioná-la como ferramenta ao Foundry Agent Service e interagir com a sua aplicação usando linguagem natural no playground dos agentes.

Se a sua aplicação web já tem funcionalidades úteis, como compras, reservas de hotel ou gestão de dados, é fácil disponibilizar essas capacidades a um agente de IA no Foundry Agent Service. Ao simplesmente adicionar um esquema OpenAPI ao seu aplicativo, você permite que o agente compreenda e use os recursos do seu aplicativo quando ele responde aos prompts dos usuários. Isso significa que tudo o que seu aplicativo pode fazer, seu agente de IA também pode fazer, com o mínimo de esforço além de criar um ponto de extremidade OpenAPI para seu aplicativo. Neste tutorial, você começa com um aplicativo simples de classificação de restaurantes. No final, você poderá ver as classificações dos restaurantes, bem como criar novos restaurantes e novas avaliações com um agente por meio da IA conversacional.

Pré-requisitos

Este tutorial pressupõe que você esteja trabalhando com o exemplo usado em Implantar 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 funcionalidade OpenAPI ao seu aplicativo Web

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

1. Abra src/fastapi_app/app.py e localize a linha 24, onde 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 ainda, ele adiciona a URL do servidor do ponto de extremidade da API.

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

   @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 /adde 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
   

   Este código mostra apenas a API create para 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 pela FastAPI para servir o esquema.

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

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

Criar um agente no Microsoft Foundry

1. No portal da Foundry, no menu superior direito, selecione Nova Foundry.

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

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

4. Seleciona Iniciar construção, depois Criar agente.

5. Dê um nome ao seu agente e selecione Criar. Quando o agente estiver pronto, deve visitar o parque infantil do agente.

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

6. No ambiente de testes do agente, expanda Ferramentas e selecione Adicionar>OpenAPI personalizada>Ferramenta>Criar.

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

8. Selecione Criar ferramenta.

9. Selecione Guardar.

Testar o agente

1. Nas Instruções, dê algumas instruções simples, como "Por favor, use a ferramenta restaurantReview para ajudar a gerir avaliações de restaurantes."

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

   • "Mostre-me a lista de avaliações de restaurantes."
   • "Crie um restaurante. Use sua imaginação para os detalhes."
   • "Não gostei da comida deste restaurante. Por favor, crie uma avaliação de 2 estrelas."

   

Práticas recomendadas de segurança

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

• Autenticação e autorização: proteja os seus pontos de extremidade OpenAPI com a autenticação da Microsoft Entra. Para obter instruções passo a passo, consulte Endpoints OpenAPI Seguros para o Foundry Agent Service. Você também pode proteger os seus pontos de extremidade atrás de Azure API Management com Microsoft Entra ID e garantir que só utilizadores ou agentes autorizados possam aceder às ferramentas.
• Valide os dados de entrada: Sempre valide os dados recebidos para evitar entradas inválidas ou maliciosas. 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 para obter práticas recomendadas 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.
• Limite de CORS: Restrinja o CORS (Cross-Origin Resource Sharing) apenas a domínios confiáveis. Para obter mais informações, consulte Habilitar CORS.
• Aplicar limite de taxa: Use o Gerenciamento de API ou middleware personalizado para evitar abusos e ataques de negação de serviço.
• Ocultar pontos de extremidade sensíveis: Evite expor APIs internas ou administrativas em seu esquema OpenAPI.
• Revise o esquema OpenAPI: Certifique-se de que seu esquema OpenAPI não vaze informações confidenciais (como URLs internos, segredos ou detalhes de implementação).
• Mantenha as dependências atualizadas: Atualize regularmente os pacotes NuGet e monitore os avisos de segurança.
• Monitore e registre a atividade: Habilite o registro em log e monitore o acesso para detetar 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óximo passo

Agora ativou a sua aplicação de Serviço de Aplicações para ser usada como ferramenta pelo “Foundry Agent Service” e para interagir com as APIs da sua aplicação através de linguagem natural no ambiente de teste dos agentes. A partir daqui, pode continuar a adicionar funcionalidades ao seu agente no portal Foundry, integrá-lo nas suas próprias aplicações usando o Microsoft Foundry SDK ou a API REST, ou implementá-lo como parte de uma solução maior. Os agentes criados no Microsoft Foundry podem ser executados na cloud, integrados em chatbots ou integrados em aplicações web e móveis.

Para dar o próximo passo e saber como executar seu agente diretamente no Serviço de Aplicativo do Azure, consulte o seguinte tutorial:

Mais recursos

• Integre a IA em seus aplicativos do Serviço de Aplicativo do Azure
• O que é o Foundry Agent Service?