Menambahkan aplikasi App Service sebagai alat di Foundry Agent Service (Python)

Dalam tutorial ini, Anda akan mempelajari cara mengekspos fungsionalitas aplikasi FastAPI melalui OpenAPI, menambahkannya sebagai alat ke Foundry Agent Service, dan berinteraksi dengan aplikasi Anda menggunakan bahasa alami di taman bermain agen.

Jika aplikasi web Anda sudah memiliki fitur yang berguna, seperti belanja, pemesanan hotel, atau manajemen data, mudah untuk membuat kemampuan tersebut tersedia untuk agen AI di Foundry Agent Service. Dengan hanya menambahkan skema OpenAPI ke aplikasi, Anda memungkinkan agen untuk memahami dan menggunakan kemampuan aplikasi Anda saat menanggapi permintaan pengguna. Ini berarti apa pun yang dapat dilakukan aplikasi Anda, agen AI Anda juga dapat melakukannya, dengan upaya minimal selain membuat titik akhir OpenAPI untuk aplikasi Anda. Dalam tutorial ini, Anda mulai dengan aplikasi penilaian restoran sederhana. Pada akhirnya, Anda akan dapat melihat peringkat restoran serta membuat restoran baru dan ulasan baru dengan agen melalui AI percakapan.

Cuplikan layar memperlihatkan taman bermain agen di tengah percakapan yang mengambil tindakan dengan menggunakan alat OpenAPI.

Tambahkan fungsionalitas OpenAPI ke aplikasi web Anda.
Pastikan skema OpenAPI kompatibel dengan Foundry Agent Service.
Daftarkan aplikasi Anda sebagai alat OpenAPI di Foundry Agent Service.
Uji agen Anda di taman bermain agen.

Prasyarat

Tutorial ini mengasumsikan Anda bekerja dengan sampel yang digunakan dalam Menyebarkan aplikasi web Python FastAPI dengan PostgreSQL di Azure.

Minimal, buka aplikasi sampel di GitHub Codespaces dan sebarkan aplikasi dengan menjalankan azd up.

Menambahkan fungsionalitas OpenAPI ke aplikasi web Anda

FasAPI sudah berisi fungsionalitas OpenAPI di jalur /openapi.jsondefault . Anda hanya perlu membuat beberapa perubahan pada kode yang ada untuk membuatnya dapat dipanggil dari jarak jauh oleh agen.

Buka src/fastapi_app/app.py dan temukan baris 24, tempat aplikasi FastAPI dideklarasikan. Ganti app = FastAPI() dengan kode berikut:

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

Kode ini menambahkan metadata ke skema OpenAPI, seperti title dan description. Yang paling penting, ia menambahkan URL server titik akhir API.

Buka src/fastapi_app/app.py, tambahkan operation_id ke / API GET dan /details/{id} . Kedua API ini mengembalikan dokumen HTML yang dapat diurai agen AI. Untuk semua API lainnya, tambahkan include_in_schema=False parameter .

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

Anda menggunakan include_in_schema=False untuk mengecualikan GET /create, POST /add, dan POST /review/{id} karena mereka adalah bagian dari fungsionalitas berbasis formulir, sedangkan agen AI perlu mengirimkan data JSON.

Untuk menambahkan restoran dan menambahkan fungsionalitas tinjauan menggunakan JSON, tambahkan kode berikut:

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

Kode ini hanya menunjukkan API buat untuk brevity dan untuk paritas dengan aplikasi sampel yang ada. Jika mau, Anda juga dapat menambahkan API lain, seperti memperbarui dan menghapus.

Mulai server pengembangan untuk aplikasi sampel dengan perintah berikut:

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

Pilih Buka di Browser.
Lihat skema OpenAPI dengan menambahkan /openapi.json ke URL, yang merupakan jalur default yang digunakan oleh FastAPI untuk melayani skema.
Kembali ke terminal codespace, sebarkan perubahan Anda dengan menerapkan perubahan Anda (metode GitHub Actions) atau jalankan azd up (metode Azure Developer CLI).
Setelah perubahan Anda disebarkan, navigasikan ke https://<your-app's-url>/openapi.json dan salin skema untuk nanti.

Membuat agen di Microsoft Foundry

Nota

Langkah-langkah ini menggunakan portal Foundry baru.

Di portal Foundry, di menu kanan atas, pilih New Foundry.
Jika ini pertama kalinya Anda berada di portal Foundry baru, pilih nama proyek dan pilih Buat proyek baru.
Beri nama proyek Anda dan pilih Buat.
Pilih Mulai membangun, lalu Buat agen.
Beri nama agen Anda dan pilih Buat. Ketika agen siap, Anda akan melihat taman bermain agen.

