Um Agent Harness é a infraestrutura de software que envolve um modelo de linguagem, permitindo que ele execute ações.

A infraestrutura é responsável por:

• Construir o contexto do modelo.
• Comunicar-se com o LLM.
• Fornecer ferramentas ao LLM.
• Executar as chamadas de ferramentas solicitadas.
• Retornar os resultados das ferramentas ao modelo.
• Gerenciar conversas e sessões.
• Controlar o ciclo de vida da execução.

O LLM fornece as capacidades de raciocínio.

A infraestrutura fornece o ambiente no qual esse raciocínio pode ser traduzido em ações.

Um chatbot tradicional geralmente segue este padrão:

flowchart LR
    A["Usuário"] --> B["Prompt"]
    B --> C["LLM"]
    C --> D["Resposta"]

Um agente de codificação de IA adiciona um ambiente de execução:

flowchart TD
    A["Usuário"] --> B["Agente Pi"]
    B --> C["LLM"]
    C --> D{"Ferramenta necessária?"}
    D -->|Sim| E["Executar Ferramenta"]
    E --> F["Retornar Resultado"]
    F --> C
    D -->|Não| G["Resposta Final"]

Exemplo:

Chatbot: "Aqui está o código Python que calcula despesas."

Pi: "Eu criei os arquivos Python, executei o programa, rodei os testes e corrigi um erro."

A diferença importante é a capacidade de interagir com um ambiente real.

Minimalismo:

• Mantenha o núcleo relativamente pequeno.
• Evite abstrações desnecessárias.
• Construa sobre ferramentas existentes do sistema operacional.

Extensibilidade:

• Crie ferramentas personalizadas.
• Construa extensões.
• Use habilidades reutilizáveis.
• Conecte serviços externos.

Independência de Modelo:

• Use diferentes provedores de LLM.
• Troque de modelos dentro do mesmo ambiente.
• Compare o comportamento dos modelos.

Transparência:

• Observe as respostas do modelo.
• Inspecione as execuções de ferramentas.
• Revise as modificações.
• Examine o histórico da sessão.

Uma configuração básica do Pi não requer:

• Um banco de dados vetorial.
• Um servidor de orquestração separado.
• Kubernetes.
• Docker.
• Uma estrutura multi-agente complexa.
• Uma aplicação de backend personalizada.

Para uma demonstração básica, um terminal, um LLM suportado e um diretório local são suficientes.

flowchart TB
    USER["Desenvolvedor"]

    subgraph PI["Pi Coding Agent"]
        UI["Interface de Terminal"]
        CORE["Runtime do Agente"]
        CONTEXT["Gerenciador de Contexto"]
        SESSION["Gerenciador de Sessão"]
        TOOLS["Execução de Ferramentas"]
        EXT["Extensões / Habilidades"]
        API["Abstração de API de LLM"]
    end

    subgraph MODELS["Provedores de LLM"]
        OPENAI["OpenAI"]
        ANTHROPIC["Anthropic"]
        GOOGLE["Google"]
        LOCAL["Modelos Locais"]
    end

    subgraph SYSTEM["Ambiente de Desenvolvimento"]
        FILES["Sistema de Arquivos"]
        BASH["Shell"]
        GIT["Git"]
        TESTS["Testes"]
    end

    USER <--> UI
    UI <--> CORE

    CORE <--> CONTEXT
    CORE <--> SESSION
    CORE <--> TOOLS
    CORE <--> API

    EXT --> CORE

    API <--> OPENAI
    API <--> ANTHROPIC
    API <--> GOOGLE
    API <--> LOCAL

    TOOLS <--> FILES
    TOOLS <--> BASH
    TOOLS <--> GIT
    TOOLS <--> TESTS

Esta é uma arquitetura conceitual, mostrando as principais responsabilidades em vez de cada dependência interna.

O Pi é desenvolvido como uma coleção de pacotes TypeScript.

flowchart TD
    USER["Desenvolvedor"]
    TUI["pi-tui"]
    CODING["pi-coding-agent"]
    CORE["pi-agent-core"]
    AI["pi-ai"]
    LLM["Provedores de LLM"]

    USER <--> TUI
    TUI <--> CODING
    CODING <--> CORE
    CORE <--> AI
    AI <--> LLM

    CODING --> FS["Ferramentas"]
    CODING --> SESSION["Sessões"]
    CODING --> EXT["Extensões"]

A mesma infraestrutura de agente também pode ser usada por meio de interfaces não interativas.

Exemplo:

"Crie uma aplicação Python que rastreie despesas."

O Pi recebe esta solicitação através de sua interface de terminal.

Antes de contatar o LLM, o Pi prepara o contexto.

Isso pode incluir:

