Utilize o LangChain com modelos no Microsoft Foundry

Use langchain-azure-ai para construir aplicações LangChain que invocam modelos desenvolvidos no Microsoft Foundry. Modelos com APIs compatíveis com OpenAI podem ser usados diretamente. Neste artigo, cria clientes de chat e embeddings, executa cadeias de prompts e combina geração com fluxos de trabalho de verificação.

Pré-requisitos

• Uma subscrição do Azure. Crie um gratuitamente.
• Um projeto da Foundry.
• O papel Azure AI User no projeto Foundry.
• Um modelo de chat implementado que suporta APIs compatíveis com OpenAI, como gpt-4.1 ou Mistral-Large-3.
• Um modelo de embeddings implementado, como text-embedding-3-large.
• Python 3.9 ou posterior.

Instale os pacotes necessários:

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

Configurar o ambiente

Defina um dos seguintes padrões de ligação:

• Endpoint do projeto com Microsoft Entra ID (recomendado).
• Endpoint direto com uma chave de API.

import os

# Option 1: Project endpoint (recommended)
os.environ["AZURE_AI_PROJECT_ENDPOINT"] = (
	"https://<resource>.services.ai.azure.com/api/projects/<project>"
)

# Option 2: Direct OpenAI-compatible endpoint + API key
os.environ["OPENAI_BASE_URL"] = (
	"https://<resource>.services.ai.azure.com/openai/v1"
)
os.environ["OPENAI_API_KEY"] = "<your-api-key>"

O que este excerto faz: Define variáveis de ambiente usadas pelas langchain-azure-ai classes de modelo para acesso a endpoints através de projetos ou diretamente.

Usar modelos de chat

Pode facilmente instanciar um modelo usando init_chat_model:

from langchain.chat_models import init_chat_model

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

Todos os modelos Foundry que suportam APIs compatíveis com OpenAI podem ser usados com o cliente, mas precisam de ser implementados primeiro no seu recurso Foundry. Usar project_endpoint (variável de ambiente AZURE_AI_PROJECT_ENDPOINT) requer Microsoft Entra ID para autenticação e a função Azure AI User.

O que este excerto faz: Cria um cliente modelo de chat usando o init_chat_model método de conveniência. O cliente roteia para o modelo especificado através dos endpoints do projeto Foundry ou de endpoints diretos configurados no ambiente.

Referências:

• AzureAIOpenAIApiChatModel

Verifica a tua configuração

Executa uma invocação simples de modelo:

response = model.invoke("Say hello")
response.pretty_print()

================================== Ai Message ==================================
Hello! 👋 How can I help you today?

O que este excerto faz: Envia um prompt básico para verificar endpoint, autenticação e encaminhamento de modelos.

Referências:

• Interface executável LangChain

Modelos configuráveis

Também pode criar um modelo configurável em tempo de execução especificando configurable_fields. Quando omites o model parâmetro, ele torna-se um campo configurável por defeito.

from langchain.chat_models import init_chat_model
from azure.identity import DefaultAzureCredential

configurable_model = init_chat_model(
    model_provider="azure_ai", 
    temperature=0,
	credential=DefaultAzureCredential()
)


configurable_model.invoke(
    "what's your name",
    config={"configurable": {"model": "gpt-5-nano"}},  # Run with GPT-5-nano
).pretty_print()

configurable_model.invoke(
    "what's your name",
    config={"configurable": {"model": "Mistral-Large-3"}}, # Run with Mistral Large
).pretty_print()

================================== Ai Message ==================================

Hi! I'm ChatGPT, an AI assistant built by OpenAI. You can call me ChatGPT or just Assistant. How can I help you today?
================================== Ai Message ==================================

I don't have a name, but you can call me **Assistant** or anything you like! 😊 What can I help you with today?

O que este excerto faz: Cria uma instância de modelo configurável que permite mudar de modelo facilmente no momento da invocação. Como o model parâmetro está em falta em init_chat_model, é por padrão um campo configurável e pode ser fornecido com invoke(). Pode adicionar outros campos configuráveis configurando configurable_fields.

Configurar os clientes diretamente

Também pode criar um cliente modelo de chat usando AzureAIOpenAIApiChatModel o class.

import os

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

model = AzureAIOpenAIApiChatModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model="Mistral-Large-3",
)

Por padrão, AzureAIOpenAIApiChatModel utiliza a API OpenAI Responses. Pode alterar este comportamento passando use_responses_api=False :

import os

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

