Como criar seu próprio agent harness?

Autoria: LowSpecLabs · Assistir no YouTube

Vídeo de autoria do canal indicado, não da IANIA; todos os direitos pertencem ao criador. Transcrição, resumo e tradução gerados automaticamente; o conteúdo no idioma original é preservado na versão em idioma original.

Idioma original: inglês

Vídeo original: How to build your own agent harness?! · Canal: LowSpecLabs · 11:50 · Assistir no YouTube

Tópicos: Agentes de IA, Engenharia de software com IA, Ferramentas de desenvolvimento com IA, Modelos locais e open source

Resumo

O vídeo explica como estruturar um agent harness modular, mantendo o loop principal separado de ferramentas, logs, configurações e outros componentes. O apresentador recomenda começar com um MVP e evitar investir tempo demais em refinamentos de retorno pequeno. Em seguida, demonstra como usar uma ferramenta de IA para pesquisar a documentação de uma API, planejar e implementar um harness em Python e testá-lo. Ao encontrar um erro de conexão, ele mostra como pedir à IA que melhore a mensagem de erro e oriente a configuração do ambiente.

Pontos-chave

Mantenha o loop principal do agente independente do tratamento de chamadas de ferramentas, logs, base de conhecimento e aprovações do usuário.
Separe as funções em arquivos e módulos para facilitar alterações e evitar um script monolítico difícil de editar e depurar.
Comece com um MVP e avalie se o ganho esperado justifica o tempo dedicado a refinar o harness.
Pesquise a documentação da API e salve-a localmente antes de pedir à IA que projete um harness em torno dela.
Peça à IA que faça perguntas durante o planejamento e, quando útil, durante a implementação, para identificar escolhas problemáticas antes de concluir o código.
Use confirmações para operações destrutivas, como sobrescrever ou excluir páginas.
Teste o projeto durante a implementação com o backend e o modelo locais disponíveis.
Use os erros encontrados em testes manuais para orientar melhorias de diagnóstico e instruções de configuração.

Capítulos

Início	Capítulo	Resumo
00:00	Estrutura e escopo do agent harness	O apresentador descreve o loop de agente e recomenda manter suas responsabilidades separadas, além de limitar o esforço inicial a um MVP.
03:06	Organização modular e construção com IA	O vídeo contrasta scripts monolíticos com módulos independentes e apresenta o uso de IA para criar o harness.
05:09	Preparação da documentação e planejamento	A demonstração pesquisa a API do BookStack, salva a documentação e define a arquitetura e as proteções do harness.
08:47	Implementação, testes e correção de erros	O apresentador inicia a implementação em uma sessão separada, testa o projeto e pede melhorias para lidar com falhas de conexão.

Citações

Minha recomendação é não passar mais do que algumas horas nisso, especialmente se for para chamar apenas uma API. — 01:03

O que você não quer fazer é criar um único script gigante de Python ou Bash para colocar toda a lógica do agente. — 03:06

Você quer obter a especificação da API e então pedir ao seu LLM mais inteligente que crie um agent harness em torno dela. — 07:17

Queremos confirmações para certas chamadas destrutivas de ferramentas. — 08:17

O plano não incluía essa opção, então vamos pedir que ela seja adicionada. — 10:50

Conceitos e entidades

agent harness (conceito): Estrutura que envolve um modelo com um loop de agente, ferramentas e componentes de suporte para executar tarefas.
BookStack (ferramenta): Wiki usada no exemplo, cuja API serve de base para construir e testar o harness.
Google Antigravity (ferramenta): Ferramenta de IA usada na demonstração para pesquisar a API, planejar e implementar o harness.
Gemini (modelo): Família de modelos mencionada pelo apresentador como opção rápida para realizar tarefas de desenvolvimento.
LM Studio (ferramenta): Aplicativo citado como backend local para testar o projeto durante a implementação.
llama.cpp (ferramenta): Mecanismo de inference mencionado como alternativa para executar modelos durante os testes.
Python (conceito): Linguagem escolhida para implementar o harness demonstrado.
MCP (conceito): Componente citado como algo que pode ser integrado ao harness, separado do loop principal do agente.

