Documentação de IA agêntica do LangChain: Ferramentas e Modo JSON
A maioria das documentação de IA agêntica do LangChain assume uma classe de modelo própria do fornecedor, mas qualquer endpoint compatível com OpenAI funciona com ChatOpenAI assim que você define uma base URL. Este guia conecta o LangChain a esta API e constrói um agente com chamada de funções passo a passo.
Atualizado
Pontos principais
- Use ChatOpenAI com base_url definida para esta API e modelo definido como
uncensored. - Chamada de funções e modo JSON são suportados, então bind_tools e response_format funcionam conforme documentado.
- Limite loops de agente, valide argumentos de ferramentas e mantenha max_concurrency em ou abaixo de 8 em uma chave completa.
- O streaming via SSE retorna o uso de tokens no final, o que ajuda a rastrear o custo de cada execução de agente.

O que você precisa antes de começar
Se você está lendo documentação de IA agêntica do LangChain e se perguntando o que muda quando o modelo não é do fornecedor dos exemplos, a resposta é muito pouco. Um agente no LangChain é um loop: o modelo lê a conversa, decide se chama uma ferramenta, seu código executa a ferramenta e o resultado volta para o modelo até que ele produza uma resposta final. O endpoint do modelo só precisa suportar chat completions com chamada de funções, e esta API faz isso.
Você precisa de três coisas: uma chave de API da página de chaves, Python 3.10 ou mais recente e os pacotes abaixo. A base URL é https://api.unlimitedaiapi.com/v1 e o ID do modelo é uncensored. É um único modelo de pesos abertos executado por um provedor independente, então não há lista de modelos para escolher; GET /v1/models retorna isso para descoberta de cliente.
pip install -U langchain langchain-openai
export UNLIMITED_API_KEY="your-key-here"Passo 1: conectar ChatOpenAI ao endpoint
A classe ChatOpenAI do LangChain aceita uma base_url personalizada. Tudo o mais permanece igual, incluindo invoke, stream, batch e variantes assíncronas.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0.2,
)
print(llm.invoke("Reply with one short sentence.").content)
Se isso imprimir uma frase, autenticação, roteamento e o nome do modelo estão corretos. A autenticação é o cabeçalho padrão Authorization: Bearer, que a classe adiciona para você. Um erro comum é omitir /v1 na base URL, o que geralmente faz a primeira chamada falhar.
Passo 2: definir ferramentas e vinculá-las
Ferramentas são funções Python simples com docstring. A docstring e as type hints tornam-se o esquema que o modelo vê, então escreva-as como se estivesse explicando a função a um novo colega.
import os
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_order_status(order_id: str) -> str:
'''Look up the status of an order by its ID, for example A100.'''
return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
llm_with_tools = llm.bind_tools([get_order_status])
ai = llm_with_tools.invoke("Where is order A100?")
print(ai.tool_calls)
A lista impressa contém uma chamada com o nome get_order_status e argumentos como {"order_id": "A100"}. Por baixo dos panos, LangChain envia sua função como uma entrada no array tools da solicitação de chat completions, e a API suporta tools, tool_choice e tool_calls em streaming. Para forçar uma chamada de função, passe tool_choice para bind_tools.
Por que a temperatura é baixa
Agentes encadeiam várias chamadas de modelo, então um único argumento mal formado pode desviar uma execução. Uma temperatura de 0 a 0,2 torna a seleção de ferramentas mais repetível. Aumente-a apenas para a etapa de resposta final se quiser prosa mais variada.
Passo 3: executar o loop do agente
Escrever o loop você mesmo leva quinze linhas e mostra exatamente o que acontece em cada etapa, o que ajuda quando algo dá errado. Os resultados das ferramentas voltam para o modelo como objetos ToolMessage, que se tornam mensagens role: "tool" na rede.
import os
from langchain_core.messages import HumanMessage, ToolMessage
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_order_status(order_id: str) -> str:
'''Look up the status of an order by its ID, for example A100.'''
return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
tools = {"get_order_status": get_order_status}
llm_with_tools = llm.bind_tools(list(tools.values()))
messages = [HumanMessage("Where is order A100, and what about A101?")]
for _ in range(5): # hard cap on loop length
ai = llm_with_tools.invoke(messages)
messages.append(ai)
if not ai.tool_calls:
break
for call in ai.tool_calls:
result = tools[call["name"]].invoke(call["args"])
messages.append(ToolMessage(content=str(result), tool_call_id=call["id"]))
print(ai.content)
Observe o range(5). Um agente sem limite de etapas pode ficar em loop infinito em um resultado de ferramenta confuso, e cada passagem custa tokens de entrada para toda a conversa até agora. Cinco é um teto razoável para tarefas simples; aumente-o deliberadamente.
Usando o helper de agente pré-construído
Versões recentes do LangChain incluem um helper que executa esse loop para você. O nome e o caminho de importação mudaram entre versões, então confirme-os contra a documentação da versão instalada. Na linha 1.x atual, parece assim:
import os
from langchain.agents import create_agent
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_order_status(order_id: str) -> str:
'''Look up the status of an order by its ID, for example A100.'''
return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
agent = create_agent(llm, tools=[get_order_status], system_prompt="You are a concise support assistant.")
result = agent.invoke({"messages": [{"role": "user", "content": "Where is order A100?"}]})
print(result["messages"][-1].content)
Use o helper quando quiser o padrão, e o loop escrito à mão quando precisar de regras de parada personalizadas, registro por etapa ou resultados de ferramentas que você deseja filtrar antes que o modelo os veja.
Saída estruturada com modo JSON
Agentes frequentemente precisam passar dados para outro código, como um plano, uma classificação ou uma lista de campos extraídos. O modo JSON força a resposta a ser um objeto JSON válido. No LangChain, você pode passá-lo através de bind:
import json
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
json_llm = llm.bind(response_format={"type": "json_object"})
msg = json_llm.invoke(
"Extract the city and country from: 'I moved to Lyon, France last spring.' "
"Answer as JSON with the keys city and country."
)
print(json.loads(msg.content))
Mencione a palavra JSON no prompt e descreva as chaves que você espera, como no exemplo. O modo JSON garante a sintaxe, não o seu esquema, então ainda valide o objeto analisado (com Pydantic, por exemplo) e trate uma chave ausente.
Limites, streaming e custo para execuções de agente
Agentes fazem muitas chamadas em pouco tempo, então os limites da conta importam mais do que para um chatbot simples. Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto. Uma chave de teste permite 2 e 60. Se você distribuir com batch ou executar vários agentes ao mesmo tempo, limite a simultaneidade na configuração:
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
)
prompts = ["Name one prime number.", "Name one even number.", "Name one square number."]
answers = llm.batch(prompts, config={"max_concurrency": 8})
for a in answers:
print(a.content)
Use 2 em vez de 8 na chave de teste. Para agentes interativos, llm.stream(...) retorna tokens via SSE conforme são gerados, e os números de uso chegam ao final do streaming.
O custo é fácil de estimar. Uma execução de 5 etapas que usa em média 4.000 tokens de entrada e 300 tokens de saída por etapa usa 20.000 tokens de entrada e 1.500 tokens de saída no total, o que resulta em $0,003 + $0,00075 = $0,00375 por execução a $0,15 e $0,50 por 1 milhão de tokens. A página de preços tem as tarifas, e a documentação lista os parâmetros e cabeçalhos de solicitação, incluindo X-Request-Id para rastrear uma única chamada com falha.
Projetando ferramentas que o modelo pode usar
A maioria das falhas de agente remonta às ferramentas, não ao loop. Algumas regras ajudam com qualquer modelo:
- Mantenha cada ferramenta estreita. Uma ferramenta chamada
get_order_statusfunciona melhor do que uma chamadadatabase_queryque aceita texto livre. - Use tipos de argumento simples: strings, inteiros e enums curtos. Objetos profundamente aninhados dão ao modelo mais maneiras de errar um campo.
- Retorne resultados curtos e simples. Uma ferramenta que despeja 50.000 caracteres na conversa preenche a janela de contexto e aumenta o custo de cada etapa posterior.
- Retorne erros como texto, como "order_id deve se parecer com A100", em vez de levantar exceções que terminam a execução.
Teste o agente em alguns prompts reais com o crédito de teste de $0,50 antes de escalar. Novos usuários o recebem com um clique na página de chaves, e ele é válido por 7 dias.
Armadilhas para verificar primeiro
- Chamada de ferramenta nunca aparece. Torne a docstring específica, diminua a temperatura ou force a chamada com
tool_choice. - Argumentos inválidos. Valide dentro da ferramenta e retorne uma string de erro clara, para que o modelo possa se corrigir na próxima etapa.
- Crescimento do contexto. A janela é de 100.000 tokens incluindo a resposta. Remova saídas antigas de ferramentas antes que preencham a janela.
Mais guias
Perguntas e respostas
Qual classe do LangChain funciona com esta API?
ChatOpenAI de langchain-openai. Defina base_url para https://api.unlimitedaiapi.com/v1, model para uncensored e passe sua chave como api_key.
A API suporta chamada de funções para agentes?
Sim. Ela aceita os parâmetros tools e tool_choice, retorna tool_calls (também em streaming) e recebe resultados de volta como mensagens com role: tool.
O LangChain pode analisar saída estruturada por meio desta API?
Sim, por meio do modo JSON: defina response_format para um tipo json_object. Garante sintaxe JSON válida, então valide os campos você mesmo.
Quantos agentes posso executar em paralelo?
Uma chave completa permite 8 requisições simultâneas e 300 por minuto. A chave de teste permite 2 simultâneas e 60 por minuto.
Sua chave está a um formulário de distância
Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.