Aggiungere un'applicazione di App Service come strumento nel Foundry Agent Service (Python)

In questa esercitazione si apprenderà come esporre le funzionalità di un'app FastAPI tramite OpenAPI, aggiungerla come strumento al servizio Foundry Agent e interagire con l'app usando il linguaggio naturale nel playground degli agenti.

Se l'applicazione Web ha già funzionalità utili, ad esempio acquisti, prenotazioni di hotel o gestione dei dati, è facile rendere queste funzionalità disponibili per un agente di intelligenza artificiale nel servizio Foundry Agent. Aggiungendo semplicemente uno schema OpenAPI all'app, è possibile abilitare l'agente per comprendere e usare le funzionalità dell'app quando risponde alle richieste degli utenti. Ciò significa che qualsiasi operazione possa eseguire l'app può anche essere eseguita dall'agente IA, con un impegno minimo se non creare un endpoint OpenAPI per l'app. In questa esercitazione si inizia con una semplice app per la valutazione dei ristoranti. Completando l'esercitazione si sarà in grado di visualizzare le valutazioni dei ristoranti, nonché creare nuovi ristoranti e nuove recensioni con un agente tramite intelligenza artificiale conversazionale.

Screenshot che mostra il playground degli agenti al centro di una conversazione che esegue azioni usando lo strumento OpenAPI.

Aggiungere la funzionalità OpenAPI all'app Web.
Assicurarsi che lo schema OpenAPI sia compatibile con il servizio Agente Foundry.
Registrare l'app come strumento OpenAPI nel servizio agente Foundry.
Testare l'agente nel playground degli agenti.

Prerequisiti

Questa esercitazione presuppone che si stia usando l'esempio usato in Distribuire un'app Web FastAPI Python con PostgreSQL in Azure.

Aprire almeno l'applicazione di esempio in GitHub Codespaces e distribuire l'app eseguendo azd up.

Aggiungere la funzionalità OpenAPI all'app Web

FastAPI contiene già la funzionalità OpenAPI nel percorso /openapi.jsonpredefinito. È sufficiente apportare alcune modifiche al codice esistente affinché un agente possa chiamarlo da remoto.

Aprire src/fastapi_app/app.py e trovare la riga 24, dove viene dichiarata l'app FastAPI. Sostituisci app = FastAPI() con il seguente codice:

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

Questo codice aggiunge metadati allo schema OpenAPI, ad esempio title e description. Soprattutto, aggiunge l'URL del server dell'endpoint API.

Aprire src/fastapi_app/app.py, aggiungere operation_id alle API GET / e /details/{id}. Queste due API restituiscono documenti HTML che un agente IA può analizzare. Per tutte le altre API, aggiungere il parametro 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)
    ...

Usare include_in_schema=False per escludere GET /create, POST /add e POST /review/{id} perché fanno parte della funzionalità basata su modulo, mentre l'agente IA deve inviare dati JSON.

Per aggiungere la funzionalità aggiungi ristorante e aggiungi recensione usando JSON, aggiungere il codice seguente:

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

Questo codice mostra solo l'API di creazione per brevità e parità con l'applicazione di esempio esistente. Se lo si desidera, è anche possibile aggiungere altre API, ad esempio di aggiornamento ed eliminazione.

Avviare il server di sviluppo per l'app di esempio con i comandi seguenti:

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

