Documentação oficial desta página · v0.20.6

Usar o Hermes como Biblioteca Python

O Hermes não é só uma ferramenta de linha de comando. Você pode importar AIAgent direto e usá-lo de forma programática nos seus próprios scripts Python, aplicações web ou pipelines de automação. Este guia mostra como.

Instalação

Clone o Hermes e crie o ambiente de desenvolvimento editável que ele suporta:

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
uv sync

Rode sua aplicação com uv run python sua_app.py a partir desse checkout. O Hermes não publica wheel nem distribuição de código-fonte com suporte para instalações via requirements.txt.

dica

As mesmas variáveis de ambiente usadas pela CLI são exigidas ao usar o Hermes como biblioteca. No mínimo, defina OPENROUTER_API_KEY (ou OPENAI_API_KEY / ANTHROPIC_API_KEY se for acessar o provedor direto).

Uso básico

A forma mais simples de usar o Hermes é o método chat() — você passa uma mensagem e recebe uma string de volta:

from run_agent import AIAgent

agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    quiet_mode=True,
)
response = agent.chat("Qual é a capital da França?")
print(response)

O chat() cuida do laço completo da conversa internamente — chamadas de ferramenta, novas tentativas, tudo — e devolve apenas a resposta final em texto.

aviso

Sempre defina quiet_mode=True ao embutir o Hermes no seu próprio código. Sem isso, o agente imprime spinners da CLI, indicadores de progresso e outras saídas de terminal que vão poluir a saída da sua aplicação.

Controle total da conversa

Para ter mais controle sobre a conversa, use run_conversation() direto. Ele devolve um dicionário com a resposta completa, o histórico de mensagens e metadados:

agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    quiet_mode=True,
)

result = agent.run_conversation(
    user_message="Pesquise os recursos recentes do Python 3.13",
    task_id="minha-tarefa-1",
)

print(result["final_response"])
print(f"Mensagens trocadas: {len(result['messages'])}")

O dicionário devolvido contém:

final_response — a resposta final em texto do agente
messages — o histórico completo de mensagens (sistema, usuário, assistente, chamadas de ferramenta)

(O task_id que você passa fica guardado na instância do agente para isolamento de VM, mas não é devolvido no dicionário de retorno.)

Você também pode passar uma mensagem de sistema própria, que sobrepõe o prompt de sistema efêmero naquela chamada:

result = agent.run_conversation(
    user_message="Explique o quicksort",
    system_message="Você é um professor de ciência da computação. Use analogias simples.",
)

Configurar as ferramentas

Controle a quais conjuntos de ferramentas o agente tem acesso usando enabled_toolsets ou disabled_toolsets:

# Habilita só as ferramentas de web (navegação, busca)
agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    enabled_toolsets=["web"],
    quiet_mode=True,
)

# Habilita tudo, menos o acesso ao terminal
agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    disabled_toolsets=["terminal"],
    quiet_mode=True,
)

dica

Use enabled_toolsets quando quiser um agente mínimo e trancado (por exemplo, só busca na web para um bot de pesquisa). Use disabled_toolsets quando quiser a maioria das capacidades, mas precisar restringir algumas específicas (por exemplo, nenhum acesso ao terminal em um ambiente compartilhado).

Conversas com vários turnos

Mantenha o estado da conversa entre turnos passando o histórico de mensagens de volta:

agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    quiet_mode=True,
)

# Primeiro turno
result1 = agent.run_conversation("Meu nome é Alice")
history = result1["messages"]

# Segundo turno — o agente lembra do contexto
result2 = agent.run_conversation(
    "Qual é o meu nome?",
    conversation_history=history,
)
print(result2["final_response"])  # "Seu nome é Alice."

O parâmetro conversation_history aceita a lista messages de um resultado anterior. O agente faz uma cópia interna, então a sua lista original nunca é alterada.

Salvar trajetórias

Ative o salvamento de trajetórias para capturar conversas no formato ShareGPT — útil para gerar dados de treino ou depurar:

agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    save_trajectories=True,
    quiet_mode=True,
)

agent.chat("Escreva uma função Python que ordena uma lista")
# Salva em trajectory_samples.jsonl no formato ShareGPT

Cada conversa é acrescentada como uma única linha JSONL, o que facilita montar conjuntos de dados a partir de execuções automatizadas.

Prompts de sistema próprios

Use ephemeral_system_prompt para definir um prompt de sistema próprio que guia o comportamento do agente, mas não é salvo nos arquivos de trajetória (mantendo seus dados de treino limpos):

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    ephemeral_system_prompt="Você é especialista em SQL. Responda só perguntas sobre banco de dados.",
    quiet_mode=True,
)

response = agent.chat("Como escrevo uma consulta com JOIN?")
print(response)

Isso é ideal para construir agentes especializados — um revisor de código, um redator de documentação, um assistente de SQL — todos usando a mesma base de ferramentas.

Processamento em lote

Para rodar muitos prompts em paralelo, o Hermes inclui o batch_runner.py. Ele gerencia instâncias concorrentes de AIAgent com isolamento adequado de recursos:

python batch_runner.py --input prompts.jsonl --output results.jsonl

Cada prompt ganha o próprio task_id e um ambiente isolado. Se você precisa de uma lógica de lote própria, pode montar a sua usando AIAgent direto:

import concurrent.futures
from run_agent import AIAgent

