> Nível 0 de Agent Harness Patterns, uma trilha de padrões sobre como funcionam os agentes de IA. Versão web: https://harnesspatterns.dev/pt/patterns/your-toolkit · Todos os padrões (em inglês): https://harnesspatterns.dev/llms.txt

# Sua caixa de ferramentas

Antes de qualquer agente, quatro peças. Um modelo que só lê e escreve texto, um system prompt que diz quem ele deve ser, uma lista de mensagens que o seu código reenvia toda vez, e ferramentas que ele pode pedir. Tudo o que vem depois neste mapa é construído com elas.

## As quatro peças

- O modelo `model`
   O personagem
   Lê texto, escreve texto. Sabe muito por causa do treinamento, mas nada sobre o seu app, o seu usuário ou o dia de hoje.
- O system prompt `system`
   Equipamento
   Instruções que ficam no topo de toda requisição: quem ele é, suas regras, seu tom e os fatos que ele não tem como saber sozinho.
- As mensagens `messages[]`
   Bolsa
   A conversa até agora. O seu código guarda essa lista e envia tudo a cada chamada.
- As ferramentas `tools`
   Habilidades
   Cartões que descrevem funções que o modelo pode pedir. Ele só pode pedir: quem executa é o seu código.

## O modelo não lembra de nada

É isso que surpreende as pessoas. Um modelo não tem memória entre chamadas. Toda requisição começa do zero, e a única coisa que ele sabe é o que está dentro dela: o system prompt, as mensagens e a lista de ferramentas.

Na animação, a segunda pergunta chega sozinha e o Oráculo pergunta "qual cidade?", mesmo tendo ouvido isso um instante antes. Ele só "lembra" quando o seu código envia as mensagens anteriores de novo. Apps de chat parecem lembrar porque reenviam a conversa inteira toda vez.

Daí saem duas coisas. O histórico é seu: é você quem o guarda, corta e armazena. E cada mensagem que você guarda é enviada de novo a cada chamada, então uma conversa longa custa mais a cada vez.

## Texto, ou uma requisição

Com ferramentas na lista, uma resposta pode ser uma de duas coisas: texto para o usuário, ou um pedido para chamar uma ferramenta com alguma entrada. O modelo nunca executa nada. Ele escreve `get_forecast(city, date)` e para; executar é trabalho do seu código.

Repare na data: o modelo transformou "amanhã" em `2026-09-26` porque o system prompt disse que dia é hoje. Os fatos que ele não tem como saber sozinho ficam ali.

## O código

**Com astorlm:** Um agente do astorlm tem as mesmas quatro peças. Ele guarda o histórico para você entre chamadas de `run()` e, quando o modelo pede uma ferramenta, ele a executa e devolve o resultado. Esse loop é o nível 2.

**Do zero:** As quatro peças e uma única requisição, ainda sem loop. Preencha o bloco `LLM` com o seu próprio endpoint, modelo e chave.

**Com astorlm**

```ts
import { OpenAIProvider, createLocalAgent, tool } from 'astorlm'
import { z } from 'zod'

// A tool: the card the model reads (name, description, schema) plus your code behind it.
const getForecast = tool({
  name: 'get_forecast',
  description: 'Daily forecast for one city: rain chance and min/max temp. date is YYYY-MM-DD.',
  schema: z.object({ city: z.string(), date: z.string() }),
  execute: async ({ city, date }) => forecastLine(city, date), // your code; the model never sees it
})

const agent = await createLocalAgent({
  // Any OpenAI-compatible endpoint: OpenAI, Ollama, LM Studio, vLLM, a proxy…
  provider: new OpenAIProvider({
    baseURL: 'http://localhost:11434/v1', // e.g. Ollama's default address
    model: 'your-model', // e.g. 'llama3.1', 'gpt-4o-mini'
    apiKey: 'YOUR_API_KEY', // local servers usually ignore it
  }),
  systemPrompt: 'You are Nimbus, a weather assistant. Today is 2026-09-25. Answer in one short line.',
  contextFiles: [], // by default astorlm also appends AGENTS.md and CLAUDE.md from the working folder
  tools: [getForecast],
})

// The agent keeps the history for you, so the second run knows about the first.
await agent.run('I’m in Buenos Aires.')
await agent.run('Will it rain tomorrow?') // asks for get_forecast(Buenos Aires, 2026-09-26), runs it, answers
console.log(agent.getMessages().length) // every message so far, resent on every call
```

**TypeScript**