• Instruções do sistema.
• Solicitação do usuário.
• Histórico de conversa ativo.
• Ferramentas disponíveis.
• Instruções de projeto do AGENTS.md.
• Descrições de habilidades.
• Conteúdo de arquivos relevantes.
• Configuração do modelo.

O ramo da sessão ativa determina quais mensagens históricas são incluídas.

O Pi envia a solicitação preparada para o provedor de LLM selecionado.

O LLM pode produzir:

• Texto em linguagem natural.
• Chamadas de ferramentas estruturadas.
• Uma combinação de ambos.

Exemplo de solicitação de ferramenta:

Ferramenta: write Arquivo: expenses.py Conteúdo: Código-fonte Python

O LLM não escreve o arquivo diretamente.

Ele solicita que o Pi execute a operação.

O Pi recebe a chamada de ferramenta solicitada.

O executor de ferramentas realiza a ação.

Exemplos:

• Ler um arquivo.
• Escrever um arquivo.
• Modificar código.
• Executar um comando shell.

O Pi então captura o resultado.

A saída é retornada ao runtime do agente.

Exemplo:

Ferramenta: bash Comando: python expenses.py

Resultado: Traceback: NameError …

O resultado torna-se parte do contexto disponível para o LLM.

O LLM pode decidir:

• Chamar outra ferramenta.
• Modificar o código.
• Rodar testes adicionais.
• Fornecer uma resposta final.

O Pi repete o processo enquanto mais execução for necessária.

Esta interação é a base do comportamento agentico.

Três responsabilidades são separadas:

1. LLM: Gera raciocínio e propõe ações.
2. Agent Harness: Coordena a execução e gerencia o contexto.
3. Ferramentas: Realizam operações no ambiente.

Esta arquitetura também é fundamental para muitas outras implementações de agentes de IA.

Ler o conteúdo de arquivos.

Exemplo de prompt:

"Leia app.py e explique sua estrutura."

Criar ou sobrescrever arquivos.

Exemplo de prompt:

"Crie um programa Python que imprima Hello TechHive."

Modificar arquivos existentes.

Exemplo de prompt:

"Modifique o programa para aceitar um nome de usuário."

Executar comandos shell.

Exemplo de prompt:

"Execute o programa e exiba o resultado."

