📐 Arquitetando Seu Agente

Checklist de Escopo do Agente

Setup Inicial — Python + Ollama

# Terminal: instalar dependências
pip install ollama

# Python: testar conexão
from ollama import chat

response = chat(
    model='qwen3:8b',
    messages=[
        {'role': 'user', 'content': 'Hello, are you working?'}
    ]
)
print(response.message.content)

# Pré-requisito: Ollama rodando em localhost:11434
# Instale: https://ollama.ai → ollama pull qwen3:8b

Mapeamento: Claude Code → Python

Implementação do Tool Registry

# tool_registry.py
from pathlib import Path
import subprocess

# 1. Funções das ferramentas
def read_file(path: str) -> str:
    return Path(path).read_text(encoding='utf-8')

def run_shell(command: str) -> str:
    result = subprocess.run(command, shell=True, capture_output=True, text=True, timeout=60)
    return result.stdout + result.stderr

# 2. Mapa nome → função
TOOL_MAP = {
    'read_file': read_file,
    'run_shell': run_shell,
}

# 3. Schemas para o LLM
TOOL_SCHEMAS = [
    {
        'type': 'function',
        'function': {
            'name': 'read_file',
            'description': 'Read contents of a file',
            'parameters': {
                'type': 'object',
                'properties': {
                    'path': {'type': 'string', 'description': 'File path to read'}
                },
                'required': ['path']
            }
        }
    },
    {
        'type': 'function',
        'function': {
            'name': 'run_shell',
            'description': 'Run a shell command',
            'parameters': {
                'type': 'object',
                'properties': {
                    'command': {'type': 'string', 'description': 'Shell command to execute'}
                },
                'required': ['command']
            }
        }
    }
]

# 4. Dispatch: executar ferramenta por nome
def execute_tool(name: str, args: dict) -> str:
    if name not in TOOL_MAP:
        return f"Error: unknown tool '{name}'"
    try:
        return TOOL_MAP[name](**args)
    except Exception as e:
        return f"Error: {e}"

Implementação do Context Manager

# context_manager.py
import json

def estimate_tokens(text: str) -> int:
    """Estimativa simples: ~4 chars por token."""
    return len(text) // 4

def trim_messages(messages: list, max_tokens: int = 30000) -> list:
    """Mantém system prompt + mensagens mais recentes dentro do budget."""
    # Sempre preservar system messages
    system = [m for m in messages if m['role'] == 'system']
    non_system = [m for m in messages if m['role'] != 'system']

    # Calcular tokens do system prompt
    system_tokens = sum(estimate_tokens(json.dumps(m)) for m in system)
    budget = max_tokens - system_tokens

    # Adicionar mensagens de trás pra frente (mais recentes primeiro)
    kept = []
    used = 0
    for msg in reversed(non_system):
        msg_tokens = estimate_tokens(json.dumps(msg))
        if used + msg_tokens > budget:
            break
        kept.insert(0, msg)
        used += msg_tokens

    return system + kept

class ContextManager:
    def __init__(self, max_tokens: int = 30000):
        self.max_tokens = max_tokens
        self.messages: list = []

    def add(self, message: dict):
        self.messages.append(message)
        self.messages = trim_messages(self.messages, self.max_tokens)

    def get_messages(self) -> list:
        return self.messages.copy()

    def token_usage(self) -> int:
        return sum(estimate_tokens(json.dumps(m)) for m in self.messages)

Implementação do Permission Controller

# permissions.json
{
    "read_file": "allow",
    "write_file": "ask",
    "run_shell": "ask",
    "search_in_files": "allow",
    "delete_file": "deny"
}

# permission_controller.py
import json
from pathlib import Path

class PermissionController:
    def __init__(self, config_path: str = 'permissions.json'):
        self.rules = json.loads(Path(config_path).read_text())

    def check(self, tool_name: str) -> str:
        """Retorna 'allow', 'ask' ou 'deny'."""
        return self.rules.get(tool_name, 'ask')

    def request_permission(self, tool_name: str, args: dict) -> bool:
        """Pede confirmação ao usuário para ferramentas 'ask'."""
        permission = self.check(tool_name)
        if permission == 'allow':
            return True
        if permission == 'deny':
            print(f"BLOCKED: {tool_name} is denied by policy")
            return False
        # permission == 'ask'
        print(f"\n⚠️  Tool: {tool_name}")
        print(f"   Args: {json.dumps(args, indent=2)}")
        resp = input("   Allow? [y/N]: ").strip().lower()
        return resp == 'y'