Perhatikan model yang dapat Anda gunakan dan wilayah yang tersedia.
Di taman bermain agen, perluas Alat dan pilih Tambahkan>alat> OpenAPI>Buat.
Beri nama dan deskripsi pada alat ini. Dalam kotak skema OpenAPI 3.0+ , tempelkan skema yang Anda salin sebelumnya.
Pilih Buat alat.
Pilih Simpan.

Petunjuk / Saran

Dalam tutorial ini, alat OpenAPI dikonfigurasi untuk memanggil aplikasi Anda secara anonim tanpa autentikasi. Untuk skenario produksi, Anda harus mengamankan perangkat dengan autentikasi identitas yang terkelola. Untuk instruksi langkah demi langkah, lihat Endpoint OpenAPI yang Aman untuk Foundry Agent Service.

Menguji agen

Dalam Instruksi, berikan beberapa instruksi sederhana, seperti "Silakan gunakan alat restaurantReview untuk membantu mengelola ulasan restoran."
Mengobrol dengan agen dengan saran perintah berikut:
- "Tunjukkan daftar ulasan restoran."
- "Buat restoran. Gunakan imajinasi Anda untuk detailnya."
- "Saya tidak suka makanan di restoran ini. Silakan buat ulasan bintang 2."

Praktik terbaik keamanan

Saat mengekspos API melalui OpenAPI di Azure App Service, ikuti praktik terbaik keamanan berikut:

Autentikasi dan Otorisasi: Lindungi titik akhir OpenAPI Anda dengan autentikasi Microsoft Entra. Untuk instruksi langkah demi langkah, lihat Endpoint OpenAPI yang Aman untuk Foundry Agent Service. Anda juga dapat melindungi titik akhir di belakang Azure API Management dengan ID Microsoft Entra dan memastikan hanya pengguna atau agen yang berwenang yang dapat mengakses alat.
Memvalidasi data input: Selalu validasi data masuk untuk mencegah input yang tidak valid atau berbahaya. Untuk aplikasi Python, gunakan pustaka seperti Pydantic untuk menerapkan aturan validasi data dengan model skema permintaan khusus (seperti RestaurantCreate dan ReviewCreate). Lihat dokumentasi mereka untuk praktik terbaik dan detail implementasi.
Gunakan HTTPS: Sampel bergantung pada Azure App Service, yang memberlakukan HTTPS secara default dan menyediakan sertifikat TLS/SSL gratis untuk mengenkripsi data saat transit.
BATAS CORS: Batasi Berbagi Sumber Daya Lintas Asal (CORS) ke domain tepercaya saja. Untuk informasi selengkapnya, lihat Mengaktifkan CORS.
Menerapkan pembatasan tarif: Gunakan API Management atau middleware kustom untuk mencegah penyalahgunaan dan penolakan serangan layanan.
Sembunyikan titik akhir sensitif: Hindari mengekspos API internal atau admin dalam skema OpenAPI Anda.
Tinjau skema OpenAPI: Pastikan skema OpenAPI Anda tidak membocorkan informasi sensitif (seperti URL internal, rahasia, atau detail implementasi).
Terus perbarui dependensi: Perbarui paket NuGet secara teratur dan pantau saran keamanan.
Memantau dan mencatat aktivitas: Aktifkan pengelogan dan pantau akses untuk mendeteksi aktivitas yang mencurigakan.
Gunakan identitas terkelola: Saat memanggil layanan Azure lainnya, gunakan identitas terkelola alih-alih kredensial yang dikodekan secara permanen.

Untuk informasi selengkapnya, lihat Mengamankan aplikasi App Service anda dan Praktik terbaik untuk keamanan REST API.

Langkah selanjutnya

Anda sekarang telah mengaktifkan aplikasi App Service untuk digunakan sebagai alat oleh Foundry Agent Service dan berinteraksi dengan API aplikasi Anda melalui bahasa alami di taman bermain agen. Dari sini, Anda dapat terus menambahkan fitur ke agen Anda di portal Foundry, mengintegrasikannya ke dalam aplikasi Anda sendiri menggunakan Microsoft Foundry SDK atau REST API, atau menyebarkannya sebagai bagian dari solusi yang lebih besar. Agen yang dibuat di Microsoft Foundry dapat dijalankan di cloud, diintegrasikan ke dalam chatbot, atau disematkan di aplikasi web dan seluler.

Untuk mengambil langkah berikutnya dan mempelajari cara menjalankan agen Anda langsung dalam Azure App Service, lihat tutorial berikut:

Tutorial: Membangun aplikasi web agenik di Azure App Service dengan LangGraph atau Foundry Agent Service (Python)

Sumber daya lainnya

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-16