Roteadores de intenção da IA

O roteador responde por um canal no lugar de um agente único. O classificador usa a credencial do próprio roteador. Cada membro é um agente publicado para o mesmo canal. Com sticky, a conversa continua com o agente escolhido até outra intenção chegar com confiança de pelo menos 0,85 (ou min_confidence, se for maior). Na primeira classificação, abaixo de min_confidence, vale o fallback_agent_id.

Configuração

Campo	Tipo e limites	Uso
`name`	1–80	Nome do roteador.
`channel_account_id`	UUID	Canal atendido.
`classifier`	{provider: anthropic\|openai\|google\|openrouter\|deepseek\|xai, model, credential_id}	Modelo que classifica.
`sticky`	boolean, padrão true	Mantém o agente da conversa; troca só com confiança ≥ 0,85 ou min_confidence, o maior.
`min_confidence`	0–1, padrão 0,6	Confiança mínima para aceitar a classificação.
`fallback_agent_id`	UUID de um membro ou null	Agente quando nada se encaixa.
`members`	1–30	agent_id, intent_name (1–80, diferente de none), intent_description (1–2.000), examples (até 20 de 500), position (0–99). Agente e intenção não se repetem.

Rotas

`GET /ai/routers`

Escopo agents:read

Query customer_id. Roteadores não arquivados (até 200), com revision, active e channel_owner (quem responde pelo canal agora: {kind: agent|router, id}).

`POST /ai/routers`

Escopo agents:write

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "config": {
    "name": "Recepção",
    "channel_account_id": "33333333-3333-4333-8333-333333333333",
    "classifier": {
      "provider": "openai",
      "model": "MODELO_VALIDADO_NA_CREDENCIAL",
      "credential_id": "22222222-2222-4222-8222-222222222222"
    },
    "sticky": true,
    "min_confidence": 0.6,
    "fallback_agent_id": "44444444-4444-4444-8444-444444444444",
    "members": [
      {
        "agent_id": "44444444-4444-4444-8444-444444444444",
        "intent_name": "vendas",
        "intent_description": "Preço, disponibilidade e compra de produtos.",
        "examples": [
          "quanto custa a cadeira?"
        ]
      },
      {
        "agent_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
        "intent_name": "suporte",
        "intent_description": "Problemas com pedido já feito, trocas e entregas.",
        "examples": [
          "meu pedido não chegou"
        ],
        "position": 1
      }
    ]
  }
}

Responde 201 com o roteador inativo.

`GET /ai/routers/{id}`

Escopo agents:read

Query customer_id.

`PUT /ai/routers/{id}`

Escopo agents:write

Corpo {customer_id, expected_revision, config}. Substitui a configuração inteira. Trocar o canal de um roteador ativo exige desativá-lo antes (409 pause_before_channel_change).

`DELETE /ai/routers/{id}`

Escopo agents:write

Corpo {customer_id, expected_revision}. Arquiva e retorna {archived: true}.

`POST /ai/routers/{id}/test`

Escopo agents:write

Campo	Tipo e limites	Uso
`text`	1–10.000	Mensagem a classificar.
`request_key`	UUID	Repetir a chave devolve o mesmo teste.
`sticky_agent_id · sticky_intent`	opcionais	Simulam uma conversa já atendida por um membro.

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "text": "Quero trocar um produto com defeito",
  "request_key": "66666666-6666-4666-8666-666666666666"
}

Chama o classificador com a sua chave. Não envia nada e não ativa ninguém. outcome: classified, sticky, reclassified, fallback, session, no_match ou classifier_failed.

{
  "id": "ffffffff-ffff-4fff-8fff-ffffffffffff",
  "router_id": "12121212-1212-4121-8121-121212121212",
  "revision": "2",
  "status": "completed",
  "agent_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "intent_name": "suporte",
  "confidence": 0.91,
  "outcome": "classified",
  "error_code": null,
  "usage": {
    "input_tokens": 412,
    "output_tokens": 18
  },
  "measurement_status": "measured",
  "created_at": "2026-09-25T13:00:00.000Z"
}

Ativação e tomada de canal

O roteador só encaminha para membros ativos. Ative cada membro e depois o roteador.

`POST /ai/routers/{id}/members/{agentId}/activate`

Escopo agents:write

Corpo {customer_id, expected_agent_revision, mode}, com o operation_revision do agente e automatic ou assisted. O agente precisa ter versão publicada para o canal do roteador e credencial válida. Retorna {revision}, a nova revisão de operação do agente. O canal continua com o roteador.

`POST /ai/routers/{id}/operation`

Escopo agents:write

Campo	Tipo e limites	Uso
`expected_revision`	string	Revisão do roteador.
`active`	boolean	Ativa ou desativa.
`replace_current`	boolean, padrão false	Confirma a troca quando um agente já responde pelo canal.
`expected_owner_agent_id`	UUID ou null	Agente que você viu no canal. Obrigatório com replace_current.

Se um agente já responde pelo canal, envie replace_current: true e o ID dele em expected_owner_agent_id. O agente perde o canal e o roteador assume. Se o responsável mudou nesse intervalo, a troca é recusada com 409 revision_conflict: leia channel_owner de novo. Canais sandbox não aceitam roteador.

Status	Código	Quando
404	`not_found`	Roteador, agente ou canal fora do Cliente.
409	`revision_conflict`	Revisão desatualizada ou responsável do canal alterado.
409	`replace_current_required`	Canal com agente vinculado e replace_current ausente.
409	`duplicate_responder`	Outro roteador ativo no canal.
409	`credential_unavailable`	Credencial do classificador inválida ou de outro provedor.
409	`member_unavailable`	Membro sem versão publicada para o canal, arquivado ou com credencial inválida.
409	`pause_before_channel_change`	Troca de canal com o roteador ativo.
422	`invalid`	Configuração fora do schema.

A elegibilidade do canal continua valendo com roteador. Veja Acesso e elegibilidade.

Visão geral do Agente de IA · Próxima: Follow-ups e retornos