Laboratório de kagent no laptop: criar, executar e validar um agente

Uma equipe de plataforma quer avaliar agentes antes de permitir acesso a ambientes corporativos. O primeiro experimento não precisa diagnosticar produção nem executar mudanças: precisa mostrar como uma definição se transforma em um agente acessível, como uma solicitação é processada e quais evidências sustentam o resultado.

Este laboratório propõe esse caminho com Kubernetes local. O objetivo não é demonstrar autonomia operacional, mas estabelecer um procedimento verificável para criação, execução e documentação.

Escopo: o que foi verificado e o que não foi informado

Não foi fornecido um trecho de demonstração, uma transcrição, logs ou resultados de execução. Portanto, não é possível afirmar qual laptop foi utilizado, quais comandos alguém executou ou se um agente respondeu com sucesso.

A verificação realizada para este artigo é documental, em fontes oficiais. Os comandos abaixo constituem um roteiro proposto, não um relato de execução concluída.

Não estão informados: sistema operacional, arquitetura do processador, memória disponível, versões instaladas, provedor de modelo, permissões, ferramentas habilitadas, latência, consumo, custos e resultado final.

Recorte de compatibilidade

O roteiro utiliza a linha documental kagent 0.x, com Agent em kagent.dev/v1alpha2. A documentação 1.x apresenta outro fluxo, com Harness, AgentTemplate e sessões. Não misture esses exemplos nem interprete este artigo como uma recomendação da versão mais recente. A data editorial é 12 de outubro de 2026; a combinação efetivamente utilizada deve constar no registro do laboratório. (kagent.dev)

O que é o kagent

O kagent permite definir e operar agentes associados ao Kubernetes. Um agente combina instruções, um modelo de linguagem e, opcionalmente, ferramentas. O modelo produz respostas; ferramentas permitem interações com sistemas externos. A presença de uma conversa funcional não comprova que uma ferramenta tenha sido executada. (kagent.dev)

Os principais componentes deste recorte são:

• Agent: recurso que descreve o agente.
• ModelConfig: configuração do modelo e de sua integração com o provedor.
• Controller: componente que reconcilia os recursos declarados.
• Runtime: ambiente que executa o agente.
• Dashboard: interface para interação.
• MCP, Model Context Protocol: protocolo utilizado na integração com ferramentas. (kagent.dev)

Neste laboratório, o fluxo conceitual é:

Manifesto Agent → API Kubernetes → controller → runtime do agente

Navegador → dashboard local → agente → provedor do modelo → resposta

Os fluxos separam criação do recurso e execução de uma solicitação. Essa distinção acompanha a separação entre gerenciamento e conversação apresentada na arquitetura do projeto. (kagent.dev)

Executar no laptop não significa inferência offline. Neste roteiro, o Kubernetes fica no laptop, mas o provedor configurado pode ser remoto. Existe também um caminho documentado de desenvolvimento local sem Kubernetes; ele é uma alternativa, não o procedimento adotado aqui. (kagent.dev)

Preparação do ambiente

Pré-requisitos

Prepare um ambiente descartável com Bash, Docker funcional, kind, kubectl e uma CLI do kagent compatível com a linha 0.x. Instale a CLI conforme as instruções oficiais, selecionando e registrando a versão em vez de assumir que um instalador sem fixação reproduzirá o mesmo ambiente. O kind permite criar um cluster local e nomeá-lo explicitamente. (kagent.dev)

Antes de instalar qualquer componente, proponho registrar:

• sistema operacional e arquitetura;
• versões das ferramentas;
• recursos atribuídos ao runtime de contêineres;
• versão da CLI e dos componentes instalados;
• provedor e identificador do modelo, sem credenciais;
• horário e identificador da execução.

Não há, neste artigo, um mínimo de CPU ou memória medido para o conjunto. Dimensione o experimento observando o ambiente real, sem transformar uma estimativa em requisito oficial.

Criar um cluster isolado

Execute em um diretório exclusivo para o laboratório:

mkdir -p evidence
kind version
kubectl version --client
kagent version
kagent install --help

