Made for Agent
Idioma: Português (Brasil)

Descoberta de serviços

3.1 Métodos de descoberta

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). Um endereço informado manualmente pelo usuário sempre tem precedência sobre os descobertos.

3.2 Anúncio na LAN

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, RFC 6762).

Um exemplo de anúncio:

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).
  • 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

GET /.well-known/lmsp.json

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

{
  "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).
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

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.