OkMigo

O agente de domínio do seu serviço

Sem agente, o amigo do OkMigo escolhe sozinho entre as operações da sua conversa e monta os parâmetros de cada uma. Com o agente, ele passa o pedido em linguagem natural para quem entende do assunto: um agente que conhece o seu vocabulário, as suas ambiguidades e qual ferramenta resolve o quê. O seu servidor MCP continua sendo a fronteira de dado e de ação. O agente fica em cima do MCP, nunca no lugar dele.

Declare o agente no manifesto

Um bloco a mais no mesmo Aplicativo. Sem ele, nada muda.

from okmigo_cartao import AgenteDeDominio, Exemplo, Orcamento

APLICATIVO = Aplicativo(
    ...,
    conversa=("buscar_pedidos", "status_do_pedido", "cancelar_pedido"),
    agente=AgenteDeDominio(
        competencias=("status de um pedido", "pedidos atrasados"),
        ferramentas=("buscar_pedidos", "status_do_pedido"),
        instrucoes="Pedido citado pelo nome do cliente e ambíguo vira pergunta "
                   "com as opções. Prazo é sempre em dias úteis.",
        exemplos=(Exemplo("cadê o pedido da Ana?", "respondido"),
                  Exemplo("cancela o pedido 123", "acao_proposta")),
        orcamento=Orcamento(chamadas=3, tokens=12_000, segundos=20),
    ),
)

competenciasSão o que o amigo lê para decidir se pergunta ao seu serviço: frases curtas, até seis.
ferramentasSão só de leitura (anotadas como readOnlyHint no seu servidor MCP) e todas na conversa. O registro recusa ferramenta que escreve.
instrucoesVocabulário e uso das ferramentas, até 4.000 caracteres. ⛔ Não é lugar de regra de negócio: a regra mora na operação MCP, onde é testável.
exemplosUm pedido e a forma de resposta esperada. Viram a bateria de avaliação que roda antes de o agente ser ligado para as pessoas.
orcamentoO teto de um pedido: até 4 chamadas de ferramenta, 20 mil tokens e 30 segundos.

O agente é executado pelo OkMigo (modo declarado): você não hospeda modelo nenhum, e a mensagem da pessoa não sai do OkMigo. O seu serviço recebe só os parâmetros das ferramentas, como sempre. Não há modo em que o agente rode no seu servidor: o texto da pessoa sairia do OkMigo, e essa é uma fronteira que o OkMigo não abre.

As quatro respostas

O agente termina sempre numa destas formas. Fora delas, não há resposta.

forma	quando	o que o OkMigo faz
`respondido`	há dado para responder	O amigo repassa com o tom dele, e todo número que ele escrever tem de estar na resposta. Se não estiver, a pessoa lê o texto do seu serviço, sem retoque. A data-base é obrigatória.
`precisa_esclarecer`	ambiguidade: dois papéis, dois clientes com o mesmo nome	A pergunta vai à pessoa como veio, e o OkMigo guarda o estado. Quando ela escolhe uma das opções, o próprio OkMigo pergunta de novo ao seu agente, sem o modelo remontar parâmetro nenhum.
`acao_proposta`	a pessoa quer que algo aconteça	Nada é executado. A proposta vira uma pendência de confirmação, e a escrita só acontece num turno seguinte, com o «sim» da pessoa.
`indisponivel`	sem dado, fonte fora do ar, fora do domínio	A pessoa lê a frase segura. O amigo não responde o assunto de cabeça.

Para validar do seu lado, validar_resposta() do okmigo-cartao aplica as mesmas regras que o OkMigo aplica.

O que o OkMigo garante, e você não precisa fazer

O tenant e a credencial vêm do servidor, nunca do modelo. Parâmetro que a ferramenta não declara é recusado antes de chegar a você.
Ferramenta fora da lista do agente não executa, nem se o modelo adivinhar o nome.
Número da resposta que não veio de uma ferramenta derruba a resposta.
Uma pergunta ao seu serviço por turno. Não existe agente chamando agente.
O rollout é gradual e por pessoa, e desligar volta a conversa para as operações da conversa na mensagem seguinte.

Checklist antes de registrar

Toda ferramenta do agente é de leitura e está na conversa
As instruções descrevem vocabulário e uso, não regras
Há exemplo para cada forma que o seu domínio produz
Os exemplos não dependem de um dado específico do seu banco
Escrita natural do domínio aparece como acao_proposta, com os campos que a operação exige
A versão do manifesto subiu (o contrato congela no registro)