# Conversational Agent: step by step

From the Lero API docs: https://lero.studio/docs/en#agente-guia. Everything in one file: https://lero.studio/docs/en/llms-full.txt.

The Conversational Agent is a real-time voice call. HTTP only does discovery and signaling; then audio and events flow peer-to-peer over WebRTC. Typical latency ~1 s, with barge-in (the person interrupts and the agent stops).

1. **Discover.** `GET /v1/agents` returns the versions, LLMs and voices your key can use.
2. **Connect.** In the WebRTC client, create the `chat` data channel before the offer, add 1 audio track (the microphone) and wait for ICE gathering.
3. **Signaling.** Send the SDP offer to `POST /v1/agents/conversation` (from your backend, with the key) and apply the SDP answer. The call starts and the agent greets.
4. **Custom agent (optional).** In the same POST, `instrucoes` (system prompt), `conhecimento` (knowledge base), `abertura`, `palavras` and the settings make the agent yours.
5. **Live context (optional).** During the call, send on `chat` what the agent needs to see: the code in a live coding, the cart, the screen.
6. **Events.** Read the transcript, the state and the latency of each turn on `chat`.
7. **Hang up.** Close the `RTCPeerConnection`.

Live context and control, over the data channel (every message needs the `type` field):

```javascript
// live context: one panel per key, always the latest version (send the full text on change, ~every 2 s)
chat.send(JSON.stringify({ type: "lero-contexto", chave: "codigo", texto: editor.getValue() }));
chat.send(JSON.stringify({ type: "lero-contexto", chave: "testes", texto: "3/5 testes passaram", responder: true }));

// system note: the person does not hear it; the agent acts on the next free turn (responder: false only stores it)
chat.send(JSON.stringify({ type: "lero-instrucao", texto: "O tempo da fase 2 acabou. Passe para a fase 3." }));

// exact utterance, bypasses the LLM
chat.send(JSON.stringify({ type: "lero-falar", texto: "Faltam 5 minutos." }));
```

| message | fields | what it does |
|---|---|---|
| `lero-contexto` | `chave` (up to 60), `texto` (up to 20,000), `responder` | One live panel per key (up to 8). Only the latest version enters the next reply. Empty `texto` removes it. |
| `lero-instrucao` | `texto` (up to 4,000), `responder` | System note the person does not hear: phase change, timer, hint. |
| `lero-falar` | `texto` (up to 2,000) | The agent says exactly the text, bypassing the LLM. |

Events on `chat` (field `tipo`):

| tipo | fields |
|---|---|
| `estado` | `estado`: conectado, na_fila, ouvindo, pensando, falando, aviso_fim, encerrada; `motivo` at the end |
| `fala` | `papel` (pessoa or agente), `texto`, `final`, `interrompido`: the live transcript |
| `latencia` | `total_ms` and the turn stages |
| `ignorado` | a short backchannel ("uhum") that did not interrupt the agent |

The call ends when you close the connection, on the silence goodbye (if `silencio_s` is on) or after 10 minutes without speech. Every call is recorded (audio, transcript and agent config) for quality review.