Introduzione a LangChain e LangGraph con Foundry

Usare il pacchetto langchain-azure-ai come punto di ingresso per la compilazione di applicazioni LangChain e LangGraph con funzionalità Microsoft Foundry. Questo articolo offre una mappa generale del pacchetto in modo da poter iniziare rapidamente, quindi passare alla documentazione approfondita corretta per ogni funzionalità.

Prerequisiti

• Sottoscrizione Azure. Crearne uno gratuitamente.

• Progetto Foundry.

• Ruolo utente Foundry nel progetto Foundry (ruolo con privilegi minimi per

  Importante

  I ruoli di Controllo degli accessi in base al ruolo di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

  sviluppo). Se si creano o si gestiscono anche le risorse, usare Collaboratore o Proprietario in base alle esigenze. Per informazioni dettagliate, vedere Controllo degli accessi in base al ruolo per Microsoft Foundry.

• Python 3.10 o versione successiva.

• Interfaccia della riga di comando di Azure connessa (az login) in modo che DefaultAzureCredential possa eseguire l'autenticazione.

Installare il pacchetto

Installare il pacchetto di base:

pip install -U langchain-azure-ai azure-identity

Installare extra facoltativi in base al proprio scenario:

pip install -U "langchain-azure-ai[tools]"
pip install -U "langchain-azure-ai[opentelemetry]"

• Usare [tools] se l'app usa strumenti dello spazio dei nomi langchain_azure_ai.tools.*, ad esempio Document Intelligence.
• Usare [opentelemetry] se si vuole eseguire l'integrazione della traccia tramite OpenTelemetry.

Scegliere i blocchi predefiniti di integrazione

Usare questa mappa per selezionare lo spazio dei nomi appropriato per la soluzione:

Consultare la sezione Informazioni dettagliate su ogni funzionalità per una guida specifica.

Connettersi agli endpoint e alle credenziali del progetto

Molte langchain-azure-ai classi supportano la connessione tramite un endpoint di progetto Foundry. Impostare AZURE_AI_PROJECT_ENDPOINT una sola volta, quindi riutilizzarlo tra le classi supportate.

export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"

Quando si usa project_endpoint, l'autenticazione usa Microsoft Entra ID e il controllo degli accessi in base ai ruoli di Azure nel progetto.

Le chiavi API sono destinate agli endpoint di servizio diretti, ad esempio /openai/v1.

export OPENAI_BASE_URL="https://<resource>.services.ai.azure.com/openai/v1"
export OPENAI_API_KEY="<your-key>"

Esempio: Usare i modelli di fonderia

Dopo aver configurato le variabili di ambiente, è possibile usare un modello tramite:

from langchain.chat_models import init_chat_model

model = init_chat_model("azure_ai:gpt-5.2")

È anche possibile configurare i client in modo specifico. Ad esempio, si vedrà AzureAIOpenAIApiChatModel come modello rappresentativo:

import os

from azure.identity import AzureCliCredential, DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

# Option A: Use a Foundry project endpoint (Microsoft Entra ID required).
model_from_project = AzureAIOpenAIApiChatModel(
  project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
  credential=DefaultAzureCredential(),
  model="gpt-5.2",
)

# Option B: Use a service endpoint directly with an API key.
model_from_endpoint = AzureAIOpenAIApiChatModel(
  endpoint=os.environ["OPENAI_BASE_URL"],
  credential=os.environ["OPENAI_API_KEY"],
  model="gpt-5.2",
)

# Option C: Use a different credential strategy.
model_with_cli_credential = AzureAIOpenAIApiChatModel(
  endpoint=os.environ["OPENAI_BASE_URL"],
  credential=AzureCliCredential(),
  model="gpt-5.2",
)

Cosa fa questo frammento di codice: Mostra lo stesso modello inizializzato da un endpoint di progetto Foundry o da un endpoint di servizio diretto e mostra come scambiare le credenziali.

È possibile applicare lo stesso modello agli strumenti. Ad esempio, AzureAIDocumentIntelligenceTool può usare l'endpoint del progetto e DefaultAzureCredential senza configurazione aggiuntiva quando AZURE_AI_PROJECT_ENDPOINT è impostato:

from langchain_azure_ai.tools import AzureAIDocumentIntelligenceTool

document_tool = AzureAIDocumentIntelligenceTool()

Come DefaultAzureCredential funziona

DefaultAzureCredential tenta diverse fonti di credenziali Microsoft Entra ID in sequenza e usa la prima che funzioni. Le origini comuni sono variabili di ambiente, identità gestita, strumenti di sviluppo e interfaccia della riga di comando di Azure.

Usare DefaultAzureCredential come impostazione predefinita per lo sviluppo locale e i carichi di lavoro distribuiti. Se è necessario un controllo più rigoroso, sostituirlo con credenziali specifiche, ad esempio AzureCliCredential per lo sviluppo solo locale o ManagedIdentityCredential per i carichi di lavoro di produzione in Azure.

Lo stesso modello di endpoint di progetto viene usato anche da altre classi.

Informazioni dettagliate su ogni funzionalità

Iniziare con queste guide in questo set di documentazione:

• Usare i modelli Foundry con LangChain e LangGraph
• Usare il middleware Foundry di sicurezza del contenuto
• Usare il servizio agente di Foundry con LangGraph
• Usa Foundry Toolbox con LangChain
• Agenti Host LangGraph come agenti ospitati da Foundry
• Usare la memoria Foundry con LangChain e LangGraph
• Usare Foundry Observability per tracciare le app

Usare queste risorse del pacchetto per i dettagli e gli aggiornamenti a livello di modulo:

• Panoramica del pacchetto e README.
• Documentazione di LangChain per langchain-azure-ai.

Passaggio successivo