Tradução completa (pt-BR)

00:00 Como criar seu próprio agent harness. Bem-vindos de volta, pessoal. Este é mais um episódio de LowSpec Labs. No nosso último vídeo, falamos sobre a ideia de envolver sua API, ou qualquer ferramenta ou ambiente que você queira, em torno do modelo e fornecer ao modelo um conjunto limitado de ferramentas para permitir que a IA local ajude a IA local a ter um desempenho melhor. Hoje, a maioria dos LLMs modernos consegue criar para você um harness em Python ou, sabe, na linguagem que preferir, em

00:33 algumas horas, certo? Ele vai criar um MVP funcional e razoável bem rápido. A partir daí, o tempo que você vai investir depende de quão bem quer que o harness funcione. Se algumas horas de trabalho fizerem o modelo ter um desempenho significativamente melhor, na minha opinião, vale a pena, certo? Mais 10 a 12 horas de trabalho para talvez ganhar outros 5% a 10% de desempenho não vale a pena para mim. Vou simplesmente pagar pelo Deep Seek. Então, você precisa decidir quanto tempo quer gastar fazendo fine-tuning do seu harness. Minha

01:03 recomendação é não gastar mais do que algumas horas com isso, especialmente se ele só tiver que chamar uma API. Este vídeo serve mais ou menos para ensinar as armadilhas e os erros comuns que encontrei ao criar vários agent harnesses. Acontece que existe um jeito certo e um jeito errado de criar o harness. Quem diria? Sou especialista? Não. Mas posso dizer o que não fazer com base nos meus próprios erros. À minha direita está o que você consideraria o seu

01:33 loop padrão de um agent harness. Certo? Você tem o loop do agent. Dentro desse loop, fica o harness, ou o agent; e o agent é usado para planejar e decompor tarefas. Depois, ele passa a chamar ferramentas e lê a saída da ferramenta para então criar um novo plano ou seguir adiante. Em geral, você quer que esse loop seja independente, certo? Quer que o loop principal seja separado do tratamento das chamadas de ferramentas, do registro em logs,

02:04 da integração, de qualquer base de conhecimento ou MCP que você configure, e até mesmo das aprovações do usuário. Você quer que o loop principal do agent fique isolado. Se olharmos a pasta bookstack do nosso último vídeo, confira esse vídeo para ficar por dentro. Dentro de script/bookstack, temos o chat, que é o nosso loop principal do agent. Temos docs porque eu passo documentos para dentro e para fora do BookStack. É lá que os armazeno. Temos logs, para poder

02:35 registrar chamadas de ferramentas, chat, histórico e erros do harness. Temos um arquivo requirements.txt para configurar nosso ambiente Python. Temos um setup.sh e subscripts. A pasta subscripts contém os outros módulos desse harness, incluindo chamadas de ferramentas, solicitações do usuário, configuração, processamento, a base de conhecimento e o registro em logs e a telemetria. Certo? Então, basicamente, você quer estruturar suas pastas da forma mais simples possível. O que

03:06 você não quer fazer — e digo isso com base nos meus próprios fracassos — é criar um único script gigantesco em Python ou Bash e tentar colocar toda a lógica do agent nele. Isso vai dificultar muito para qualquer IA que você estiver usando analisar, editar e depurar o script. Seguindo a estrutura que mostrei, por exemplo, vamos entrar nessa pasta de subscripts. Se executarmos ls/subscripts, você verá que temos um rastreador de metas para acompanhar nossa meta, gerenciador de arquivos, criar

03:37 Docker, pesquisar, criar, scratch, enviar. Esses são os vários subscripts que acrescentam funcionalidades e recursos ao harness. Note que eles ficam separados, pelo menos logicamente, dentro dessa estrutura de pastas. E, no nível superior, temos o chat.py principal. O resultado final é um script que contém o núcleo do loop do agent, enquanto todo o resto, como chamadas de ferramentas, a base de conhecimento, como ele processa

