Bir App Service uygulamasını Foundry Agent Service'te (Python) araç olarak ekleme

Bu öğreticide, OpenAPI aracılığıyla bir FastAPI uygulamasının işlevselliğini kullanıma sunmayı, bunu Foundry Aracı Hizmeti'ne araç olarak eklemeyi ve aracıların oyun alanında doğal dil kullanarak uygulamanızla etkileşim kurmayı öğreneceksiniz.

Web uygulamanızın zaten alışveriş, otel rezervasyonu veya veri yönetimi gibi kullanışlı özellikleri varsa, bu özellikleri Foundry Agent Service'teki bir yapay zeka temsilcisinin kullanımına açmak kolaydır. Yalnızca uygulamanıza bir OpenAPI şeması ekleyerek, aracının kullanıcı istemlerine yanıt verirken uygulamanızın özelliklerini anlamasını ve kullanmasını sağlarsınız. Bu, uygulamanız için OpenAPI uç noktası oluşturmanın ötesinde en az çabayla yapay zeka aracınızın da yapabilecekleri anlamına gelir. Bu öğreticide, basit bir restoran derecelendirme uygulamasıyla başlayacaksınız. Sonunda restoran derecelendirmelerini görebilir ve konuşma yapay zekası aracılığıyla bir temsilciyle yeni restoranlar ve yeni incelemeler oluşturabileceksiniz.

• Web uygulamanıza OpenAPI işlevselliği ekleyin.
• OpenAPI şemasının Foundry Agent Service ile uyumlu olduğundan emin olun.
• Uygulamanızı Foundry Agent Service'e OpenAPI aracı olarak kaydedin.
• Temsilcinizi aracı oyun alanında test edin.

Önkoşullar

Bu öğreticide , Azure'da PostgreSQL ile Python FastAPI web uygulaması dağıtma bölümünde kullanılan örnekle çalıştığınız varsayılır.

En azından GitHub Codespaces'ta örnek uygulamayı açın ve komutunu çalıştırarak azd upuygulamayı dağıtın.

Web uygulamanıza OpenAPI işlevselliği ekleme

FasAPI, varsayılan yolda /openapi.jsonOpenAPI işlevselliğini zaten içerir. Bir aracı tarafından uzaktan çağrılabilmek için mevcut kodda birkaç değişiklik yapmanız yeterlidir.

1. src/fastapi_app/app.py açın ve FastAPI uygulamasının bildirildiği 24. satırı bulun. değerini aşağıdaki kodla değiştirin app = FastAPI() :

   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}],
   )
   

   Bu kod, Ve titlegibi description OpenAPI şemasına meta veriler ekler. En önemlisi, API uç noktasının sunucu URL'sini ekler.

2. src/fastapi_app/app.py açın, ve operation_id GET API'lerine / ekleyin/details/{id}. Bu iki API, bir yapay zeka aracısının ayrıştırabileceği HTML belgelerini döndürür. Diğer tüm API'ler için parametresini include_in_schema=False ekleyin.

   @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)
       ...
   

   include_in_schema=False bunu kullanarak , GET /createve POST /add işlevlerini dışlarsınız POST /review/{id}çünkü bunlar form tabanlı işlevselliğin bir parçasıdır ve yapay zeka aracısının JSON verilerini göndermesi gerekir.

3. Add Restaurant'ı eklemek ve JSON kullanarak gözden geçirme işlevi eklemek için aşağıdaki kodu ekleyin:

   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
   

   Bu kod yalnızca kısa ve mevcut örnek uygulamayla eşlik için oluşturma API'sini gösterir. İsterseniz, güncelleştirme ve silme gibi başka API'ler de ekleyebilirsiniz.

4. Aşağıdaki komutlarla örnek uygulamanın geliştirme sunucusunu başlatın:

   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. Tarayıcıda Aç'ı seçin.

6. Şemayı sunmak için FastAPI tarafından kullanılan varsayılan yol olan URL'ye ekleyerek /openapi.json OpenAPI şemasını görüntüleyin.

7. Kod alanı terminalinde, değişikliklerinizi işleyerek (GitHub Actions yöntemi) veya çalıştırarak azd up (Azure Geliştirici CLI yöntemi) değişikliklerinizi dağıtın.

8. Değişiklikleriniz dağıtıldıktan sonra adresine gidin https://<your-app's-url>/openapi.json ve daha sonra kullanmak üzere şemayı kopyalayın.

Microsoft Foundry'de aracı oluşturma

Uyarı

Bu adımlarda yeni Foundry portalı kullanılır.

1. Dökümhane portalının sağ üst menüsünde Yeni Dökümhane'yi seçin.

2. Yeni Dökümhane portalında ilk kez geliyorsanız proje adını seçin ve Yeni proje oluştur'u seçin.

3. Projenize bir ad verin ve Oluştur'u seçin.

4. Oluşturmaya başla'yı ve ardından Aracı oluştur'u seçin.

5. Aracınıza bir ad verin ve Oluştur'u seçin. Aracı hazır olduğunda, temsilci oyun alanı görmelisiniz.

   Kullanabileceğiniz modelleri ve kullanılabilir bölgeleri not edin.

6. Aracı oyun alanında Araçlar'ı genişletin ve Ekle>Özel>OpenAPI aracı>Oluştur'u seçin.