prompts = [
    "Explique recursão",
    "O que é uma tabela hash?",
    "Como funciona a coleta de lixo?",
]

def process_prompt(prompt):
    # Cria um agente novo por tarefa, para garantir segurança entre threads
    agent = AIAgent(
        model="anthropic/claude-sonnet-4",
        quiet_mode=True,
        skip_memory=True,
    )
    return agent.chat(prompt)

with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
    results = list(executor.map(process_prompt, prompts))

for prompt, result in zip(prompts, results):
    print(f"P: {prompt}\nR: {result}\n")

aviso

Sempre crie uma nova instância de AIAgent por thread ou tarefa. O agente mantém estado interno (histórico de conversa, sessões de ferramenta, contadores de iteração) que não é seguro compartilhar entre threads.

Exemplos de integração

Endpoint FastAPI

from fastapi import FastAPI
from pydantic import BaseModel
from run_agent import AIAgent

app = FastAPI()

class ChatRequest(BaseModel):
    message: str
    model: str = "anthropic/claude-sonnet-4"

@app.post("/chat")
async def chat(request: ChatRequest):
    agent = AIAgent(
        model=request.model,
        quiet_mode=True,
        skip_context_files=True,
        skip_memory=True,
    )
    response = agent.chat(request.message)
    return {"response": response}

Bot do Discord

import discord
from run_agent import AIAgent

client = discord.Client(intents=discord.Intents.default())

@client.event
async def on_message(message):
    if message.author == client.user:
        return
    if message.content.startswith("!hermes "):
        query = message.content[8:]
        agent = AIAgent(
            model="anthropic/claude-sonnet-4",
            quiet_mode=True,
            skip_context_files=True,
            skip_memory=True,
            platform="discord",
        )
        response = agent.chat(query)
        await message.channel.send(response[:2000])

client.run("YOUR_DISCORD_TOKEN")

Etapa de pipeline CI/CD

#!/usr/bin/env python3
"""Etapa de CI: revisa automaticamente o diff de um PR."""
import subprocess
from run_agent import AIAgent

diff = subprocess.check_output(["git", "diff", "main...HEAD"]).decode()

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
    skip_context_files=True,
    skip_memory=True,
    disabled_toolsets=["terminal", "browser"],
)

review = agent.chat(
    f"Revise este diff de PR em busca de bugs, problemas de segurança e questões de estilo:\n\n{diff}"
)
print(review)

Principais parâmetros do construtor

Parâmetro	Tipo	Padrão	Descrição
`model`	`str`	`""`	Modelo no formato do OpenRouter (vazio por padrão; resolvido a partir da sua config do hermes em tempo de execução)
`quiet_mode`	`bool`	`False`	Suprime a saída da CLI
`enabled_toolsets`	`List[str]`	`None`	Lista de permissão de conjuntos de ferramentas específicos
`disabled_toolsets`	`List[str]`	`None`	Lista de bloqueio de conjuntos de ferramentas específicos
`save_trajectories`	`bool`	`False`	Salva as conversas em JSONL
`ephemeral_system_prompt`	`str`	`None`	Prompt de sistema próprio (não salvo nas trajetórias)
`max_iterations`	`int`	`500`	Máximo de iterações de chamada de ferramenta por conversa
`skip_context_files`	`bool`	`False`	Não carrega arquivos AGENTS.md
`skip_memory`	`bool`	`False`	Desativa leitura/escrita da memória persistente
`api_key`	`str`	`None`	Chave de API (recorre às variáveis de ambiente)
`base_url`	`str`	`None`	URL própria do endpoint da API
`platform`	`str`	`None`	Dica de plataforma (`"discord"`, `"telegram"` etc.)

Observações importantes

dica

Defina skip_context_files=True se não quiser que os arquivos AGENTS.md do diretório de trabalho sejam carregados no prompt de sistema.
Defina skip_memory=True para impedir que o agente leia ou escreva na memória persistente — recomendado para endpoints de API sem estado.
O parâmetro platform (por exemplo, "discord", "telegram") injeta dicas de formatação específicas da plataforma, para que o agente adapte o estilo da saída.

aviso

Segurança entre threads: crie um AIAgent por thread ou tarefa. Nunca compartilhe uma instância entre chamadas concorrentes.
Limpeza de recursos: o agente limpa os recursos automaticamente (sessões de terminal, instâncias de navegador) quando a conversa termina. Se você roda em um processo de vida longa, garanta que cada conversa se encerre normalmente.
Limites de iteração: o padrão max_iterations=500 é generoso. Para casos simples de pergunta e resposta, considere reduzi-lo (por exemplo, max_iterations=10) para evitar laços descontrolados de chamada de ferramenta e controlar custos.

Instalação​

Uso básico​

Controle total da conversa​

Configurar as ferramentas​

Conversas com vários turnos​

Salvar trajetórias​

Prompts de sistema próprios​

Processamento em lote​

Exemplos de integração​

Endpoint FastAPI​

Bot do Discord​

Etapa de pipeline CI/CD​

Principais parâmetros do construtor​

Observações importantes​

Instalação

Uso básico

Controle total da conversa

Configurar as ferramentas

Conversas com vários turnos

Salvar trajetórias

Prompts de sistema próprios

Processamento em lote

Exemplos de integração

Endpoint FastAPI

Bot do Discord

Etapa de pipeline CI/CD

Principais parâmetros do construtor

Observações importantes