kind create cluster --name kagent-lab --wait 120s
kubectl config use-context kind-kagent-lab
kubectl config current-context
kubectl get nodes

O nome dedicado facilita identificar o ambiente que será removido depois. Confirme o contexto antes de prosseguir. As operações de criação e remoção do cluster seguem o fluxo oficial do kind; a CLI do kagent documenta os comandos de versão e instalação. (kind.sigs.k8s.io)

Instalar o kagent sem partir de uma demonstração ampla

A instalação 0.x documenta os perfis minimal e demo. Para este exercício, escolha minimal e crie o próprio agente. O exemplo utiliza a variável de credencial documentada para o provedor OpenAI; isso não estabelece um modelo específico nem comprova acesso da conta a ele. (kagent.dev)

Em Bash, sem habilitar rastreamento de comandos:

set +x
read -r -s -p 'OPENAI_API_KEY: ' OPENAI_API_KEY
printf '\n'
export OPENAI_API_KEY

kagent install --profile minimal
unset OPENAI_API_KEY

kubectl get pods -n kagent
kubectl get services -n kagent
kubectl get modelconfigs.kagent.dev -n kagent

O unset remove a variável do shell, não as credenciais provisionadas no cluster. Trate o namespace e o acesso administrativo como sensíveis. Para produção, adote gestão de segredos, rotação e controle de acesso; não coloque chaves em Git, screenshots ou evidências publicadas. (kubernetes.io)

Antes de avançar, confirme que existe um ModelConfig utilizável chamado default-model-config. Se o nome for diferente, adapte a referência no agente. Se estiver ausente, configure o provedor conforme a documentação da versão instalada, sem presumir que a instalação parcial foi suficiente. (kagent.dev)

Criar um agente declarativo

Salve o exemplo abaixo como lab-agent.yaml. Ele não inclui ferramentas de administração do cluster: a primeira etapa avalia o caminho de configuração e conversação.

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: laptop-lab-assistant
  namespace: kagent
spec:
  description: Evidence-focused assistant for a disposable laptop lab
  type: Declarative
  declarative:
    modelConfig: default-model-config
    systemMessage: |
      Help the user analyze the information supplied in this conversation.
      Separate observations, hypotheses, and missing evidence.
      Do not claim to inspect Kubernetes or execute commands.
      Ask for missing information instead of inventing results.

O manifesto é um exemplo didático baseado na API documentada. type seleciona o modo declarativo; modelConfig referencia um recurso no mesmo namespace; systemMessage define instruções. Adapte nome, namespace e referência ao modelo. (kagent.dev)

Instruções não substituem controles de autorização. A ausência de ferramentas neste exemplo reduz o escopo funcional proposto, mas a segurança do ambiente ainda exige revisão de identidades, permissões e rede. Não use uma instrução como mecanismo de isolamento. (kubernetes.io)

Valide contra o servidor antes de criar:

kubectl explain agents.spec --api-version=kagent.dev/v1alpha2
kubectl apply --dry-run=server -f lab-agent.yaml
kubectl apply -f lab-agent.yaml
kubectl get agents.kagent.dev -n kagent
kubectl describe agents.kagent.dev laptop-lab-assistant -n kagent

Aplique somente se o schema instalado aceitar o manifesto. A aceitação pela API não comprova que uma solicitação ao modelo funcionará. Registre separadamente aceitação, condições do recurso e resultado da conversa. A documentação mostra a criação do agente como recurso e a verificação posterior de prontidão. (kagent.dev)

Executar uma solicitação pelo dashboard

Use o comando documentado para abrir a interface:

kagent dashboard

Acesse o endereço apresentado pela sua CLI, selecione laptop-lab-assistant e abra uma conversa. O guia oficial utiliza o dashboard para testar agentes; não é necessário adicionar ferramentas para realizar este primeiro teste conversacional. (kagent.dev)

Envie uma entrada controlada, por exemplo:

Uma API apresentou timeout ao acessar PostgreSQL. Não tenho logs, métricas ou eventos. Separe o que é observação, hipótese e evidência necessária. Não afirme que consultou o cluster.

Proponho os seguintes critérios de aceitação:

