Comece a usar LangChain e LangGraph com a Foundry

Use o langchain-azure-ai pacote como ponto de entrada para construir aplicações LangChain e LangGraph com funcionalidades do 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 Foundry.
• A função de Utilizador IA do Azure no projeto Foundry (função com privilégio mínimo para desenvolvimento). Se também criar ou gerir recursos, use Contribuinte ou Proprietário conforme necessário. Para mais informações, consulte Controlo de acesso baseado em roles para Microsoft Foundry.
• Python 3.10 ou posterior.
• Azure CLI logado (az login) para que DefaultAzureCredential possa autenticar.

Gorjeta

Este artigo menciona o suporte para o Microsoft Foundry (novo), que utiliza a versão azure-ai-projects>=2.0. Se estiveres a usar o Foundry Classic, usa langchain-azure-ai[v1] em vez disso.

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 os componentes de integração

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

Capacidade	Namespace	Uso típico
Serviço de Agente de Fundição	langchain_azure_ai.agents	Construir nós de agentes controlados para criar grafos complexos e fluxos para LangGraph e LangChain. Veja exemplos detalhados.
Segurança de Conteúdos da Fundição	langchain_azure_ai.agents.middleware	Use a Segurança e Moderação de Conteúdos da Foundry para garantir que pode implementar soluções com as proteções certas. Veja exemplos detalhados.
Modelos de chat	langchain_azure_ai.chat_models	Ligue para o Azure OpenAI e modele o catálogo de modelos de chat. Veja exemplos detalhados.
Embeddings	langchain_azure_ai.embeddings	Chamar modelos de incorporação do catálogo para criar vetores para fluxos de trabalho de pesquisa, recuperação e ordenação. Veja exemplos detalhados.
Repositórios vetoriais	langchain_azure_ai.vectorstores	Use integrações vetoriais com Azure AI Search e Cosmos DB.
Cães Retriever	langchain_azure_ai.retrievers	Execute a recuperação em índices e armazenamentos suportados pelo Azure.
Armazenamento de histórico de chat	langchain_azure_ai.chat_message_histories	Persiste e reproduz o histórico de chat entre sessões. Use históricos baseados em memória para recuperar o histórico consolidado do chat de passe. Veja exemplos detalhados.
Tools	langchain_azure_ai.tools	Adicione ferramentas como Inteligência de Documentos, Visão, análise de texto de saúde e Aplicações Lógicas.
Chamadas de retorno e rastreamento	langchain_azure_ai.callbacks	Capturar eventos de execução e enviar rastreamentos OpenTelemetry. Veja exemplos detalhados.
Construtores de consulta	langchain_azure_ai.query_constructors	Crie filtros de consulta específicos do backend para cenários de recuperação.

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

Ligue-se aos endpoints e às credenciais do projeto

Muitas langchain-azure-ai classes suportam a conexã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:

import 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 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 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 funciona DefaultAzureCredential

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

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
• Utilize o Foundry Agent Service com o LangGraph
• Use a memória 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

Utilizar modelos de fundição com LangChain