Introduzione a LangChain e LangGraph con Foundry

Usare il langchain-azure-ai pacchetto come punto di ingresso per la compilazione di applicazioni LangChain e LangGraph con le funzionalità di 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. Creane uno gratis.
• Un progetto Fonderia.
• Ruolo utente di Azure AI nel progetto Foundry (ruolo con privilegi minimi per lo 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:

Vedere la sezione Informazioni dettagliate su ogni funzionalità per le procedure specifiche.

Collegarsi 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 utilizza Microsoft Entra ID e Azure RBAC per il 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:

import 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 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.
model_from_endpoint = AzureAIOpenAIApiChatModel(
  endpoint=os.environ["OPENAI_BASE_URL"],
  credential=DefaultAzureCredential(),
  model="gpt-5.2",
)

# Option C: Use a different credential strategy.
model_with_cli_credential = AzureAIOpenAIApiChatModel(
  endpoint=os.environ["OPENAI_BASE_URL"],
  credential="super-secret",
  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()

Funzionamento di DefaultAzureCredential

DefaultAzureCredential tenta diverse origini di credenziali Microsoft Entra ID nell'ordine e usa la prima che funziona. Le origini comuni sono variabili di ambiente, identità gestita, strumenti di sviluppo e Azure CLI.

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
• Utilizzare il middleware di sicurezza dei contenuti di Foundry
• Usare il Servizio agente di Foundry con LangGraph
• 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.

Passo successivo