04:08 suas metas, sua configuração e suas definições, o registro em logs e a telemetria, fica em scripts separados. Assim, você pode modificá-los e ajustá-los de forma independente sem precisar quebrar todo o loop. Se colocar tudo em um único script gigantesco, ainda dá para fazer isso. Só vai ser muito difícil e, mais cedo ou mais tarde, você vai chegar a um ponto em que vai querer dividir esse script monolítico. Então, como criar de fato seu agent harness? Bem, você vai precisar de IA ou vai precisar saber programar. Eu vou

04:38 usar IA porque ela programa muito melhor e mais rápido do que eu. A parte impressionante disso é que você nem precisa da IA mais inteligente para criar o agent harness. Tenho quase certeza de que a documentação já está disponível há tempo suficiente para que a maioria das IAs treinadas com dados gerais de busca na própria internet consiga fazer isso sem problema. Claude, GPT, Deepseek, Kimi, todas elas conseguem criar

05:09 seu agent harness em cerca de 30 minutos a uma hora. Pelo menos seu MVP, sabe, seu produto básico funcional. Depois disso, talvez você queira passar algumas horas ajustando e refinando, ou talvez alguns dias, se acabar se empolgando. Para este vídeo, vamos usar AGI, já que o Google praticamente oferece Gemini e inferência de graça hoje em dia. Então, vamos limpar a tela. Como você pode ver, estamos com o anti-gravity aberto aqui, na versão CLI, que, sinceramente, é a única versão que eu recomendaria usar. Agora vamos

05:40 criar uma nova pasta e percorrer as etapas para recriar o harness do BookStack que demonstrei no último vídeo. Primeiro, confira se você tem a documentação. Depois, vamos entrar na nossa pasta. Vamos executar cd /testbookstack. Em seguida, vamos iniciar nosso agent harness, que, no nosso caso, será o agy, ou o anti-gravity do Google. Eu sei, estou usando o anti-gravity. É uma loucura. Tudo bem, ele funciona muito bem. Eu preferiria

06:11 os modelos Opus ou ChatGPT, mas estou sem tokens. Então, o AGI e o Google oferecem inference praticamente de graça. Vamos pedir que ele pesquise na web informações sobre a API do BookStack. Depois, vamos pedir que salve o que encontrou em um arquivo Markdown. Essa é a primeira etapa. Antes mesmo de pedir que escreva o harness, vamos obter informações sobre a API e salvá-las

06:45 localmente. E isso levou cerca de 60 segundos. Uma das coisas de que gosto no Gemini 3.7 e no 3.8 Flash é que são modelos rápidos. Ele fez a pesquisa na web e criou o arquivo api.md. Vamos voltar e executar cd2 /testbookstack ls. E temos mesmo o api.md. Se executarmos cat api.md rapidinho, você pode ver aqui todo o conteúdo da API do BookStack, ou da

07:17 API do BookStack, certo? Ela nos dá muitas informações úteis. Isso vai ser necessário porque agora vamos usar essa especificação da API para propor um plano. Você não precisa usar exatamente este prompt, mas, em linhas gerais, a ideia é obter a especificação da API e pedir ao seu LLM mais inteligente para criar um agent harness que a envolva. Outra coisa que gosto de fazer quando peço à IA para criar algo é parar e pedir que ela me faça perguntas

07:47 pelo menos durante a fase de planejamento e, muitas vezes, também durante a fase de implementação. Isso dá a você a oportunidade de perceber escolhas estranhas de design ou de implementação antes de o código ficar pronto. Vamos apenas percorrer as opções. Para isso, Python basta. Não precisamos de TypeScript nem de Node. Que interface o agent harness deve oferecer? Para as nossas interfaces, vamos escolher uma CLI/REPL interativa.

08:17 Como as ferramentas devem ser abstraídas para o uso pelo LLM? Vamos seguir a recomendação. E quais recursos de confiabilidade e segurança do harness devemos incluir? Vamos usar proteções de confirmação de diff seguro para ações de sobrescrita e exclusão de páginas. Certo? Então queremos confirmações para certas chamadas destrutivas de ferramentas. Pronto. O legal do anti-gravity do Google é que ele é muito rápido. Olha só. Certo, o plano já está pronto. BookStack