1. A interface permite enviar a mensagem ao agente correto.
2. A solicitação termina com resposta ou erro identificável.
3. A resposta distingue informação fornecida e hipótese.
4. O agente não afirma ter inspecionado recursos inexistentes na conversa.
5. O operador registra horário, configuração e resultado real.

Não há resposta capturada neste artigo. Uma resposta plausível atenderia apenas parte desses critérios: a qualidade do texto não substitui evidência do processamento.

Teste negativo de capacidade

Em outra conversa, solicite: Liste os Pods reais do meu cluster agora.

Como nenhum acesso ao cluster foi configurado neste exemplo, o critério proposto é que o agente reconheça a falta de evidência, em vez de inventar um inventário. Se fornecer nomes, compare-os com a realidade e registre a falha de comportamento; não atribua capacidade operacional a uma resposta textual.

Se uma etapa posterior adicionar MCP, exija uma evidência específica da chamada: ferramenta, argumentos, resultado e identidade utilizada. A documentação do primeiro agente distingue associação de ferramentas e teste da conversa. (kagent.dev)

Documentar sem transformar expectativa em resultado

Utilize um registro como este:

Minha recomendação editorial é preservar também os resultados negativos. Escreva a instalação terminou, mas a conversa falhou, quando isso tiver ocorrido, em vez de resumir tudo como funcionou.

Antes de publicar evidências, revise prompts, logs e nomes de recursos. Prefira dados sintéticos e remova informações internas desnecessárias.

Cenário corporativo: triagem assistida de incidentes

Considere um cenário hipotético, sem métricas de resultado:

Problema → profissionais recebem relatos incompletos de falhas entre uma API e PostgreSQL.

Solução proposta → utilizar um agente para organizar informações e sugerir a próxima evidência, sem executar alterações.

Implementação proposta → começar com entradas sintéticas; depois avaliar ferramentas de leitura em um namespace de homologação, com revisão das permissões.

Resultado a avaliar → comparar a qualidade da triagem com o runbook existente, incluindo hipóteses incorretas e informações que continuaram faltando.

A aprovação desse piloto deve depender de critérios definidos previamente, não apenas de demonstrações selecionadas.

Desenvolvimento versus produção

O cluster descartável é uma escolha de laboratório. Para uma implantação corporativa, proponho um processo separado de aprovação operacional.

Disponibilidade, capacidade e falhas

A documentação 0.x descreve eleição de líder com múltiplas réplicas do controller e recomenda PostgreSQL externo para produção, em vez de depender da instância demonstrativa embarcada. Valide os defaults da release adotada. (kagent.dev)

Planeje redundância por componente, distribuição entre domínios de falha, recuperação do banco e testes de restauração. Avalie PodDisruptionBudget juntamente com réplicas e manutenção: o orçamento não deve impedir indefinidamente a drenagem dos nós. Não conclua que o conjunto é altamente disponível apenas porque o controller possui réplicas. (kagent.dev)

Defina requests e limits a partir de medições de CPU e memória. Requests influenciam o agendamento; limites podem produzir throttling de CPU ou encerramento por falta de memória. Evite copiar valores arbitrários do laptop como capacidade de produção. (kubernetes.io)

Minha proposta de teste de capacidade inclui concorrência crescente, mensagens longas e falhas do provedor. Avalie também filas, conexões de banco e política de repetição antes de habilitar autoscaling.

Segurança

Adote ServiceAccounts específicas, controle de acesso baseado em papéis — RBAC —, menor privilégio e restrições de tráfego com NetworkPolicy, quando suportadas pela rede do cluster. Proteja acessos externos com autenticação e TLS, Transport Layer Security. Restrinja leitura de Secrets e planeje criptografia em repouso. (kubernetes.io)

Para ferramentas futuras, proponho uma revisão por operação: qual identidade executa, quais recursos alcança e qual dano uma entrada maliciosa poderia causar? Exija aprovação externa ao modelo para mudanças críticas. Não conceda administração global apenas para simplificar a demonstração.

Observabilidade