model = AzureAIOpenAIApiChatModel(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
    model="Mistral-Large-3",
    use_responses_api=False
)

Executar chamadas assíncronas

Utilize credenciais assíncronas caso a sua aplicação fizer chamadas para modelos com ainvoke. Ao utilizar o Microsoft Entra ID para autenticação, utilize a implementação assíncrona correspondente para credenciais:

import os

from azure.identity.aio import DefaultAzureCredential as DefaultAzureCredentialAsync
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

model = AzureAIOpenAIApiChatModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredentialAsync(),
	model="gpt-4.1",
)


async def main():
	response = await model.ainvoke("Say hello asynchronously")
	response.pretty_print()


import asyncio
asyncio.run(main())

================================== Ai Message ==================================
Hello! 👋 How can I help you today?

O que este excerto faz: Cria um cliente assíncrono e executa um pedido não bloqueante com ainvoke.

Referências:

• Credenciais Assíncronas na Azure Identity
• Interface executável LangChain

Fundamentação

Muitos modelos podem realizar raciocínio em múltiplos passos para chegar a uma conclusão. Isto envolve decompor problemas complexos em passos menores e mais geríveis.

from langchain.chat_models import init_chat_model

model = init_chat_model("azure_ai:DeepSeek-R1-0528")

for chunk in model.stream("Why do parrots have colorful feathers?"):
    reasoning_steps = [r for r in chunk.content_blocks if r["type"] == "reasoning"]
    print(reasoning_steps if reasoning_steps else chunk.text, end="")

print("\n")

Parrots have colorful feathers primarily due to a combination of evolutionary ...

Referências:

• Streaming LangChain

Ferramentas do lado do servidor

Os modelos OpenAI implementados no Foundry suportam ciclos de chamada de ferramentas do lado do servidor: os modelos podem interagir com pesquisa web, interpretadores de código e outras ferramentas, e depois analisar os resultados numa única conversação. Se um modelo invocar uma ferramenta do lado do servidor, o conteúdo da mensagem de resposta incluirá conteúdo que representa a invocação e o resultado da ferramenta.

Estas são ferramentas fornecidas pela OpenAI que estendem as capacidades do modelo. Para ver a lista completa de ferramentas suportadas, consulte ferramentas incorporadas.

O exemplo seguinte mostra como usar a pesquisa na web:

from langchain.chat_models import init_chat_model
from langchain_azure_ai.tools.builtin import WebSearchTool
from azure.identity import DefaultAzureCredential

model = init_chat_model("azure_ai:gpt-4.1", credential=DefaultAzureCredential())
model_with_web_search = model.bind_tools([WebSearchTool()])

result = model_with_web_search.invoke("What is the current price of gold? Give me the answer in one sentence.")
result.content[-1]["text"]

