Skills: dê ao agente o contexto certo, não todo o contexto

Este é o quarto artigo da série sobre arquitetura AI friendly. Já falamos sobre contexto, documentação e observabilidade. Agora quero falar sobre uma forma de organizar conhecimento e formas de trabalho para agentes: as skills.

Este artigo não está ligado a um produto ou ferramenta específica. A ideia é discutir o conceito de skill de forma geral, independentemente do modelo, agente ou plataforma usada para colocá-la em prática.

A ideia principal é simples: um agente não precisa receber todo o contexto possível. Ele precisa receber o contexto certo para o problema que está tentando resolver.

O problema de colocar tudo na mesma caixa

Uma reação comum quando começamos a trabalhar com agentes é tentar ensinar tudo de uma vez.

Colocamos documentação da empresa, padrões de código, regras de negócio, instruções de operação, dashboards, runbooks e links para várias ferramentas em um único lugar.

Parece conveniente. Afinal, o agente passa a ter acesso a mais informação.

Mas volume não é o mesmo que conhecimento útil.

Quando tudo é apresentado ao mesmo tempo, o agente precisa descobrir quais informações importam, quais são confiáveis, quais estão relacionadas e quais devem ser ignoradas. Isso aumenta o ruído e torna o raciocínio mais difícil de acompanhar.

Talvez estejamos repetindo com agentes um problema que já tivemos com sistemas: tentando colocar responsabilidades demais dentro da mesma caixa.

Uma skill parte de outra ideia. Cada contexto importante pode ter sua própria especialização.

O que é uma skill?

Uma skill é uma unidade de conhecimento e workflow para um contexto específico.

Ela pode explicar:

• quais conceitos são importantes naquele domínio;

• quais perguntas devem ser feitas primeiro;

• quais fontes de informação podem ser consultadas;

• como interpretar os dados encontrados;

• quais cuidados e limites precisam ser respeitados;

• como apresentar o resultado.

Uma skill de investigação de incidentes, por exemplo, pode orientar o agente a identificar o serviço afetado, reconstruir a linha do tempo, consultar sinais de operação, separar fatos de hipóteses e registrar as evidências.

Ela não precisa armazenar todos os logs, métricas ou documentos. Precisa saber onde encontrar essas informações e como usá-las.

O valor está na combinação entre conhecimento e ação.

Skills são os novos microserviços?

Eu não diria que skills são os novos microserviços. Tecnicamente, são coisas diferentes.

Mas existe uma analogia importante entre os dois.

Aprendemos que sistemas grandes ficam mais fáceis de evoluir quando são separados por responsabilidades e contextos de negócio. Cada contexto passa a ter um vocabulário, regras, dados, contratos e ownership mais claros.

Podemos aplicar um raciocínio parecido ao contexto que entregamos para agentes.

Em vez de criar um agente que conhece superficialmente todos os domínios, podemos criar especializações com fronteiras mais claras:

O agente continua tendo uma visão geral do sistema, mas pode acionar um contexto especializado quando precisa investigar um problema específico.

Contexto especializado não é contexto isolado

Decompor o conhecimento não significa criar caixas que não conversam.

Uma investigação pode começar em observabilidade, passar por delivery e terminar em dados. O agente precisa entender quando cada contexto é relevante e como relacionar as evidências encontradas.

Uma skill fornece profundidade. O agente faz a coordenação.

Uma skill precisa ter fronteiras

Uma skill genérica demais perde valor rapidamente.

“Investigue problemas de produção” é uma instrução ampla. Ela não explica por onde começar, quais fontes consultar ou como decidir que uma hipótese é mais provável do que outra.

Uma skill mais útil define o contexto, o objetivo, as fontes disponíveis e os limites da investigação:

Contexto:
  APIs e serviços do domínio de pedidos.

Objetivo:
  Investigar um aumento de latência e identificar as hipóteses
  mais prováveis com base em evidências.

Fontes e capacidades:
  - consultar logs, métricas e traces do fluxo de pedidos;
  - consultar o catálogo de serviços e suas dependências;
  - verificar mudanças e deploys recentes;
  - consultar a base de dados em modo somente leitura;
  - comparar o comportamento atual com um período anterior.