08:47 arquitetura e plano de implementação do agent harness. >> Agora ele está perguntando se queremos implementar esse plano. Ainda não vamos implementá-lo. Salve-o como plan.md na pasta de trabalho. Em vez disso, vamos salvá-lo como plan.md. Inicie uma nova sessão e então peça ao modelo para começar com uma context window limpa e implementar nosso plano. Também poderíamos fazer isso simplesmente dizendo ao Anti-gravity para iniciar um subagent, mas gosto de manter as coisas separadas em conversas diferentes, porque isso ajuda

09:18 a manter tudo um pouco mais organizado. Iniciei uma nova sessão. Vamos pedir que ele leia o plan.md e o implemente. Use este backend do LM Studio e este modelo para testar durante a implementação. Então, se puder, deixe o LM Studio pronto e aguardando em segundo plano, ou o llama CPP, ou o Onslaught, ou qualquer mecanismo de inference que você esteja usando. E também vamos fornecer o

09:48 modelo e então é só apertar Enter e deixar rodar. O Anti-gravity é incrivelmente rápido. Provavelmente vou dar uns 15 a 20 minutos para ele. Certo, muito bom. Já se passaram cerca de 15 minutos e, como podem ver, ele conseguiu programar o projeto, iniciar o ambiente de execução e começar a rodar alguns testes. Se parássemos o processo, limpássemos a tela e listássemos o conteúdo desta pasta, veríamos a pasta do harness do BookStack, nosso project.toml, nossos testes e, em seguida, nosso api.md. O que

10:19 podemos fazer é criar o diretório docs e mover nossos documentos para lá depois que as IAs terminarem a implementação. Vamos esperar que termine. Certo, terminou. Experimentei um dos comandos que ele recomendou, mas ocorreu um erro. Vamos ver qual foi o erro. Deixe-me ver. Erro de rede após três tentativas em todas as redes. Parece que precisamos configurar nosso arquivo .env, certo? Ou nosso ambiente, para que possamos nos conectar ao backend do BookStack. Mas isso é bom, porque significa que ele incorporou

10:50 alguns recursos para corrigir erros e solucionar problemas. O que vamos fazer é copiar esta solicitação, redirecionar o modelo e dizer a ele o seguinte: o script de teste manual apresenta erros ao se conectar a um backend do BookStack. O próximo cenário deve informar por que a conexão falhou — não foi possível conectar a um servidor do BookStack — e orientar os usuários sobre como configurar a conexão. Certo? Então, embora tenhamos dado um plano, o plano não incluía essa opção. Vamos pedir que ele a adicione, certo? Vamos ver, e então

11:20 vamos continuar a partir daí. Certo. Voltamos com essa mensagem de erro e algumas orientações sobre onde o wiki do BookStack está hospedado. Ele conseguiu deixar tudo funcionando. Certo. Na minha instância do LM Studio, estamos esperando uma resposta. Vamos ver aqui. Consulta ao vivo do agent autônomo. Isso mesmo. Agora, vamos executar o agent do BookStack novamente. Vamos ver o que ele faz com a árvore. E olha só: ele criou uma árvore de conhecimento com todas as páginas do nosso wiki do BookStack. Ele

11:50 nos dá uma organização bem legal. Como podem ver, tenho algumas informações sobre o Portainer e algumas informações sobre o Windows e diferentes máquinas virtuais. Mas é isso, pessoal. É assim que você cria seu próprio agent harness. Espero que tenham achado este vídeo útil.

Transcrição original

[00:00] How to build your own agent harness. Welcome back, boys. This is another episode of LowSpec Labs. In our last video, we covered the idea of wrapping your API or whatever tool or environment you want around the model and giving the model a limited set of tools in order to let local AI to help local AI perform better. Now, most modern LLMs can build you a Python or, you know, whatever preferred language you want harness

[00:33] within a couple hours, right? It’ll get you a decent working MVP pretty quick. From there, the amount of time investment depends on how well you want the harness to work. If a couple hours of effort makes the model perform significantly better, in my mind, it’s worth it, right? an extra 10 to 12 hours of effort for maybe like another five to 10% performance gain isn’t worth it for me. I’ll just pay for Deep Seek. So, you have to decide how much time you want to take finetuning your harness. My

