# Descoberta de serviços

> Como os clientes LMSP encontram um serviço local por configuração manual, sondagem de loopback e mDNS/DNS-SD opcional, e como ler o documento well-known de descrição do serviço.

Source: https://madeforagent.com/pt-br/lmsp/1.0/discovery/
Language: pt-BR
Specification: LMSP 1.0 (draft)
Updated: 2026-11-08

## 3.1 Métodos de descoberta {#methods}

Um cliente descobre um serviço tentando estes métodos em ordem:

1. **Configuração manual.** O usuário informa diretamente o endereço do serviço.
2. **Sondagem de endereços locais convencionais.** O cliente requisita `/.well-known/lmsp.json` em endereços candidatos. Os candidatos convencionais são `http://127.0.0.1:17832` e `http://[::1]:17832`.
3. **Descoberta na LAN.** O cliente busca `_lmsp._tcp.local.` com mDNS e DNS-SD.

Um método tem sucesso quando produz uma descrição de serviço válida ([seção 3.3](https://madeforagent.com/pt-br/lmsp/1.0/discovery.md#service-description)). Um endereço informado manualmente pelo usuário sempre tem precedência sobre os descobertos.

## 3.2 Anúncio na LAN {#mdns}

O DNS-SD usa registros PTR para encontrar instâncias de serviço, registros SRV para obter o host e a porta, e registros TXT para transportar uma pequena quantidade de informações extras. Combinado com o mDNS, oferece descoberta sem configuração em uma rede local ([RFC 6763](https://www.rfc-editor.org/rfc/rfc6763), [RFC 6762](https://www.rfc-editor.org/rfc/rfc6762)).

Um exemplo de anúncio:

```text
Service type:   _lmsp._tcp.local.
Instance name:  Workstation LMSP._lmsp._tcp.local.

TXT record:
  v=1
  id=svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2
  path=/
  auth=pairing
```

| Chave TXT | Significado |
| --- | --- |
| `v` | Versão do formato do anúncio. `1` para o LMSP 1.0. |
| `id` | O ID do serviço, igual a `service.id` na descrição do serviço. |
| `path` | Caminho de URL da raiz do serviço. Os clientes requisitam `{path}.well-known/lmsp.json`. |
| `auth` | Dica de autenticação. `pairing` significa que o cliente deve fazer o pareamento antes de usar o serviço. |

Regras:

- Um serviço **NÃO DEVE** colocar tokens de acesso, listas de modelos, caminhos de arquivos nem qualquer outra informação sensível no registro TXT. O registro apenas localiza o serviço. As capacidades reais **DEVEM** ser lidas da descrição do serviço.
- Um serviço **DEVE** manter o anúncio mDNS desativado por padrão. Ele só é ativado quando o usuário liga explicitamente a descoberta na LAN. Um serviço usado apenas na máquina local não faz anúncio.
- Um serviço que anuncia na LAN precisa escutar além do loopback, o que só é permitido no modo LAN ([seção 10.5](https://madeforagent.com/pt-br/lmsp/1.0/security.md#lan)).
- Um cliente **DEVE** tratar o registro TXT como uma dica não verificada e confirmar o serviço lendo a sua descrição.

## 3.3 Descrição do serviço {#service-description}

```http
GET /.well-known/lmsp.json
```

Um serviço **DEVE** servir este documento como `application/json`, sem exigir autenticação.

```json
{
  "protocol": "lmsp",
  "versions": ["1.0"],
  "service": {
    "id": "svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2",
    "name": "Workstation Local Models",
    "version": "1.0.0"
  },
  "interfaces": [
    {
      "kind": "lmsp",
      "version": "1.0",
      "url": "http://127.0.0.1:17832/lmsp/v1",
      "transport": "http+json"
    },
    {
      "kind": "openai",
      "version": "responses+chat",
      "url": "http://127.0.0.1:17832/v1",
      "transport": "http+json"
    }
  ],
  "capabilities": {
    "streaming": true,
    "tasks": true,
    "event_resume": true,
    "conversations": true,
    "model_management": true
  },
  "authentication": {
    "type": "bearer",
    "pairing_url": "http://127.0.0.1:17832/lmsp/v1/pair"
  },
  "openapi": "http://127.0.0.1:17832/lmsp/v1/openapi.json"
}
```

| Campo | Significado |
| --- | --- |
| `protocol` | Sempre `"lmsp"`. |
| `versions` | As versões do LMSP que o serviço suporta, como strings `major.minor`. |
| `service` | `id` é um identificador estável do serviço, `name` um nome de exibição e `version` a versão do software do serviço. |
| `interfaces` | As interfaces oferecidas. Cada uma tem um `kind` (`lmsp`, `openai` ou `ollama`), uma `version`, uma `url` base e um `transport`. Para `openai`, `version` nomeia as famílias de API atendidas, como `responses+chat`. |
| `capabilities` | Flags booleanas de recursos, listadas abaixo. |
| `authentication` | `type` é `bearer`. `pairing_url` é onde os clientes trocam um código de pareamento por um token ([seção 10.2](https://madeforagent.com/pt-br/lmsp/1.0/security.md#pairing)). |
| `openapi` | URL do documento OpenAPI que descreve a interface LMSP. |

Flags de capacidade:

| Flag | Significado |
| --- | --- |
| `streaming` | As respostas podem ser enviadas em streaming como eventos enviados pelo servidor. **DEVE** ser `true` na 1.0. |
| `tasks` | Tarefas assíncronas estão disponíveis. **DEVE** ser `true` na 1.0. |
| `event_resume` | Os fluxos de eventos das tarefas podem ser assinados e retomados (`GET /lmsp/v1/tasks/{task_id}/events`). |
| `conversations` | O serviço armazena respostas, de modo que `store` e `previous_response_id` funcionam e `GET /lmsp/v1/responses/{response_id}` está disponível. |
| `model_management` | Os modelos podem ser carregados e descarregados explicitamente. |

## 3.4 Comportamento do cliente {#client-behavior}

Um cliente:

- **DEVERIA** selecionar a versão mais alta em `versions` que ele também suporte.
- **DEVERIA** selecionar a interface LMSP ou a interface OpenAI em `interfaces`, conforme o que ele consiga falar.
- **DEVE** usar apenas as capacidades que a descrição declara. Uma flag ausente significa `false`.
- **DEVE** ignorar os campos de extensão que não reconhece.
- **DEVERIA** reler a descrição do serviço periodicamente, e também quando uma requisição falhar, em vez de mantê-la em cache para sempre.
- **DEVERIA** lembrar um serviço escolhido pelo `service.id`, e não pelo endereço, porque os endereços podem mudar.