Fluxo:
  1. Identificar o serviço e o endpoint afetados.
  2. Determinar quando a alteração começou.
  3. Comparar latência, erros e volume de requisições.
  4. Consultar os traces e as dependências do fluxo.
  5. Verificar mudanças recentes.
  6. Consultar dados do pedido para validar a hipótese,
     sem alterar registros.
  7. Registrar fatos, hipóteses e informações faltantes.

Limites:
  - não alterar dados;
  - não executar comandos de escrita;
  - não expor dados sensíveis no resultado;
  - pedir ajuda quando as evidências forem insuficientes.

Esse exemplo é mais útil porque transforma uma intenção em um procedimento que pode ser seguido. Ele também deixa claro que consultar uma base de dados não significa conceder acesso irrestrito. A skill pode usar uma conexão de leitura, com tabelas, campos e limites definidos para aquela investigação.

Na prática, as fontes podem ser disponibilizadas ao agente por capacidades bem delimitadas:

search_logs(service, time_range)
query_metrics(service, metric, time_range)
get_trace(trace_id)
list_recent_changes(service, time_range)
query_readonly_database(query, parameters)

Cada capacidade deve ter sua própria política de acesso. A consulta à base pode aceitar apenas operações de leitura, limitar o tempo da consulta e permitir acesso somente às tabelas necessárias para o domínio.

Isso não significa que toda skill precisa ser rígida. Ela pode permitir adaptação, desde que deixe claras as fronteiras do problema que pretende resolver.

Quanto mais claro o contexto, menor a chance de o agente gastar energia em caminhos irrelevantes.

Uma skill também precisa conhecer seus limites

Um bom especialista não é apenas alguém que sabe o que fazer. É alguém que sabe quando não deve agir sozinho.

Uma skill deveria deixar claro:

• quais ações são somente de leitura;

• quais ações exigem aprovação;

• quais dados podem ser expostos;

• quando uma hipótese ainda não tem evidência suficiente;

• quando o problema precisa ser encaminhado para uma pessoa.

Isso é especialmente importante em skills relacionadas a produção, dados sensíveis ou mudanças que podem afetar outros contextos.

Contexto especializado não deve ser confundido com autonomia irrestrita.

Esses limites não podem existir apenas como instruções para o agente. Precisamos de guardrails determinísticos que validem permissões, argumentos, ambiente e impacto antes de qualquer ação ser executada. Nunca devemos confiar que o agente vai lembrar ou respeitar uma regra de segurança por conta própria.

A skill orienta o comportamento, mas o guardrail aplica a restrição. Vamos aprofundar essa diferença mais adiante, em um artigo dedicado a guardrails, permissões e fitness functions.

O agente faz a ligação entre os contextos

O maior valor não está apenas em criar skills isoladas. Está na capacidade do agente de relacioná-las.

Uma skill de observabilidade pode encontrar uma anomalia. Uma skill de delivery pode identificar uma mudança recente. Uma skill de dados pode apontar uma alteração em um pipeline.

O agente, com uma visão mais ampla, pode conectar essas descobertas e formular uma hipótese:

O aumento de erros começou depois de uma mudança recente. O serviço passou a receber dados com uma estrutura diferente, e a falha está concentrada nos pedidos criados depois da atualização.

Essa conclusão ainda precisa ser verificada, mas já é mais útil do que uma lista de informações desconectadas.

As skills fornecem profundidade. O agente fornece coordenação.

Como começar a criar skills

Você não precisa começar criando uma skill para cada ferramenta ou equipe.

Escolha um problema recorrente e observe como as pessoas mais experientes resolvem esse problema hoje.

Pergunte:

• quais perguntas são feitas primeiro;

• quais fontes são consultadas;

• como os dados são interpretados;

• quais hipóteses costumam ser descartadas;

• quando a investigação precisa ser escalada;

• qual formato de resultado é realmente útil.

Depois, transforme esse conhecimento em uma sequência que possa ser descoberta e reutilizada.

Uma skill não precisa ser perfeita na primeira versão. Ela pode evoluir com os casos reais e incorporar os aprendizados de cada investigação.

Conclusão

Skills são uma forma de organizar contexto especializado para agentes.

Elas evitam que o agente receba um volume enorme de informação sem orientação e ajudam a tornar o raciocínio mais específico, verificável e útil.

A principal mudança não é criar mais uma camada de abstração. É reconhecer que diferentes problemas exigem diferentes conhecimentos, fontes e formas de investigação.

Assim como aprendemos a separar serviços por contexto, podemos separar o conhecimento e as capacidades dos agentes por contexto também.