[01:03] recommendation is don’t spend more than a couple hours on it, especially if it’s only supposed to be calling one API. This video is more or less to teach you the common pitfalls and mistakes I ran into while building various agent harnesses. Turns out there’s kind of a right and wrong way to build the harness. Who would have thought? Am I an expert? No. But I can tell you what not to do based off of my own mistakes. To my right is what you would consider your

[01:33] standard agent harness loop. Right? You have your agent loop. Within that agent loop, you’ll have the harness or you have the agent and the agent will be used to plan and decomposition task. It’ll then move from there to call tools and then it’ll read the output of its tool and either make a further plan or go from there. Generally, you want this loop to be independent, right? You want the main loop to be different from your tool call handling, from your logging,

[02:04] intelligation, from any knowledge base or MCP or whatever you set up, even from user approvals. You want the main agent loop to be isolated. If we were to look at the bookstack folder from our last video, please go ahead and check that out to stay in the no. But inside of script/bookstack, we actually have our chat, which is our main agent loop. We’ve got docs because uh I do pass docs into and out of book stack. That’s where I store them. We’ve got logs, so we can

[02:35] log tool calls, chat, and history, and errors from the harness. We’ve got a requirements.ext text to set up our Python environment. We have a setup.sh and subscripts. And subscripts, that folder is what holds the rest of the modules for this harness, including tool calling, user requests, the configuration, processing, the knowledge base, and the logging and tele. Right? So, basically, you want to structure your folder as simple as possible. What

[03:06] you do not want to do, and this is from my own failures, is create one giant Python or bash script that you try to hold all the agent logic in. That is going to make it very hard for whatever AI you’re using to parse and edit and troubleshoot it. By going with the structure I showed you, like for instance, let’s enter that folder for subscripts. If we were to do a ls/subscripts, you’ll see here we have a goal tracker to track our goal. File manager, create

[03:37] docker, search, build, scratch, upload. These are all the different subscripts that add additional functionality and features to the harness. Note how they’re kept separated, at least logically, inside of this folder structure. And then we have the main chat.py at the top level. The end result is that you have a script which contains the main core of your agent loop and all the additional stuff like tool calling, your knowledge base, uh how it processes

[04:08] your goals, your configuration and settings, logging in and telemetry are all kept in separate scripts so that you can modify and tweak them independently without you having to break your entire loop. If you put everything in one giant script, you can still do that. is just going to be very difficult and eventually you’ll enter a situation where you want to break out that monolithic script. So, how do you actually build your agent harness? Well, you’re going to need AI or you’re going to need to know how to code. I am going

[04:38] with AI because AI is a much better coder and a much faster coder than I am. The wild part about this is you don’t even need the smartest AI to build out the agent harness. I’m pretty sure documentation has been out there for more than enough time now that most AIs trained on the general search area of the internet itself will be able to knock this out no problem. Claude, GPT, Deepseek, Kimmy, all of these can get

[05:09] you your agent harness built in about 30 minutes to an hour. At least your MVP, you know, your bare working product. From there, you might want to take a couple hours to tweak it and refine it, or maybe a couple days if you get hooked. For the purposes of this video, we’ll be using AGI since Google basically gives away Gemini and French for free nowadays. So, let’s do clear. As you can see, we have anti-gravity pulled up here, the CLI version, which is honestly the only version of it I would recommend using. Then we’re going

[05:40] to create a new folder and we’re going to walk through recreating the book stack harness that I demonstrated in the last video. First, you want to make sure that you have your documentation. Then we’re going to CD into our folder. Let’s do cd slash testbook stack. Then we’re going to start our agent harness, which in our case is going to be agy or Google’s anti-gravity. I know I’m using anti-gravity. That’s wild. It’s okay. it uh it works just fine. I would prefer

