# Documentação — hobots

SDK JavaScript da **Hobots** para robôs (RPAs) e integrações. Cliente HTTP puro, sem dependências de runtime, Node 18+.

**O agente é a própria tarefa.** Não existe `init()` nem slug: a única chamada a `register()`/`start()` configura o processo (credenciais do ambiente, heartbeat sempre ligado, captura de erros não tratados) e diz o que o robô faz. O objeto global `hobots` expõe a execução atual — `hobots.log`, `hobots.items`, `hobots.progress`, `hobots.transaction`… — de qualquer lugar do programa.

| Modo | Chamada | Para quê |
| --- | --- | --- |
| **Sob demanda** | `hobots.register(handler, options?)` | O robô faz polling e executa uma solicitação do app (formulário do agente/agendamento) por vez — módulo **Trabalhos**. |
| **Sempre ligado** | `hobots.start(handler, options?)` | O robô abre a própria execução e roda o handler (o seu loop) dentro dela; a plataforma recebe logs, itens e progresso. |

Uma chamada por processo: um processo é um agente, e um agente faz uma coisa.

## Páginas

- [Getting started](./getting-started.md) — instalação, envs, o primeiro agente nos dois modos, encerramento.
- [Execuções](./runs.md) — handler, o objeto `hobots`, itens, progresso, anexos, cancelamento automático, retry, concorrência, idempotência.
- [Conceitos](./concepts.md) — o vocabulário: agente, execução, evento, issue, transaction, step, heartbeat, instância, claim.
- [Referência de API](./api-reference.md) — assinaturas, tabelas de opções e tempos.
- [Protocolo & transporte](./protocol.md) — Client Secret, endpoints (`/v1/ingest`, `/v1/runs/*`), envelope, retries, claim atômico.

## Exemplo mínimo

```js
import hobots from 'hobots'; // HOBOTS_CLIENT_SECRET e HOBOTS_INSTANCE_ID no ambiente

hobots.register(async params => {
  hobots.log.info(`processando lote ${params.lote}…`);
  hobots.items.succeeded({ numero_nota: '123' }, { id: '123' });
  hobots.log.success('concluído'); // o retorno do handler é ignorado — reporte por log/itens
});
```

> Exemplos runnable em [`packages/hobots-sdk-demos`](../../hobots-sdk-demos).