Introdução a LangChain e LangGraph com o Foundry

Use o pacote langchain-azure-ai como o ponto de entrada para a criação de aplicativos LangChain e LangGraph com recursos Microsoft Foundry. Este artigo fornece uma visão geral do pacote para que você possa começar rapidamente e, em seguida, acessar a documentação detalhada para cada funcionalidade.

Pré-requisitos

• Uma assinatura Azure. Crie um gratuitamente.
• Um projeto do Foundry.
• A função Usuário de Azure AI no projeto Foundry (função de mínimo privilégio para desenvolvimento). Caso você também crie ou gerencie recursos, use Colaborador ou Proprietário quando necessário. Para obter detalhes, consulte controle de acesso baseado em função para Microsoft Foundry.
• Python 3.10 ou posterior.
• CLI do Azure está conectado (az login) para que DefaultAzureCredential possa autenticar-se.

Instalar o pacote

Instale o pacote base:

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

Instale extras opcionais com base em seu cenário:

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

• Use [tools] se seu aplicativo usa ferramentas do namespace langchain_azure_ai.tools.*, como o Document Intelligence.
• Use [opentelemetry] se desejar a integração de rastreamento por meio do OpenTelemetry.

Escolher blocos de construção de integração

Use este mapa para escolher o namespace certo para sua solução:

Consulte a seção Aprenda cada funcionalidade em detalhes para obter instruções passo a passo específicas.

Conectar-se com os endpoints e as credenciais do projeto

Muitas langchain-azure-ai classes dão suporte à conexão por meio de um endpoint de um projeto do Foundry. Defina AZURE_AI_PROJECT_ENDPOINT uma vez e reutilize-a entre classes com suporte.

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

Quando você usa project_endpoint, a autenticação usa Microsoft Entra ID e Azure RBAC no projeto.

As chaves de API são para pontos de extremidade de serviço diretos, como /openai/v1.

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

Exemplo: usar modelos de fundimento

Depois que as variáveis de ambiente forem configuradas, você poderá usar um modelo:

import langchain.chat_models import init_chat_model

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

Você também pode configurar clientes especificamente. Como exemplo, vamos ver AzureAIOpenAIApiChatModel como um padrão representativo:

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",
)

O que este snippet de código faz: Mostra o mesmo modelo inicializado a partir de um ponto de acesso de projeto do Foundry ou de um ponto de acesso de serviço direto e demonstra como trocar as credenciais.

Você pode aplicar o mesmo padrão às ferramentas. Por exemplo, AzureAIDocumentIntelligenceTool pode usar o ponto de extremidade do projeto e DefaultAzureCredential sem configuração extra quando AZURE_AI_PROJECT_ENDPOINT é definido:

from langchain_azure_ai.tools import AzureAIDocumentIntelligenceTool

document_tool = AzureAIDocumentIntelligenceTool()

Como DefaultAzureCredential funciona

DefaultAzureCredential tenta várias fontes de credenciais Microsoft Entra ID em ordem e usa a primeira que funciona. As fontes comuns são variáveis de ambiente, identidade gerenciada, ferramentas de desenvolvedor e CLI do Azure.

Use DefaultAzureCredential como padrão para desenvolvimento local e cargas de trabalho implantadas. Se você precisar de um controle mais rigoroso, substitua-o por uma credencial específica, como AzureCliCredential para desenvolvimento somente local ou ManagedIdentityCredential para cargas de trabalho de produção em Azure.

O mesmo padrão de ponto de extremidade de projeto também é usado por outras classes.

Aprenda cada funcionalidade em detalhes

Comece com estes guias neste conjunto de documentação:

• Usar modelos Foundry com LangChain e LangGraph
• Usar o middleware de Segurança de Conteúdo do Foundry
• Usar o Serviço do Foundry Agent com o LangGraph
• Usar memória de fundimento com LangChain e LangGraph
• Usar a Observabilidade do Foundry para rastrear aplicativos

Use esses recursos de pacote para obter detalhes e atualizações no nível do módulo:

• Visão geral do pacote e README.
• Documentação do LangChain para langchain-azure-ai.

Próxima etapa