flowchart TD
    A["Usuário: Corrija o bug"]
    B["LLM analisa a solicitação"]
    C["read: Inspecionar código"]
    D["edit: Corrigir código"]
    E["bash: Rodar testes"]
    F{"Testes passaram?"}
    G["Resposta final"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F -->|Não| B
    F -->|Sim| G

Ferramentas integradas adicionais e extensões podem estar disponíveis dependendo da versão e configuração.

Contexto é a informação fornecida ao LLM para uma solicitação de modelo.

Pode incluir:

• Solicitação atual do usuário.
• Histórico de conversa.
• Resultados de ferramentas.
• Instruções do sistema.
• Instruções do projeto.
• Descrições de habilidades.
• Conteúdo de arquivos referenciados.

O Pi não carrega automaticamente todos os arquivos de um repositório para o contexto do LLM.

Ele seleciona e monta o contexto com base na sessão e nos recursos configurados.

AGENTS.md é um arquivo de instruções do projeto.

Exemplo:

# Instruções do Projeto

Este projeto é para um workshop de agente de codificação.

Diretrizes:
- Use Python.
- Prefira a biblioteca padrão.
- Mantenha o código simples.
- Escreva funções legíveis.
- Adicione testes para novos recursos.
- Explique mudanças importantes.

Essas instruções ajudam a guiar o comportamento do agente dentro do projeto.

O Pi mantém sessões de conversa.

As sessões podem incluir:

• Mensagens do usuário.
• Mensagens do assistente.
• Chamadas de ferramentas.
• Resultados de ferramentas.
• Mudanças de modelo.
• Eventos de compactação de contexto.

Sessões persistentes usam arquivos JSONL.

O Pi suporta uma estrutura de conversa baseada em árvore.

flowchart TD
    A["Iniciar Sessão"]
    B["Criar Aplicação"]
    C["Adicionar Armazenamento de Dados"]

    D["Abordagem CSV"]
    E["Abordagem SQLite"]

    F["Testar CSV"]
    G["Testar SQLite"]

    A --> B
    B --> C
    C --> D
    C --> E
    D --> F
    E --> G

Ramificações permitem a exploração de abordagens alternativas a partir de estados anteriores da conversa.

Conversas longas podem exceder a janela de contexto de um modelo.

O Pi pode resumir contextos mais antigos para reduzir a quantidade de informações enviadas em futuras solicitações de modelo.

Comando:

/compact

A compactação ajuda a gerenciar o tamanho do contexto, mas pode perder alguns detalhes de mensagens mais antigas.

As entradas originais da sessão podem permanecer no histórico de sessão armazenado.

flowchart TD
    USER["Desenvolvedor"]
    PI["Agente Pi"]
    API["Interface Unificada de Modelo"]

    USER --> PI
    PI --> API

    API --> A["OpenAI"]
    API --> B["Anthropic"]
    API --> C["Google"]
    API --> D["Modelo Local"]

Vantagens:

• Flexibilidade.
• Comparação de modelos.
• Escolha de provedor.
• Otimização de custos.
• Experimentação.

As capacidades e a compatibilidade dos modelos podem variar.

Instruções específicas do projeto.

Prompts reutilizáveis para atividades recorrentes.

Exemplos:

• Revisão de código.
• Documentação.
• Geração de testes.
• Refatoração.

Instruções reutilizáveis e recursos de suporte para fluxos de trabalho especializados.

Exemplos:

• Fluxo de trabalho de testes em Python.
• Fluxo de trabalho de implantação.
• Geração de documentação.
• Desenvolvimento de API.

Personalização baseada em TypeScript.

As extensões podem:

• Definir ferramentas personalizadas.
• Registrar comandos.
• Reagir a eventos de ciclo de vida.
• Integrar serviços externos.
• Personalizar o comportamento interativo.

MCP significa Model Context Protocol (Protocolo de Contexto de Modelo).

Ele fornece uma maneira padronizada para aplicações acessarem ferramentas e recursos externos.

Versões modernas do Pi fornecem suporte nativo ao MCP.

Exemplos de integrações:

• GitHub.
• Bancos de dados.
• Aplicações internas.
• Serviços remotos.

Inicie a interface de terminal.

pi

Execute um prompt e imprima sua resposta.

pi -p "Explique decoradores Python"

Transmita eventos estruturados do agente.

pi --mode json -p "Explique este projeto"

Controle o Pi usando mensagens JSONL através de entrada e saída padrão.

Incorpore as capacidades do agente Pi em aplicações TypeScript.

flowchart TD
    CORE["Runtime do Agente Pi"]

    CORE --> A["TUI Interativa"]
    CORE --> B["Imprimir / JSON"]
    CORE --> C["RPC"]
    CORE --> D["SDK TypeScript"]

    A --> E["Desenvolvedor"]
    B --> F["Scripts de Automação"]
    C --> G["Aplicação Externa"]
    D --> H["Aplicação de Agente Personalizada"]

macOS / Linux:

curl -fsSL https://pi.dev/install.sh | sh

Windows PowerShell:

irm https://pi.dev/install.ps1 | iex

Alternativa usando npm:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

A instalação via npm requer Node.js 22.19 ou mais recente.

Dentro do Pi:

/login

Selecione um provedor suportado e autentique-se.

Então:

/model

Selecione o modelo que você deseja usar.

Prompt:

Inspecione o diretório atual.

Explique quais arquivos estão presentes.

Não modifique nada.

Conceito: Exploração do sistema de arquivos e operações de leitura.

Prompt:

Crie um rastreador de despesas Python simples.

Requisitos:
- Adicionar uma despesa.
- Listar despesas.
- Calcular o total de despesas.
- Armazenar despesas em um arquivo CSV.
- Use apenas a biblioteca padrão do Python.

Mantenha a implementação simples.

Conceito: Geração de código e criação de arquivos.

Prompt:

Execute a aplicação.

Crie três exemplos de despesas.

Verifique se o total é calculado corretamente.

Conceito: Execução de shell e observação de resultados.

Prompt:

Crie testes unitários usando unittest do Python.

Teste a criação de despesas e o cálculo do total.

Execute os testes e corrija quaisquer erros.

Conceito: Testes autônomos e correção iterativa.

Prompt:

Adicione um recurso para agrupar despesas por categoria.

Exiba o total para cada categoria.

Atualize os testes e execute-os.

Conceito: Modificação de código e retenção de contexto.

Comandos:

/session /tree /model

Conceito: Histórico de sessão, ramificação e troca de modelo.

Infraestrutura de agente de codificação minimalista e extensível.

Pontos fortes:

• Personalização.
• Múltiplos provedores de LLM.
• Execução de ferramentas.
• Gerenciamento de sessão.
• Extensibilidade.

Agente de codificação com um conjunto integrado de ferramentas de desenvolvimento e fluxos de trabalho.

Agente de codificação projetado para trabalhar com bases de código, comandos de terminal e fluxos de trabalho de desenvolvimento.

Frameworks para desenvolver aplicações de LLM personalizadas e fluxos de trabalho agenticos.

O Pi é principalmente uma infraestrutura de agente pronta para uso e extensível, em vez de um framework de fluxo de trabalho de propósito geral.