```ts
// The four pieces, with no agent yet: one request in, one reply out. Plain fetch, no SDK.

// Any OpenAI-compatible endpoint: OpenAI, Ollama, LM Studio, vLLM, a proxy…
const LLM = {
  baseURL: 'http://localhost:11434/v1', // e.g. Ollama's default address
  model: 'your-model', // e.g. 'llama3.1', 'gpt-4o-mini'
  apiKey: 'YOUR_API_KEY', // local servers usually ignore it
}

type ToolCall = { id: string; function: { name: string; arguments: string } }
type Message =
  | { role: 'user'; content: string }
  | { role: 'assistant'; content: string | null; tool_calls?: ToolCall[] }

// 1. The system prompt: who it is, its rules, and facts it can't know on its own.
const system = 'You are Nimbus, a weather assistant. Today is 2026-09-25. Answer in one short line.'

// 2. The history. The model remembers nothing between calls: this array IS its memory.
const messages: Message[] = []

// 3. A tool, as the model sees it: a name, a description and its inputs. Never the code.
const tools = [
  {
    type: 'function',
    function: {
      name: 'get_forecast',
      description: 'Daily forecast for one city: rain chance and min/max temp. date is YYYY-MM-DD.',
      parameters: {
        type: 'object',
        properties: { city: { type: 'string' }, date: { type: 'string' } },
        required: ['city', 'date'],
      },
    },
  },
]

// 4. The model: every call sends ALL of the above, and gets back one message.
async function ask(text: string): Promise<Message> {
  messages.push({ role: 'user', content: text })
  const res = await fetch(`${LLM.baseURL}/chat/completions`, {
    method: 'POST',
    headers: { 'content-type': 'application/json', authorization: `Bearer ${LLM.apiKey}` },
    body: JSON.stringify({ model: LLM.model, messages: [{ role: 'system', content: system }, ...messages], tools }),
  })
  const reply: Message = (await res.json()).choices[0].message
  messages.push(reply) // keep it, or the next call won't know it happened
  return reply
}

await ask('I’m in Buenos Aires.') // "Got it! How can I help?"
const reply = await ask('Will it rain tomorrow?')
// The reply is either text (reply.content) or a tool request (reply.tool_calls):
// get_forecast({ city: "Buenos Aires", date: "2026-09-26" })
// Running it and sending the result back, in a loop, is level 2.
```

**Python**

```python
# The four pieces, with no agent yet: one request in, one reply out. Standard library only, no SDK.
import json
import urllib.request

# Any OpenAI-compatible endpoint: OpenAI, Ollama, LM Studio, vLLM, a proxy...
LLM = {
    "base_url": "http://localhost:11434/v1",  # e.g. Ollama's default address
    "model": "your-model",  # e.g. "llama3.1", "gpt-4o-mini"
    "api_key": "YOUR_API_KEY",  # local servers usually ignore it
}

# 1. The system prompt: who it is, its rules, and facts it can't know on its own.
SYSTEM = "You are Nimbus, a weather assistant. Today is 2026-09-25. Answer in one short line."

# 2. The history. The model remembers nothing between calls: this list IS its memory.
messages = []

# 3. A tool, as the model sees it: a name, a description and its inputs. Never the code.
TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_forecast",
            "description": "Daily forecast for one city: rain chance and min/max temp. date is YYYY-MM-DD.",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}, "date": {"type": "string"}},
                "required": ["city", "date"],
            },
        },
    }
]

# 4. The model: every call sends ALL of the above, and gets back one message.
def ask(text):
    messages.append({"role": "user", "content": text})
    request = urllib.request.Request(
        f"{LLM['base_url']}/chat/completions",
        data=json.dumps({
            "model": LLM["model"],
            "messages": [{"role": "system", "content": SYSTEM}, *messages],
            "tools": TOOLS,
        }).encode(),
        headers={"Content-Type": "application/json", "Authorization": f"Bearer {LLM['api_key']}"},
    )
    with urllib.request.urlopen(request) as response:
        reply = json.load(response)["choices"][0]["message"]
    messages.append(reply)  # keep it, or the next call won't know it happened
    return reply

ask("I'm in Buenos Aires.")  # "Got it! How can I help?"
reply = ask("Will it rain tomorrow?")
# The reply is either text (reply["content"]) or a tool request (reply["tool_calls"]):
# get_forecast(city="Buenos Aires", date="2026-09-26")
# Running it and sending the result back, in a loop, is level 2.
```

## O que observar

- **Mantenha o system prompt curto e específico.** Ele vai junto em toda chamada. Papel, regras, tom e os fatos de que o modelo precisa; não um manual.
- **Decida o que o histórico guarda.** Reenviar tudo para sempre fica lento e caro, e uma hora não cabe mais. Cortar e resumir o histórico é um padrão por si só.
- **Um modelo sem ferramentas responde mesmo assim.** Pergunte sobre dados ao vivo e ele vai chutar, com toda a fluência. Se a resposta depende de algo que ele não consegue ver, dê a ele uma ferramenta.

## Padrões relacionados

- [1 · O que é um agente?](https://harnesspatterns.dev/pt/patterns/what-is-an-agent.md)
- [2 · O loop do agente](https://harnesspatterns.dev/pt/patterns/agent-loop.md)
- [3 · Projetando uma ferramenta](https://harnesspatterns.dev/pt/patterns/designing-a-tool.md)
- [7 · A mochila enche](https://harnesspatterns.dev/pt/patterns/compaction.md)