Integrar uma ferramenta externa a um agente de produto exige definir o que ele pode solicitar, como a solicitação será validada e qual evidência confirma o resultado. A descrição da ferramenta ajuda o agente a escolher um recurso, mas o contrato de execução precisa existir no sistema. Comece por uma ação delimitada, com entradas conhecidas, limites explícitos e um caminho de resposta quando a ferramenta não conseguir concluir.
Escolha uma ação com finalidade clara
Evite começar com acesso amplo a um sistema externo. Descreva a tarefa que o produto precisa realizar e a menor ação necessária para apoiá-la. Consultar um registro, preparar uma proposta e alterar esse registro são capacidades diferentes.
A Anthropic sobre padrões de agentes distingue fluxos predefinidos de agentes que escolhem dinamicamente seu processo e uso de ferramentas. Essa escolha dinâmica não dispensa o desenho da ferramenta. Pelo contrário, a equipe precisa saber qual comportamento está oferecendo para cada chamada.
Registre o objeto da ação, as condições permitidas e o resultado esperado. Se a descrição precisa reunir operações sem relação clara, considere separar capacidades antes de conectá-las ao agente.
Defina entrada, autorização e resultado
Uma proposta de contrato inclui campos obrigatórios, valores aceitos, limites de escopo e respostas possíveis. Dados ausentes ou inválidos devem ter um tratamento definido. O agente não deveria improvisar um valor apenas para conseguir concluir a chamada.
A autorização precisa ser compatível com a pessoa e a tarefa. Descreva quais ações podem ser preparadas, quais exigem confirmação e quais não estão disponíveis. A validação deve acompanhar a execução real; uma instrução escrita no prompt não substitui o controle implementado pelo produto.
Para a saída, diferencie sucesso, falha e estado ainda não confirmado. Uma resposta textual da ferramenta pode descrever o processamento sem demonstrar que o efeito ocorreu. Defina qual identificador, estado ou consulta permitirá conferir a conclusão.
Planeje falhas e novas tentativas
Uma integração precisa lidar com demora, indisponibilidade, resposta parcial e alteração das condições entre consulta e execução. Escolha o comportamento para cada situação relevante, em vez de permitir repetição indefinida.
Antes de repetir uma ação, a equipe deve saber se a tentativa anterior pode ter produzido efeito. Para uma consulta, tentar novamente pode ser simples. Para uma alteração, será necessário considerar duplicidade e estado atual. Engenharia deve definir esse contrato e o produto deve comunicar o estado correspondente ao usuário.
O Google SRE sobre objetivos de serviço descreve metas de confiabilidade que orientam decisões de engenharia e revisão. Na integração, proponha condições operacionais que levem a ações concretas: aguardar, oferecer continuidade manual, restringir uso ou interromper.
Exemplo fictício: criar uma solicitação interna
Imagine um produto em que o agente prepara uma solicitação de acesso a um recurso de trabalho. A ferramenta permite consultar o catálogo e criar uma solicitação, mas não aprovar o acesso. A pessoa revisa o recurso pedido e a justificativa antes do envio.
Se a criação demorar, o produto precisa distinguir uma solicitação ainda em processamento de uma falha confirmada. Se houver dúvida sobre o resultado, uma consulta pelo identificador da operação pode ajudar a verificar o estado antes de nova tentativa, conforme o contrato implementado.
O exemplo não define uma implementação universal. Ele mostra como separar consulta, preparação, confirmação e efeito. A ferramenta deve executar apenas a capacidade autorizada, enquanto a interface permite acompanhar a tarefa sem confundir pedido registrado com acesso aprovado.
Avalie o efeito, além da conversa do agente
A Anthropic sobre avaliações de agentes distingue trajetória e resultado efetivo no ambiente. Use essa diferença para desenhar casos de avaliação da integração. Uma conversa aparentemente correta não comprova que o registro esperado foi criado ou alterado.
Inclua casos com entrada válida, informação ausente, recusa de autorização, indisponibilidade e resultado incerto. Confira também se o produto comunica o estado de forma coerente. Um erro de comunicação pode levar o usuário a tomar outra ação com base em uma conclusão que não ocorreu.
Os critérios precisam refletir a tarefa. Para uma consulta, relevância e completude podem ser centrais. Para uma execução, autorização, objeto correto e confirmação do efeito ganham peso. Não use a mesma avaliação genérica para capacidades diferentes.
Mantenha o contrato visível para operação e evolução
Registre versões e responsáveis. Quando a ferramenta externa mudar um campo, uma resposta ou uma condição de uso, a equipe precisa saber quais tarefas podem ser afetadas e o que deve ser reavaliado.
O registro de uma execução deve ajudar a investigar o problema sem expor conteúdo desnecessário. Defina quais identificadores, versões e estados precisam ser preservados e quem pode acessá-los, conforme as regras da organização.
Antes de conectar outra ferramenta, confirme se a integração atual tem uma finalidade delimitada, entradas verificadas, autorização implementada, estados compreensíveis e evidência de conclusão. A capacidade do agente deve crescer junto da capacidade do produto de verificar o que ele faz.
Se quiser discutir essa decisão no contexto da sua empresa, converse com a dooop.
Leituras para continuar
- Inteligência no produto: como evoluir um software com IA
- Como desenhar aprovação humana dentro de um produto com IA
- Como escolher uma funcionalidade de IA para o produto
Fontes
Para continuar esta leitura
Conversar sobre a aplicação na empresa
Conversa sobre o contexto da empresa de software
Conteúdo de dooop. O cadastro permite relacionar esta pauta à jornada do leitor e acompanhar o interesse pelo tema.