Fare clic su Open in Browser (Apri nel browser).
Visualizzare lo schema OpenAPI aggiungendo /openapi.json all'URL, ovvero il percorso predefinito usato da FastAPI per gestire lo schema.
Tornare al terminale codespace, distribuire le modifiche eseguendo il commit delle modifiche (metodo GitHub Actions) o eseguendo azd up (metodo dell'interfaccia della riga di comando per sviluppatori di Azure).
Dopo aver distribuito le modifiche, andare a https://<your-app's-url>/openapi.json e copiare lo schema per un uso futuro.

Creare un agente in Microsoft Foundry

Annotazioni

Questi passaggi usano il nuovo portale Foundry.

Nel menu in alto a destra del portale Foundry, selezionare Nuovo Foundry.
Se si tratta della prima volta nel nuovo portale Foundry, selezionare il nome del progetto e selezionare Crea nuovo progetto.
Assegnare un nome al progetto e selezionare Crea.
Selezionare Avvia compilazione e quindi Crea agente.
Assegnare un nome all'agente e selezionare Crea. Quando l'agente è pronto, dovresti vedere l'ambiente di prova dell'agente.

Si notino i modelli che è possibile usare e le aree disponibili.
Nel playground dell'agente espandere Strumenti e selezionare Aggiungi>strumento> personalizzato OpenAPI>creare.
Assegnare allo strumento un nome e una descrizione. Nella casella Schema OpenAPI 3.0+ incollare lo schema copiato in precedenza.
Selezionare Crea strumento.
Seleziona Salva.

Suggerimento

In questa esercitazione lo strumento OpenAPI è configurato per chiamare l'app in modo anonimo senza autenticazione. Per gli scenari di produzione, è consigliabile proteggere lo strumento con l'autenticazione dell'identità gestita. Per istruzioni dettagliate, vedere Proteggere gli endpoint OpenAPI per il servizio agente Foundry.

Testare l'agente

In Istruzioni, fornire alcune semplici istruzioni, ad esempio "Usare lo strumento restaurantReview per gestire le recensioni dei ristoranti".
Aprire una chat con l'agente con i suggerimenti seguenti:
- "Mostrami l'elenco delle recensioni dei ristoranti".
- "Crea un ristorante. Usa l'immaginazione per i dettagli".
- "I piatti di questo ristorante non mi piacciono". Crea una recensione a 2 stelle".

Procedure consigliate per la sicurezza

Quando si espongono API tramite OpenAPI nel Servizio app di Azure, seguire queste procedure consigliate per la sicurezza:

Autenticazione e autorizzazione: proteggere gli endpoint OpenAPI con l'autenticazione Microsoft Entra. Per istruzioni dettagliate, vedere Proteggere gli endpoint OpenAPI per il servizio agente Foundry. È anche possibile proteggere gli endpoint dietro Gestione API di Azure con Microsoft Entra ID e assicurarsi che solo gli utenti o gli agenti autorizzati possano accedere agli strumenti.
Convalidare i dati di input: Convalidare sempre i dati in ingresso per evitare input non validi o dannosi. Per le app Python, usare librerie come Pydantic per applicare regole di convalida dei dati con modelli di schema di richiesta dedicati, ad esempio RestaurantCreate e ReviewCreate. Per informazioni dettagliate sulle procedure consigliate e sull'implementazione, vedere la documentazione.
Usare HTTPS: l'esempio si basa sul Servizio app di Azure, che applica HTTPS per impostazione predefinita e fornisce certificati TLS/SSL gratuiti per crittografare i dati in transito.
Limitare CORS: limitare la condivisione di risorse tra le origini (CORS, Cross-Origin Resource Sharing) solo ai domini attendibili. Per altre informazioni, vedere Abilitare CORS.
Applicare la limitazione della frequenza: usare API Management o middleware personalizzato per evitare attacchi di tipo denial of service e un uso improprio.
Nascondere gli endpoint sensibili: evitare di esporre API interne o amministrative nello schema OpenAPI.
Esaminare lo schema OpenAPI: assicurarsi che dallo schema OpenAPI non trapelino informazioni riservate, ad esempio URL interni, segreti o dettagli di implementazione.
Mantenere aggiornate le dipendenze: aggiornare regolarmente i pacchetti NuGet e monitorare gli avvisi di sicurezza.
Monitorare e registrare attività: abilitare la registrazione e monitorare l'accesso per rilevare attività sospette.
Usare le identità gestite: quando si chiamano altri servizi di Azure, usare identità gestite anziché credenziali hardcoded.

Per altre informazioni, vedere Proteggere l'app del Servizio app e Procedure consigliate per la sicurezza delle API REST.

Passo successivo

L'app del Servizio App è stata abilitata per essere utilizzata come strumento dal Servizio Agente Fonderia e per l'interazione con le API dell'app tramite il linguaggio naturale nel playground degli agenti. Da qui è possibile continuare ad aggiungere funzionalità all'agente nel portale foundry, integrarla nelle proprie applicazioni usando Microsoft Foundry SDK o l'API REST oppure distribuirla come parte di una soluzione più grande. Gli agenti creati in Microsoft Foundry possono essere eseguiti nel cloud, integrati in chatbot o incorporati in app Web e per dispositivi mobili.

Per eseguire il passaggio successivo e imparare a eseguire l'agente direttamente nel Servizio app di Azure, vedere l'esercitazione seguente:

Esercitazione: Creare un'app Web agentic nel servizio app di Azure con LangGraph o Foundry Agent Service (Python)

Altre risorse

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-12-16