7. Araci bir ad ve bir açiklama verin. OpenAPI 3.0+ şema kutusuna, daha önce kopyaladığınız şemayı yapıştırın.

8. Araç oluştur'u seçin.

9. Kaydetseçeneğini seçin.

Tavsiye

Bu öğreticide, OpenAPI aracı kimlik doğrulaması olmadan uygulamanızı anonim olarak çağıracak şekilde yapılandırılır. Üretim senaryolarında aracın güvenliğini yönetilen kimlik doğrulaması ile sağlamalısınız. Adım adım yönergeler için bkz. Foundry Agent Service için OpenAPI uç noktalarının güvenliğini sağlama.

Aracıyı test edin

1. Yönergeler bölümünde, "Lütfen restoran incelemelerini yönetmeye yardımcı olmak için restaurantReview aracını kullanın" gibi bazı basit yönergeler verin.

2. Aşağıdaki istem önerileriyle aracıyla sohbet edin:

   • "Bana restoran incelemelerinin listesini göster."
   • "Bir restoran oluşturun. Ayrıntılar için hayal gücünüzü kullanın."
   • "Bu restoranda yemek beğenmedim. Lütfen 2 yıldızlık bir inceleme oluşturun."

   

En iyi güvenlik uygulamaları

Azure App Service'te OpenAPI aracılığıyla API'leri gösterirken şu en iyi güvenlik yöntemlerini izleyin:

• Kimlik Doğrulaması ve Yetkilendirme: Microsoft Entra kimlik doğrulaması ile OpenAPI uç noktalarınızı koruyun. Adım adım yönergeler için bkz. Foundry Agent Service için OpenAPI uç noktalarının güvenliğini sağlama. Ayrıca Microsoft Entra Id ile Azure API Management'ın arkasındaki uç noktalarınızı koruyabilir ve araçlara yalnızca yetkili kullanıcıların veya aracıların erişebildiğinden emin olabilirsiniz.
• Giriş verilerini doğrulama: Geçersiz veya kötü amaçlı girişi önlemek için her zaman gelen verileri doğrulayın. Python uygulamalarında, ayrılmış istek şeması modelleriyle (RestaurantCreate ve ReviewCreate gibi) veri doğrulama kurallarını zorunlu kılmak için Pydantic gibi kitaplıkları kullanın. En iyi yöntemler ve uygulama ayrıntıları için belgelerine bakın.
• HTTPS kullanın: Örnek, varsayılan olarak HTTPS'yi zorlayan ve aktarımdaki verileri şifrelemek için ücretsiz TLS/SSL sertifikaları sağlayan Azure App Service'e dayanır.
• CORS'leri sınırla: Çıkış Noktaları Arası Kaynak Paylaşımı'nı (CORS) yalnızca güvenilen etki alanlarıyla kısıtlayın. Daha fazla bilgi için bkz. CORS'yi etkinleştirme.
• Hız sınırlama uygula: Kötüye kullanım ve hizmet reddi saldırılarını önlemek için API Management veya özel ara yazılım kullanın.
• Hassas uç noktaları gizle: OpenAPI şemanızda iç veya yönetici API'lerini açığa çıkarmaktan kaçının.
• OpenAPI şemasını gözden geçirin: OpenAPI şemanızın hassas bilgileri (iç URL'ler, gizli diziler veya uygulama ayrıntıları gibi) sızdırmadığından emin olun.
• Bağımlılıkları güncel tutun: NuGet paketlerini düzenli olarak güncelleştirin ve güvenlik önerilerini izleyin.
• İzleme ve günlük etkinliği: Şüpheli etkinliği algılamak için günlüğe kaydetme ve izleme erişimini etkinleştirin.
• Yönetilen kimlikleri kullanma: Diğer Azure hizmetlerini çağırırken, sabit kodlanmış kimlik bilgileri yerine yönetilen kimlikleri kullanın.

Daha fazla bilgi için bkz . App Service uygulamanızın güvenliğini sağlama ve REST API güvenliği için en iyi yöntemler.

Sonraki adım

Artık App Service uygulamanızın Foundry Agent Service tarafından bir araç olarak kullanılmasını etkinleştirdiniz ve aracıların oyun alanında doğal dil aracılığıyla uygulamanızın API'leriyle etkileşime geçtiniz. Buradan, Foundry portalında aracınıza özellik eklemeye devam edebilir, Microsoft Foundry SDK'sını veya REST API'sini kullanarak kendi uygulamalarınızla tümleştirebilir veya daha büyük bir çözümün parçası olarak dağıtabilirsiniz. Microsoft Foundry'de oluşturulan aracılar bulutta çalıştırılabilir, sohbet botlarıyla tümleştirilebilir veya web ve mobil uygulamalara eklenebilir.

Bir sonraki adıma geçmek ve aracınızı doğrudan Azure App Service'te çalıştırmayı öğrenmek için aşağıdaki öğreticiye bakın:

Öğretici: LangGraph veya Foundry Agent Service (Python) ile Azure App Service'te aracı web uygulaması oluşturma

Daha fazla kaynak

• Yapay zekayı Azure App Service uygulamalarınızla tümleştirme
• Foundry Aracı Hizmeti nedir?