Estudo de LangChain
· Atualizado em
Um modelo simples para cada nota:
- Definição em uma frase
- Por que importa (o que quebra ou muda se você ignorar)
- Exemplo curto ou trecho de código
- Notas relacionadas
- Perguntas em aberto
- Fontes
Modelo de Linguagem Grande (LLM)¶
1. Definição
Um modelo de linguagem grande é um modelo probabilístico treinado com enormes quantidades de texto para prever o próximo token de uma sequência. "Grande" se refere ao número de parâmetros que ele contém, normalmente bilhões ou mais.
2. Por que importa
- Tudo o que um modelo faz (responder, resumir, programar) vem da repetição: prever o próximo token, acrescentá-lo e repetir.
- LLMs são uma tecnologia de uso geral que transformou a forma como as pessoas interagem com computadores.
3. Exemplo
Prompt: "The capital of France is"
Next-token probabilities (illustrative):
- " Paris" → 0.97
- " a" → 0.01
- " located" → 0.005
The model samples one token (usually " Paris"), appends it, and predicts again.
API call that produces this behavior:
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=50,
messages=[{"role": "user", "content": "The capital of France is"}],
)
4. Notas relacionadas
- Tokens: a unidade que o modelo prevê, uma de cada vez
- Janela de contexto: quantos tokens ele consegue processar de uma vez
- Temperatura: como ele escolhe entre os tokens previstos
- Mensagens de sistema / usuário / assistente: como uma conversa é passada para ele
- Chamada de API: como você de fato o usa
5. Perguntas em aberto
- Como os parâmetros funcionam? Eu poderia procurar um exemplo simples para ver como eles são.
6. Fontes
- Glossary: LLM, documentação do Claude
- Large language model, Wikipédia
Tokens¶
1. Definição
É a unidade básica de texto, que pode ser uma palavra inteira ou parte de uma.
2. Por que importa
- Tokens são a unidade com que os LLMs trabalham.
- Janelas de contexto são medidas em tokens.
- O preço das APIs é cobrado por token, então eles determinam o custo.
3. Exemplo
Text: "Tokenization is unbelievable!"
One possible split (exact splits vary by tokenizer):
["Token", "ization", " is", " un", "believ", "able", "!"]
That's 7 tokens for 4 words. Common words are usually one token, while
longer or rarer words get broken into pieces.
Checking real counts with the API:
count = client.messages.count_tokens(
model="claude-sonnet-5-5",
messages=[{"role": "user", "content": "Tokenization is unbelievable!"}],
)
print(count.input_tokens)
Experiment: run the same sentence in English and in another language, and
compare input_tokens. The non-English version will often use more.
4. Notas relacionadas
- LLM: o que produz e consome tokens
- Janela de contexto: seu limite é medido em tokens
- Temperatura: altera as probabilidades do próximo token
- Chamada de API:
usageinforma a contagem de tokens, que define o custo
5. Perguntas em aberto
- Por que os tokenizadores dividem as palavras em pedaços em vez de usar palavras inteiras?
6. Fontes
- Glossary: Tokens, documentação do Claude
- Token counting, documentação do Claude
- Pricing, documentação do Claude
Janela de contexto¶
1. Definição
É a quantidade máxima de texto, medida em tokens, que um LLM consegue manter e consultar enquanto gera uma resposta.
2. Por que importa
- Entrada e saída dividem a mesma janela. Um prompt longo, que ocupa quase toda a janela de contexto, pode deixar pouco espaço para a saída, que pode acabar cortada.
- Ela orienta decisões de design, porque obriga você a encontrar formas de recuperar só o que importa.
3. Exemplo
Say a model has a 10,000-token context window (illustrative number).
| Turn | Input sent (history + new msg) | Reply | Total used |
|------|-------------------------------|-------|-----------|
| 1 | 200 | 300 | 500 |
| 2 | 800 | 300 | 1,100 |
| 3 | 1,400 | 300 | 1,700 |
Each turn's input includes all previous turns, so usage climbs steadily. Keep
going and eventually the input plus the reply won't fit.
In code, the growth looks like this:
messages = []
def chat(user_text):
messages.append({"role": "user", "content": user_text})
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=500,
messages=messages, # the whole history, every time
)
reply = next(
(block.text for block in response.content if block.type == "text"), ""
)
messages.append({"role": "assistant", "content": response.content})
print(response.usage.input_tokens) # watch this number grow
return reply
Experiment: call chat() five times and print input_tokens each time.
4. Notas relacionadas
- LLM: a quem a janela pertence
- Tokens: a unidade em que a janela é medida
- Mensagens de sistema / usuário / assistente: toda mensagem, de qualquer papel, ocupa espaço nela
- Chamada de API: as chamadas não guardam estado, então o histórico inteiro é reenviado e enche a janela
5. Perguntas em aberto
- Que estratégias lidam com conversas que ultrapassam a janela (resumir, truncar, recuperação)?
- Por que os modelos às vezes deixam passar detalhes no meio de entradas longas?
6. Fontes
- Glossary: Context window, documentação do Claude
- Context windows, documentação do Claude
Temperatura¶
1. Definição
Um parâmetro que controla a aleatoriedade do texto que um LLM gera. Valores mais baixos deixam a saída previsível e consistente, enquanto valores mais altos tornam as respostas mais criativas e variadas.
2. Por que importa
- Ela controla o quão consistentes as respostas são. Use uma temperatura baixa para tarefas com uma resposta certa, e uma alta para brainstorming ou escrita criativa.
- Mesmo com temperatura 0, não há garantia de respostas idênticas: a saída de um LLM não é totalmente determinística.
- Os modelos atuais do Claude não aceitam o parâmetro
temperature, embora outros provedores ainda possam oferecê-lo.
3. Exemplo
Prompt: "The sky is"
Next-token probabilities (illustrative):
- " blue" → 0.70
- " clear" → 0.15
- " gray" → 0.10
- " falling" → 0.05
Effect of temperature, taking these as the probabilities at 1.0:
- Below 1.0: the distribution sharpens, so " blue" dominates.
- At 1.0: the probabilities stay as listed.
- Above 1.0: the distribution flattens, so " falling" becomes a real possibility.
A small simulation, with no API needed:
probs = {" blue": 0.70, " clear": 0.15, " gray": 0.10, " falling": 0.05}
for t in [0.2, 0.7, 1.0, 2.0]:
weights = {token: p ** (1 / t) for token, p in probs.items()}
total = sum(weights.values())
print(t, {token: round(w / total, 2) for token, w in weights.items()})
Output:
0.2 {' blue': 1.0, ' clear': 0.0, ' gray': 0.0, ' falling': 0.0}
0.7 {' blue': 0.84, ' clear': 0.09, ' gray': 0.05, ' falling': 0.02}
1.0 {' blue': 0.7, ' clear': 0.15, ' gray': 0.1, ' falling': 0.05}
2.0 {' blue': 0.47, ' clear': 0.22, ' gray': 0.18, ' falling': 0.13}
Experiment: add 0.01 and 10 to the list, and see what happens at both extremes.
4. Notas relacionadas
- LLM: o comportamento que ela altera
- Tokens: ela atua sobre as probabilidades do próximo token
- Chamada de API: os provedores que ainda a oferecem a recebem como parâmetro da chamada
5. Perguntas em aberto
- Qual a diferença entre top-p, top-k e temperatura, e dá para combiná-los?
- Por que a temperatura 0 não é totalmente determinística?
6. Fontes
- Glossary: Temperature, documentação do Claude
- Migrating to API version 2026-10-21, documentação do Claude
- Softmax function, Wikipédia
Mensagens de sistema / usuário / assistente¶
1. Definição
Mensagens são os turnos, cada um identificado por um papel, que compõem uma conversa com um LLM.
- Mensagens de sistema dão instruções gerais e contexto para o comportamento do assistente.
- Mensagens de usuário contêm as perguntas ou prompts específicos dos usuários.
- Mensagens de assistente representam as respostas geradas pelo modelo com base nas mensagens anteriores de sistema ou de usuário.
2. Por que importa
- Papéis são uma ferramenta de design.
- Os três papéis contam para a janela de contexto.
3. Exemplo
Same question, with and without a system message:
# No system message
messages=[{"role": "user", "content": "What is a token?"}]
# With a system message
system="You are a teacher for beginners. Answer in two sentences, no jargon."
messages=[{"role": "user", "content": "What is a token?"}]
A multi-turn conversation, where I include the assistant's previous reply:
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=300,
system="You are a teacher for beginners. Answer in two sentences, no jargon.",
messages=[
{"role": "user", "content": "What is a token?"},
{"role": "assistant", "content": "A token is a small chunk of text the model reads and writes."},
{"role": "user", "content": "Why does it matter for cost?"},
],
)
Experiment: ask the third question alone, then with the full history. Compare the answers. Without the history, the model doesn't know what "it" refers to.
4. Notas relacionadas
- LLM: quem lê as mensagens
- Janela de contexto: todos os papéis contam para ela
- Chamada de API: as mensagens e o
systemsão campos da requisição
5. Perguntas em aberto
- Quanto a mensagem de sistema realmente muda o comportamento, em comparação com colocar o mesmo texto na primeira mensagem de usuário?
6. Fontes
- Using the Messages API, documentação do Claude
- Messages API reference, documentação do Claude
Chamada de API¶
1. Definição
Uma chamada de API a um modelo é uma requisição HTTP em que você envia suas mensagens e configurações para um servidor, e ele devolve a resposta do modelo.
2. Por que importa
- É assim que qualquer projeto interage com LLMs.
- Cada requisição não guarda estado, então você precisa reenviar a conversa inteira toda vez.
3. Exemplo
Request (curl):
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"system": "You are a helpful assistant that explains things simply.",
"messages": [
{"role": "user", "content": "What is a token?"}
]
}'
Same call in Python:
import anthropic
client = anthropic.Anthropic() # reads ANTHROPIC_API_KEY from the environment
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
system="You are a helpful assistant that explains things simply.",
messages=[{"role": "user", "content": "What is a token?"}],
)
text = next(
(block.text for block in response.content if block.type == "text"), ""
)
print(text)
print(response.stop_reason)
print(response.usage.input_tokens, response.usage.output_tokens)
Trimmed response:
{
"id": "msg_01...",
"role": "assistant",
"content": [{"type": "text", "text": "A token is a small chunk of text..."}],
"stop_reason": "end_turn",
"usage": {"input_tokens": 25, "output_tokens": 80}
}
Experiment: set max_tokens to 10 and watch stop_reason change. Then deliberately use a wrong API key and read the error that comes back.
4. Notas relacionadas
- LLM: quem responde à chamada
- Tokens: o
usageda resposta faz a contagem deles - Janela de contexto: reenviar o histórico a cada chamada é o que a enche
- Temperatura: uma configuração que alguns provedores ainda aceitam na chamada, embora os modelos atuais do Claude não aceitem
- Mensagens de sistema / usuário / assistente: o corpo de toda requisição
5. Perguntas em aberto
- O que meu código deve fazer quando uma chamada falha ou atinge um limite de taxa?
6. Fontes
- Messages API reference, documentação do Claude
- Using the Messages API, documentação do Claude
- Stop reasons and fallback, documentação do Claude
Saída estruturada¶
1. Definição
Uma técnica para fazer o modelo responder em um formato previsível e legível por máquina, normalmente JSON.
2. Por que importa
- É o formato em que se deve confiar ao salvar em um banco de dados, enviar para uma API etc.
3. Exemplo
Same fact, two possible free-text replies:
Ana is 31 years old.
The person's name is Ana, and she's 31.
With structured output, the shape is always the same:
{"name": "Ana", "age": 31}
The native way, using a Pydantic model as the schema:
from pydantic import BaseModel
class Person(BaseModel):
name: str
age: int
response = client.messages.parse(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Ana is 31 years old."}],
output_format=Person,
)
print(response.parsed_output) # name='Ana' age=31
Experiment: drop the schema, ask for JSON in the prompt instead, and run json.loads() on the reply a few times. See how often it breaks.
4. Notas relacionadas
- Ferramentas: ferramentas também usam um schema, que descreve os argumentos de uma função, e não a resposta
- Chamada de API: o schema vai junto com a requisição
- Runnable / LCEL: parsers de saída transformam a resposta em dados, como uma etapa de uma chain
5. Perguntas em aberto
- O que acontece quando a saída segue o schema, mas os valores estão errados?
6. Fontes
- Structured outputs, documentação do Claude
Ferramentas¶
1. Definição
Uma forma de deixar seu modelo pedir ao seu código que execute algo e usar o resultado na resposta.
É um mecanismo que permite a um modelo de IA gerar requisições estruturadas, normalmente em JSON, para invocar funções ou APIs externas. Há duas formas de invocar uma ferramenta:
- Invocação automática de ferramentas: o LLM decide se faz sentido chamar uma ferramenta ou não. Essa é a escolha padrão.
- Invocação forçada de ferramentas: o desenvolvedor do sistema configura o modelo para sempre usar determinadas ferramentas. Isso é ideal para pipelines determinísticos, como a extração de dados estruturados. Alguns modelos, incluindo o Claude Sonnet 5.5 e o Opus 5.5, não oferecem suporte a isso.
2. Por que importa
- LLMs preveem texto plausível, então não são confiáveis para cálculos exatos.
- Usar ferramentas amplia o poder e a utilidade do modelo.
- O modo de invocação define se é o modelo ou o desenvolvedor quem escolhe quando uma ferramenta é executada.
3. Exemplo
The model doesn't run anything itself. It asks, my code runs the function, and I send back the result:
tools = [{
"name": "multiply",
"description": "Multiply two numbers.",
"input_schema": {
"type": "object",
"properties": {"a": {"type": "number"}, "b": {"type": "number"}},
"required": ["a", "b"],
},
}]
messages = [{"role": "user", "content": "What is 48213 * 9177?"}]
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=300,
tools=tools,
messages=messages,
)
# response.stop_reason is "tool_use": the model is asking for the function
call = next(block for block in response.content if block.type == "tool_use")
result = call.input["a"] * call.input["b"] # my code does the math
messages.append({"role": "assistant", "content": response.content})
messages.append({
"role": "user",
"content": [{"type": "tool_result", "tool_use_id": call.id, "content": str(result)}],
})
final = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=300,
tools=tools,
messages=messages,
)
text = next(block.text for block in final.content if block.type == "text")
print(text)
Experiment: ask the same question without the tool and compare the answer with the exact result.
Veja mais exemplos no artigo do n8n LLM Tool Calling: How It Works and How To Implement It.
4. Notas relacionadas
- Saída estruturada: também usa um schema, mas para dar forma à resposta, e não aos argumentos de uma função
- Mensagens de sistema / usuário / assistente: o pedido da ferramenta e o resultado trafegam como mensagens
- Chamada de API: as ferramentas são um campo da requisição, e cada ida e volta é uma nova chamada
- O loop do agente: onde o modelo continua tomando essa decisão
5. Perguntas em aberto
- Como o modelo decide qual ferramenta chamar, e o que acontece se ele escolher a errada?
- Qual a diferença entre passar uma função Python diretamente e usar o decorador
@tool?
6. Fontes
- Tool use with Claude, documentação do Claude
- LLM Tool Calling: How It Works and How To Implement It, blog do n8n
Runnable / LCEL: compondo etapas¶
1. Definição
Um Runnable é a interface padrão do LangChain para um componente, e a LangChain Expression Language (LCEL) é a sintaxe | para compor Runnables em uma chain. Prompts, modelos e parsers de saída são todos Runnables.
2. Por que importa
- Todos os processos são como pipelines. Compor essas etapas representa um pipeline de ponta a ponta em um contexto de IA.
3. Exemplo
A three-step chain, composed with the | operator:
from langchain_anthropic import ChatAnthropic
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
prompt = ChatPromptTemplate.from_template("Explain {topic} in one sentence.")
model = ChatAnthropic(model="claude-sonnet-5-5")
parser = StrOutputParser()
chain = prompt | model | parser
print(chain.invoke({"topic": "tokens"}))
Each step's output is the next step's input:
{"topic": "tokens"} → prompt → messages → model → AI message → parser → string
Experiment: remove the parser from the chain and print the result. It's now an AI message object instead of a string.
4. Notas relacionadas
- Mensagens de sistema / usuário / assistente: o que a etapa do prompt produz
- Chamada de API: o que a etapa do modelo faz por baixo dos panos
- Saída estruturada: uma etapa de parser pode devolver dados estruturados em vez de uma string
5. Perguntas em aberto
- O que a LCEL me oferece que uma função Python comum não oferece?
6. Fontes
- Runnable, referência do LangChain
O loop do agente¶
1. Definição
O loop do agente é uma série de etapas em que o modelo decide repetidamente se chama uma ferramenta ou dá a resposta final, e continua no loop até produzir uma resposta final ou até uma condição de parada ser atingida.
2. Por que importa
- Agentes resolvem problemas em que as etapas não podem ser conhecidas de antemão. Se as etapas forem fixas e previsíveis, um agente pode ser a escolha errada, e o mesmo vale para tarefas de baixo valor.
3. Exemplo
Veja os exemplos na página Agents do LangChain.
4. Notas relacionadas
- Ferramentas: o que o modelo decide se chama ou não a cada etapa
- Chamada de API: cada etapa do loop é uma nova chamada
5. Perguntas em aberto
- N/A
6. Fontes
- Agents, documentação do LangChain