orquestrador/docs/architecture/admin-bot-governed-configuration-scope.md

Configuracoes Do Bot Governadas Pelo Admin

Objetivo

Definir exatamente quais configuracoes do bot de atendimento entram sob governanca do orquestrador-admin.

Esta etapa detalha, em nivel de campo, a parte do runtime do bot que pode ser consultada por colaborador e alterada por diretor.

Decisao

O admin governa apenas configuracoes funcionais do bot de atendimento.

Isso inclui:

• escolha do modelo homologado usado no atendimento
• politicas de resposta do bot
• politicas de uso de tools
• politicas de fallback e handoff humano
• politicas operacionais por canal

Essa fronteira fica formalizada em shared/contracts/bot_governed_configuration.py.

Configuracoes governadas

1. Selecao de modelo do bot

Campos governados:

• provider
• model_name

Esses campos definem qual modelo homologado responde ao cliente final.

2. Geracao de resposta

Campos governados:

• temperature
• max_output_tokens
• prompt_profile_ref

Esses campos controlam o perfil funcional da resposta, sem expor o painel a segredos ou internals de infraestrutura.

3. Uso de tools

Campos governados:

• tool_policy_ref
• max_tool_calls_per_turn
• confirmation_policy

Esses campos definem como o bot pode usar tools e quando precisa de confirmacao antes de acao critica.

4. Fallback e handoff

Campos governados:

• fallback_mode
• handoff_enabled
• handoff_intents

Esses campos governam quando o fluxo segue fallback controlado e quando encaminha para atendimento humano.

5. Operacao por canal

Campos governados:

• enabled
• maintenance_mode
• default_route
• operation_window_ref

Esses campos permitem controlar disponibilidade e comportamento funcional por canal homologado.

O que nao entra como configuracao do bot

As seguintes superficies ficam fora desta governanca:

• configuracao de modelo para geracao de tools
• credenciais de provedor e segredos
• conteudo bruto de prompt sensivel
• variaveis de ambiente e infraestrutura
• implementacao interna das tools
• alteracao direta em tabelas operacionais do product

Regras obrigatorias

1. Leitura por colaborador, alteracao por diretor

• colaborador consulta via view_system
• diretor consulta e altera via manage_settings

2. Sem escrita direta no runtime do produto

O painel registra estado desejado e governado. O product consome apenas configuracao publicada, versionada e auditavel.

3. Separacao do runtime de geracao

O runtime usado para gerar tools continua em trilha propria. Ele nao deve ser tratado como configuracao do bot de atendimento.

Consequencias positivas

• deixa a tela de configuracao do bot mais clara e segura
• evita que a UI misture atendimento com geracao de tools
• preserva a governanca de publicacao entre admin e product
• prepara a proxima etapa de rotas administrativas para configuracao funcional do sistema