Добавление приложения App Service как инструмента в Службе агента Foundry (Python)

В этом руководстве вы узнаете, как предоставить функциональность приложения FastAPI через OpenAPI, добавить его как инструмент в службу агента Foundry и взаимодействовать с приложением с помощью естественного языка в тестовой среде агентов.

Если веб-приложение уже имеет полезные функции, такие как покупки, бронирование отелей или управление данными, это легко сделать эти возможности доступными агенту ИИ в Службе агента Foundry. Просто добавив в приложение схему OpenAPI, агент может понять и использовать возможности приложения при реагировании на запросы пользователей. Это означает, что ваше приложение может сделать все, что может сделать агент ИИ, с минимальными усилиями, помимо создания конечной точки OpenAPI для вашего приложения. В этом руководстве вы начинаете с простого приложения оценки ресторанов. К концу вы сможете видеть рейтинги ресторанов, а также создавать новые рестораны и новые отзывы с агентом через беседный ИИ.

Предпосылки

В этом руководстве предполагается, что вы работаете с примером, используемым в развертывании веб-приложения Python FastAPI с помощью PostgreSQL в Azure.

По крайней мере откройте пример приложения в GitHub Codespaces и разверните приложение, выполнив его azd up.

Добавление функций OpenAPI в веб-приложение

FasAPI уже содержит функции OpenAPI по умолчанию /openapi.json. Необходимо внести несколько изменений в существующий код, чтобы сделать его вызывающим удаленно агентом.

1. Откройте src/fastapi_app/app.py и найдите строку 24, где объявляется приложение FastAPI. Замените 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}],
   )
   

   Этот код добавляет метаданные в схему OpenAPI, например title и description. Самое главное, он добавляет URL-адрес сервера конечной точки API.

2. Откройте src/fastapi_app/app.py, добавьте operation_id в / API-интерфейсы /details/{id} GET. Эти два API возвращают HTML-документы, которые агент ИИ может анализировать. Для всех остальных API добавьте 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)
       ...
   

   Вы используете для include_in_schema=False исключения GET /createи POST /addPOST /review/{id} потому, что они являются частью функциональности на основе форм, в то время как агент ИИ должен отправлять данные JSON.

3. Чтобы добавить ресторан и добавить функции проверки с помощью JSON, добавьте следующий код:

   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
   

   Этот код отображает только API создания для краткости и для паритета с существующим примером приложения. Если вы хотите, вы также можете добавить другие API, такие как обновление и удаление.

4. Запустите сервер разработки для примера приложения с помощью следующих команд:

   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. Выберите "Открыть в браузере".

6. Просмотрите схему OpenAPI, добавив /openapi.json в URL-адрес, который используется FastAPI по умолчанию для обслуживания схемы.

7. Вернитесь в терминал пространства кода, разверните изменения, зафиксировав изменения (метод GitHub Actions) или запустите azd up (метод Azure Developer CLI).

8. После развертывания изменений перейдите к https://<your-app's-url>/openapi.json схеме и скопируйте ее позже.

Создание агента в Microsoft Foundry

1. На портале Foundry в правом верхнем меню выберите New Foundry.

2. Если это первый раз на новом портале Foundry, выберите имя проекта и нажмите кнопку "Создать проект".

3. Присвойте проекту имя и нажмите кнопку "Создать".

4. Нажмите кнопку "Начать сборку", а затем создайте агент.

5. Присвойте агенту имя и нажмите кнопку "Создать". Когда агент будет готов, вы увидите песочницу агента.

   Обратите внимание на модели, которые можно использовать и доступные регионы.

6. В песочнице агента разверните Инструменты и выберите Добавить>настраиваемый>инструмент OpenAPI>Создать.

7. Присвойте инструменту имя и описание. В поле схемы OpenAPI 3.0+ вставьте скопированную ранее схему.

8. Нажмите "Создать инструмент".

9. Нажмите кнопку "Сохранить".

Тестирование агента

1. В инструкциях дайте несколько простых инструкций, таких как "Пожалуйста, используйте средство ресторанReview для управления отзывами о ресторанах".

2. Общаться с агентом со следующими предложениями запроса:

   • "Показать мне список отзывов о ресторане".
   • "Создайте ресторан. Используйте свое воображение для деталей".
   • "Я не любил еду в этом ресторане. Создайте 2 звезды обзор".

   

Рекомендации по обеспечению безопасности

При предоставлении API-интерфейсов с помощью OpenAPI в Службе приложений Azure следуйте приведенным ниже рекомендациям по обеспечению безопасности.

• Проверка подлинности и авторизация. Защита конечных точек OpenAPI с помощью проверки подлинности Microsoft Entra. Пошаговые инструкции см. в разделе "Безопасные конечные точки OpenAPI" для службы агента Foundry. Кроме того, вы можете защитить конечные точки с помощью управления API Azure и Microsoft Entra ID и обеспечить доступ только для авторизованных пользователей или агентов.
• Проверьте входные данные: Всегда проверяйте входящие данные, чтобы предотвратить недопустимые или вредоносные входные данные. Для приложений Python используйте такие библиотеки, как Pydantic , чтобы применить правила проверки данных с выделенными моделями схемы запросов (например, RestaurantCreate и ReviewCreate). Ознакомьтесь с документацией по рекомендациям и сведениям о реализации.
• Используйте ПРОТОКОЛ HTTPS: В примере используется служба приложений Azure, которая по умолчанию применяет ПРОТОКОЛ HTTPS и предоставляет бесплатные СЕРТИФИКАТЫ TLS/SSL для шифрования данных во время передачи.
• Ограничение CORS: Ограничить общий доступ к ресурсам между источниками (CORS) только доверенным доменам. Дополнительные сведения см. в разделе "Включение CORS".
• Применение ограничения скорости:Используйте службу управления API или пользовательского по промежуточного слоя, чтобы предотвратить злоупотребления и атаки типа "отказ в обслуживании".
• Скрытие конфиденциальных конечных точек: Избегайте предоставления внутренних или административных API в схеме OpenAPI.
• Просмотрите схему OpenAPI: Убедитесь, что схема OpenAPI не утечка конфиденциальной информации (например, внутренние URL-адреса, секреты или сведения о реализации).
• Обновление зависимостей: Регулярно обновляйте пакеты NuGet и отслеживайте рекомендации по безопасности.
• Мониторинг и действие журнала: Включите ведение журнала и мониторинг доступа для обнаружения подозрительных действий.
• Используйте управляемые удостоверения: При вызове других служб Azure используйте управляемые удостоверения вместо жестко закодированных учетных данных.

Дополнительные сведения см. в статье "Защита приложения службы приложений " и рекомендации по обеспечению безопасности REST API.

Следующий шаг

Теперь вы настроили приложение App Service для использования в качестве инструмента для службы агента Foundry. Взаимодействуйте с API вашего приложения через естественный язык на платформе для агентов. Здесь вы можете продолжать добавлять функции в агент на портале Foundry, интегрировать его в собственные приложения с помощью пакета SDK Microsoft Foundry или REST API или развернуть его в составе более крупного решения. Агенты, созданные в Microsoft Foundry, можно запускать в облаке, интегрировать в чат-боты или внедрять в веб-приложения и мобильные приложения.

Чтобы выполнить следующий шаг и узнать, как запустить агент непосредственно в Службе приложений Azure, ознакомьтесь со следующим руководством.

Дополнительные ресурсы

• Интеграция ИИ в приложения Службы приложений Azure
• Что такое служба агента Foundry?