Comece a usar LangChain e LangGraph com a Foundry

Use o pacote langchain-azure-ai como ponto de entrada para construir aplicações LangChain e LangGraph com capacidades Microsoft Foundry. Este artigo dá-lhe um mapa de alto nível do pacote para que possa começar rapidamente e depois passar para a documentação aprofundada correta para cada funcionalidade.

Pré-requisitos

• Uma subscrição do Azure. Crie um gratuitamente.

• Um projeto da Foundry.

• A função Utilizador do Foundry no projeto Foundry (função de privilégios mínimos para

  Importante

  As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

  desenvolvimento). Se também criar ou gerenciar recursos, utilize Contribuinte ou Proprietário conforme necessário. Para mais detalhes, consulte Controlo de acesso baseado em funções para Microsoft Foundry.

• Python 3.10 ou posterior.

• CLI do Azure iniciado sessão (az login) para que DefaultAzureCredential possa autenticar-se.

Instale o pacote

Instale o pacote base:

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

Instala extras opcionais consoante o teu cenário:

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

• Use [tools] se a sua aplicação usar ferramentas do namespace langchain_azure_ai.tools.*, como Document Intelligence.
• Usa [opentelemetry] se quiseres integração de traçado via OpenTelemetry.

Escolha componentes de integração

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

Consulte a secção Aprenda cada funcionalidade em detalhe para guias específicas.

Conecte-se aos endpoints e credenciais do projeto

Muitas langchain-azure-ai classes suportam a ligação através de um endpoint de projeto Foundry. Define AZURE_AI_PROJECT_ENDPOINT uma vez e depois reutiliza entre as classes suportadas.

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

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

As chaves API são para endpoints de serviço direto, 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 fundição

Depois de configuradas as variáveis de ambiente, pode usar um modelo através de:

from langchain.chat_models import init_chat_model

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

Também podes configurar clientes especificamente. Como exemplo, vejamos AzureAIOpenAIApiChatModel como um padrão representativo:

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

O que este excerto faz: Mostra o mesmo modelo inicializado a partir de um endpoint de projeto Foundry ou de um endpoint de serviço direto, e mostra como trocar credenciais.

Podes aplicar o mesmo padrão às ferramentas. Por exemplo, AzureAIDocumentIntelligenceTool pode usar o endpoint do projeto e DefaultAzureCredential sem configuração adicional quando AZURE_AI_PROJECT_ENDPOINT está definido:

from langchain_azure_ai.tools import AzureAIDocumentIntelligenceTool

document_tool = AzureAIDocumentIntelligenceTool()

Como DefaultAzureCredential funciona

DefaultAzureCredential tenta várias fontes de credenciais Microsoft Entra ID por ordem e usa a primeira que funciona. Fontes comuns são variáveis de ambiente, identidade gerida, ferramentas para programadores e CLI do Azure.

Use DefaultAzureCredential como padrão para o desenvolvimento local e cargas de trabalho implementadas. Se precisares de controlo mais rigoroso, substitui-o por uma credencial específica, como AzureCliCredential para desenvolvimento apenas local ou ManagedIdentityCredential para cargas de trabalho de produção em Azure.

O mesmo padrão projeto-ponto final é também utilizado por outras classes.

Aprenda cada capacidade em detalhe

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

• Use Modelos de Fundição com LangChain e LangGraph
• Use middleware Foundry Content Safety
• Use o Serviço de Agente da Fundição com o LangGraph
• Use a Caixa de Ferramentas da Fundição com a LangChain
• Aloje agentes LangGraph como agentes alojados no Foundry
• Use a Memória da Foundry com LangChain e LangGraph
• Use a Foundry Observability para rastrear aplicações

Use estes recursos do pacote para detalhes e atualizações ao nível do módulo:

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

Próximo passo