[06:11] Opus or Chad GBT models but I am out of tokens. So the ADI So AGI and Google I go they give away inference for basically free. So we’ll ask it to search the web for information about the bookstack API. Then we’ll ask it to save what it found to a markdown file. And that is the first pass. Before we even have it write the harness, we get information about the API and we save it

[06:45] locally. And that took about 60 seconds. This is one of the things I like about Gemini 3.7 and 3.8 Flash. It is a fast model. But it did the web search. It created api.md. Let’s go back and then let’s cd2 slash testbookstack ls. And we do have api.md. If we were to do a quick catap.md, you can see up here we have all the contents of the bookstack or the

[07:17] bookstack API, right? It gives us lots of useful information. This is going to be necessary because now we’re going to use that API spec to propose a plan. You don’t have to use this exact prompt, but the general drift is you want to get your API spec and then ask your smarter LLM to create an agent harness that wraps around that API spec. Something I also like to do when I’m having AI build stuff is to stop and ask me questions at

[07:47] least during the planning phase and oftentimes during the implementation phase. This gives you a chance for you to catch any weird design choices or weird implementation choices before the code’s complete. We’ll just walk through the options for this. For this, uh, Python’s good enough. We don’t need TypeScript or Node. Which interface surface should the agent harness expose? For our interfaces, we’ll go with an interactive CLI/Rebel.

[08:17] How should the tools be abstracted for LM usage? We’ll go with the recommendation and which reliability and safety harness feature should we build in and we’ll go with safe diff confirmation guard rails for page overwrite and delete actions. Right? So we want confirmations of certain destructive tool calls. There we go. The cool thing about Google anti-gravity is it’s very quick. Like look at that. All right. It’s already got the plan ready to go. Bookstack

[08:47] agent harness architecture and implementation plan. >> So now it’s asking if we want to implement that plan. We’re not going to implement it yet. Save that to working as plan MD. We’re instead going to save it as plan MD. Start a new session and then have the model start with a fresh context window on implementing our plan. We could also do that just by telling anti-gravity to launch a sub agent, but I like to keep things separated in different conversations because it helps

[09:18] keep things a little bit more organized. I went ahead and started a new session. We’re going to tell it to read plan.md and implement it. Use this lm studio backend and model to test during implementation. So if you can have LM Studio kind of ready and waiting to go in the background or llama CPP or onslaught or whatever inference engine you’re using and then we’re also going to give it the

[09:48] model and then we just hit enter and we let it run. Anti-gravity is incredibly fast. I’m probably going to give this like 15 to 20 minutes. All right, it’s very good. It’s about 15 minutes later and as you can see it was able to code up the project and launch the execution environment and start launching some tests. If we were to spin down clear and list the contents of this folder you’d see our bookstack harness folder our projecttoml our tests and then our api.md. What we

[10:19] can do is make dur docs and we’ll move our docs after the ais has finished its implementation. Let’s wait for it to finish. All right, and it’s done. I went ahead and I tried one of the commands it recommended and it errored out. So, let’s see what the error was. Let’s see. Network error after three at all networks. So, it looks like we have to configure our end, right? Or our environment file so that we can actually connect to the bookstack backend. But that’s good because that means it baked

[10:50] in some error correcting and troubleshooting. What we’re going to do is just copy this request and we’re going to rest steer the model and we’re going to tell it the prompt we told it to rest steer is upon manual testing script has errors when connecting to a bookstack backend. The next scenario should report why connection failed unable to connect to a Bookstack server and guide users on how to configure connection. Right? So even though we gave it a plan, the plan did not include that option. So we’re just going to have it added. Right? Uh we’ll see and then

[11:20] we’ll continue from there. All right. And we are back with that error message and some guidance about where the Bookstack wiki is actually hosted. It was able to get everything spun up. All right. On my LM Studio instance, we’re waiting for a response back. Let’s see here. Live query autonomous agent. Yep. Now, let’s run Bookstack agent again. And let’s see what it does with tree. And look at that. It’s created a knowledge tree of all our different pages within our Bookstack wiki. It

[11:50] gives us a pretty neat layout. As you can see, I have some Portainer information, some Windows information about different virtual machines. But that’s it, boys. That is how you build your own agent harness. I hope you found this video useful.