As of today, March 24, 2026, the spot price of gold is approximately $4,397.80 per ounce. ([tradingeconomics.com](https://tradingeconomics.com/commodity/gold))

Algumas ferramentas podem exigir a configuração de outros recursos no seu projeto. Use azure-ai-projects para configurar esses recursos e depois referencia-os a partir do LangChain/LangGraph.

O exemplo seguinte mostra como configurar um armazenamento de ficheiros antes de o usar numa ferramenta:

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create vector store and upload file
vector_store = openai.vector_stores.create(name="ProductInfoStore")
vector_store_id = vector_store.id

with open("product_info.md", "rb") as file_handle:
    vector_store_file = openai.vector_stores.files.upload_and_poll(
        vector_store_id=vector_store.id,
        file=file_handle,
    )

O que este snippet faz: Configura um armazenamento vetorial com um ficheiro no Microsoft Foundry para que um modelo possa depois pesquisar o conteúdo desse ficheiro (usado com o FileSearchTool no bloco de código seguinte).

from langchain_azure_ai.tools.builtin import FileSearchTool

model_with_tools = model.bind_tools([FileSearchTool(vector_store_ids=[vector_store.id])])

results = model_with_tools.invoke("Tell me about Contoso products")
print("Answer:", results.content[-1]["text"])
print("Annotations:", results.content[-1]["annotations"])

Answer: Contoso offers the following products:

1. **The widget**
   - Description: A high-quality widget that is perfect for all your widget needs.
   - Price: $19.99

2. **The gadget**
   - Description: An advanced gadget that offers exceptional performance and reliability.
   - Price: $49.99

These products are part of Contoso's main offerings as detailed in their product information documentation.
Annotations: [{'file_id': 'assistant-MvU5SEqUcUBumoLUV5BXxn', 'filename': 'product_info.md', 'type': 'file_citation', 'file_index': 395}]

Utilização de modelos de Foundry em agentes

Use create_agent com modelos conectados ao Foundry para criar ciclos de agente no estilo ReAct.

from langchain.agents import create_agent

agent = create_agent(
    model="azure_ai:gpt-5.2", 
    system_prompt="You're an informational agent. Answer questions cheerfully.", 
)

response = agent.invoke({"messages": "what's your name?"})
response["messages"][-1].pretty_print()

================================== Ai Message ==================================

I’m ChatGPT, your AI assistant.

Ferramentas do lado do servidor também podem ser usadas, mas requerem chamar bind_tools.

from langchain.chat_models import init_chat_model
from langchain.agents import create_agent
from langchain_azure_ai.tools.builtin import ImageGenerationTool

model = init_chat_model("azure_ai:gpt-5.2")
tools = [ImageGenerationTool(model="gpt-image-1.5", size="1024x1024")]
model_with_tools = model.bind_tools(tools)

agent = create_agent(
    model=model_with_tools,
    tools=tools,
    system_prompt="You're an informational agent. Answer questions with graphics.", 
)

Utilização de modelos de embedding

Pode facilmente instanciar um modelo usando init_embeddings:

from langchain.embeddings import init_embeddings

embed_model = init_embeddings("azure_ai:text-embedding-3-small")

O que este excerto faz: Cria um cliente para o modelo de embeddings utilizando o init_embeddings método de conveniência.

Todos os modelos Foundry que suportam APIs compatíveis com OpenAI podem ser usados com o cliente, mas precisam de ser implementados primeiro no seu recurso Foundry. Usar project_endpoint (variável de ambiente AZURE_AI_PROJECT_ENDPOINT) requer Microsoft Entra ID para autenticação e a função Azure AI User.

Ou criar o cliente de embeddings com AzureAIOpenAIApiEmbeddingsModel.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.embeddings import AzureAIOpenAIApiEmbeddingsModel

embed_model = AzureAIOpenAIApiEmbeddingsModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model="text-embedding-3-large",
)

Para a autenticação direta do endpoint e da chave de API:

import os

from langchain_azure_ai.embeddings import AzureAIOpenAIApiEmbeddingsModel

embed_model = AzureAIOpenAIApiEmbeddingsModel(
	endpoint=os.environ["OPENAI_BASE_URL"],
	credential=os.environ["OPENAI_API_KEY"],
	model="text-embedding-3-large",
)

O que este excerto faz: Configura a geração de embeddings para fluxos de trabalho de pesquisa vetorial, recuperação e ranking.

Referências:

• AzureAIOpenAIApiEmbeddingsModel

Exemplo: Execute uma pesquisa por similaridade com um armazenamento vetorial

Use um armazenamento vetorial em memória para experimentação local.

from langchain_core.documents import Document
from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

documents = [
	Document(id="1", page_content="foo", metadata={"baz": "bar"}),
	Document(id="2", page_content="thud", metadata={"bar": "baz"}),
]

vector_store.add_documents(documents=documents)

results = vector_store.similarity_search(query="thud", k=1)
for doc in results:
	print(f"* {doc.page_content} [{doc.metadata}]")

* thud [{'bar': 'baz'}]

O que este excerto faz: Adiciona documentos de exemplo a um armazenamento vetorial e devolve o documento mais semelhante para uma consulta.

Referências:

• Armazenamento vetorial LangChain

Pedidos de depuração com registo

Ative langchain_azure_ai o registo de depuração para inspecionar o fluxo de pedidos.

import logging
import sys

logger = logging.getLogger("langchain_azure_ai")
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler(stream=sys.stdout)
formatter = logging.Formatter(
	"%(asctime)s:%(levelname)s:%(name)s:%(message)s"
)
handler.setFormatter(formatter)
logger.addHandler(handler)

O que faz este excerto: Configura os registos do Python para emitir logs detalhados do SDK que ajudam a solucionar problemas de endpoint ou de payload.

Referências:

• Python logging

Referência de variáveis do ambiente

Pode configurar as seguintes variáveis de ambiente. Estes valores também podem ser configurados ao construir os objetos:

Próximo passo

Conteúdo relacionado

• Visão geral dos modelos de fundição
• Visão geral do SDK Foundry da Microsoft
• Use o LangChain com memória no Foundry
• Use LangChain com o Foundry Agent Service