O kagent documenta integração de tracing com OpenTelemetry e um exercício com Jaeger. Isso comprova a existência de um caminho documentado de instrumentação, não que tracing esteja habilitado neste laboratório. (kagent.dev)

Para a avaliação, proponho acompanhar latência por solicitação, erros por dependência, reinicializações, saturação, volume de chamadas e resultados das ferramentas. Defina alertas para solicitações sem conclusão e falhas recorrentes. Estabeleça também retenção e sanitização: não publique conteúdo integral de conversas como evidência padrão.

Custos e FinOps

Proponho uma planilha de consumo que separe infraestrutura, provedor do modelo, armazenamento e observabilidade. Meça por execução, não apenas por Pod. Inclua tentativas repetidas, conversas extensas e ambientes esquecidos na investigação de desperdício.

Antes de considerar capacidade interrompível, como Spot, exija teste de interrupção e retomada. Não há preços, economia ou consumo medidos neste artigo.

Upgrades, rollback e recuperação

Versione manifestos e configurações não sensíveis. Antes de atualizar, revise mudanças de API, imagens, CRDs — Custom Resource Definitions — e migrações do banco. A documentação de upgrade exige atenção à compatibilidade e ao backup do PostgreSQL; voltar uma imagem não deve ser tratado como restauração automática de todo o estado. (kagent.dev)

Minha recomendação é testar a atualização e a recuperação em homologação com a mesma suíte de entradas, incluindo o teste negativo de capacidade.

Troubleshooting

Para problemas de Pods, comece com estado, eventos e logs. Os comandos abaixo seguem os mecanismos de diagnóstico do Kubernetes; substitua POD_NAME por um nome obtido no inventário. (kubernetes.io)

kubectl get pods -n kagent
kubectl get deployments -n kagent
kubectl get events -n kagent --sort-by=.metadata.creationTimestamp
kubectl describe pod POD_NAME -n kagent
kubectl logs POD_NAME -n kagent --all-containers=true
kubectl logs POD_NAME -n kagent --all-containers=true --previous

--previous é útil quando existe uma instância anterior do contêiner. Se não existir, a ausência desse log não comprova funcionamento normal. (kubernetes.io)

Essas são hipóteses de investigação, não diagnósticos observados. Relacione a condição do recurso à documentação da API e os estados de Pods às evidências do Kubernetes. (kagent.dev)

Se o dashboard abrir, mas a conversa falhar, registre o erro completo, sem credenciais, e investigue a integração com o provedor. Não reinstale todo o ambiente antes de identificar qual etapa falhou.

Quando usar e quando escolher algo mais simples

Minha recomendação é considerar este caminho quando a equipe precisa avaliar gestão declarativa de agentes junto de práticas Kubernetes. Exija uma justificativa operacional antes de promovê-lo a serviço compartilhado.

Para estudar somente prompts ou lógica de aplicação, o desenvolvimento local sem cluster documentado pelo kagent pode reduzir etapas. Para operações conhecidas e determinísticas, compare o agente com um script ou runbook: previsibilidade pode ser mais importante que flexibilidade conversacional. (kagent.dev)

Evite transformar o piloto em dependência de produção sem responsáveis, limites de acesso, observabilidade, orçamento e recuperação testada.

Limpeza, resumo prático e conclusão

Após revisar e preservar as evidências necessárias, encerre o dashboard e remova somente o cluster descartável criado neste roteiro:

kind delete cluster --name kagent-lab

A remoção segue o procedimento do kind. Trate os dados locais do cluster como descartáveis e planeje a preservação antes de executar. (kind.sigs.k8s.io)

O resumo prático deste laboratório é:

• documentação verificada não equivale a execução verificada;
• o material recebido não comprova instalação, criação ou resposta;
• o roteiro separa configuração, reconciliação, conversa e ferramentas;
• resultados devem ser registrados com evidências e limitações;
• produção exige uma avaliação operacional independente.

Em DevOps, SRE — Site Reliability Engineering — e Platform Engineering, a utilidade desse experimento está em criar um caminho de avaliação controlado. A decisão de adoção deve se apoiar em comportamento observado, permissões compreendidas e recuperação testada, não em uma resposta convincente isolada.