> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weve.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentes

> O assistente que o club cria, alimenta com o próprio material e oferece aos alunos.

Um agente é um assistente de conversa: quem administra escreve o **papel** dele (as instruções)
e escolhe o **material** de que ele sabe; o aluno pergunta, e a resposta cita de onde veio.

## Quem conversa

O agente é um **entregável**, como o curso e a mentoria: o `id` dele é o que se põe numa
entrega. Quem pergunta é quem tem uma matrícula ativa numa entrega que o abre — reembolso, prazo
de acesso, bônus de turma e entrega aberta valem sem configuração a mais. Um "assistente para
todos os alunos" é só uma entrega aberta.

As conversas são **da pessoa**: depois que o acesso acaba, o aluno continua lendo o que conversou
(`has_history`), e só não pergunta mais.

<Warning>
  A equipe do club lê as conversas dos alunos — é como se descobre que o agente está respondendo
  errado. O classroom avisa isso ao aluno antes da primeira pergunta (`staff_can_read`).
</Warning>

## O que o agente sabe

O material é escolhido da **biblioteca de mídia**: PDF, texto (`.txt`) ou Markdown, até 50
arquivos. Ao entrar no agente, o arquivo vai para uma fila de leitura:

| `status`   | significa                                   |
| ---------- | ------------------------------------------- |
| `pending`  | na fila                                     |
| `indexing` | sendo lido agora                            |
| `ready`    | pronto para as perguntas                    |
| `failed`   | não deu para ler — o motivo está em `error` |

O PDF é lido em lotes de páginas, e cada trecho guarda de que páginas saiu: é o que permite a
citação dizer "Apostila (p. 12–13)". O mesmo arquivo em dois agentes é lido uma vez, e o arquivo
que muda na biblioteca é lido de novo sozinho. Enquanto é material de um agente, o arquivo não
vira público nem pode ser excluído.

Cada pergunta leva junto o material de uma de duas formas, e quem decide é o **tamanho**:

* material pequeno vai **inteiro** — o agente de uma apostila curta lê tudo, sempre;
* material grande é **buscado**: por palavra (sem acento, pelo radical) e por significado, e a
  pergunta leva os trechos mais relevantes.

[`POST .../knowledge/search`](/api-reference/agents/knowledge-search) mostra exatamente o que
uma pergunta levaria, sem chamar o modelo.

## Perguntar

A resposta chega em **streaming** ([ver o formato](/api-reference/agents/classroom-message-send)).
Três garantias que a tela pode assumir:

* **A mesma pergunta não é feita duas vezes.** O `id` da pergunta é gerado por quem envia; repetir
  o envio responde `409 message_exists`. E a conversa responde uma coisa por vez
  (`409 generation_in_progress`).
* **A resposta não depende da conexão.** Fechar a aba no meio não interrompe nada; a resposta
  completa aparece na conversa.
* **A falha não some com o que foi escrito.** A resposta que falha fecha `failed` com o texto que
  chegou a ser gerado, e a conversa continua aceitando perguntas.

## Os tetos

Dois limites, conferidos **antes** de chamar o modelo — pergunta recusada não custa nada:

* **por aluno**: `daily_message_limit` perguntas a cada agente em 24 horas corridas (padrão 50).
  Apagar conversas não devolve perguntas; `limits.resets_at` diz quando a mais antiga sai da
  janela. Estourado, `429 daily_limit_reached`.
* **por club**: um orçamento mensal de IA, definido pela plataforma. Estourado,
  `429 club_budget_exhausted` para todos os alunos até virar o mês.

O gasto é contado resposta a resposta, em **microdólares** (1.000.000 é um dólar), e ler o PDF do
material também conta. [`GET /ai-usage`](/api-reference/agents/ai-usage) mostra o orçamento do mês
e o gasto por agente.

## O modelo

Modelo, temperatura e tamanho da resposta **não são configuração do club**: são da plataforma,
iguais para todos os agentes. O que diferencia um agente de outro são as instruções e o material.


## Related topics

- [Limites de uso](/essentials/rate-limits.md)
- [Onde a mídia é usada](/api-reference/media/usage.md)