From e31a904780f7a2419568ffbfd18e16cab76b5646 Mon Sep 17 00:00:00 2001 From: Wesley Simplicio Date: Fri, 8 May 2026 22:04:35 -0300 Subject: [PATCH 1/3] docs(i18n): add Brazilian Portuguese (pt-BR) README and Docusaurus locale MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add native pt-BR translation of the main README plus bootstrap of the Docusaurus pt-BR locale, complementing existing pt-BR work in flight. - README.pt-BR.md: full native translation of README.md (mirrors the README.zh-CN.md structural template; not a machine translation). - README.md / README.zh-CN.md: add bidirectional language badge to README.pt-BR.md. - website/docusaurus.config.ts: register `pt-BR` alongside `en` and `zh-Hans` with localized label "Português (Brasil)". - website/i18n/pt-BR/.../features/image-generation.md: seed translation of the image-generation guide to mirror the parity coverage that zh-Hans currently has (3 docs translated). Additional pages can be added incrementally without further config changes. This contribution intentionally avoids overlap with the in-flight pt-BR PRs: - #15737 (web/src/i18n/pt.ts) -- Web UI strings - #20443 (locales/pt.yaml + agent/i18n.py) -- CLI runtime catalog - #22063 (web/src/i18n/pt-BR.ts) -- Web UI strings Surfaces here (root README + Docusaurus docs site i18n) are not touched by any of the above. --- README.md | 1 + README.pt-BR.md | 196 ++++++++++++++++++ README.zh-CN.md | 1 + website/docusaurus.config.ts | 6 +- .../user-guide/features/image-generation.md | 156 ++++++++++++++ 5 files changed, 359 insertions(+), 1 deletion(-) create mode 100644 README.pt-BR.md create mode 100644 website/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-guide/features/image-generation.md diff --git a/README.md b/README.md index 8b8a078b2507..e5fde202e7f9 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ License: MIT Built by Nous Research 中文 + Português (Brasil)

**The self-improving AI agent built by [Nous Research](https://nousresearch.com).** It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. Run it on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle. It's not tied to your laptop — talk to it from Telegram while it works on a cloud VM. diff --git a/README.pt-BR.md b/README.pt-BR.md new file mode 100644 index 000000000000..abc17f86f89e --- /dev/null +++ b/README.pt-BR.md @@ -0,0 +1,196 @@ +

+ Hermes Agent +

+ +# Hermes Agent ☤ + +

+ Documentação + Discord + Licença: MIT + Feito por Nous Research + English + 中文 +

+ +**O agente de IA autoaperfeiçoante criado pela [Nous Research](https://nousresearch.com).** É o único agente com um loop de aprendizado embutido — ele cria habilidades a partir da experiência, aprimora elas durante o uso, se autoincentiva a persistir conhecimento, busca nas próprias conversas anteriores e constrói um modelo cada vez mais profundo de quem você é ao longo das sessões. Roda num VPS de $5, num cluster de GPU ou em infraestrutura serverless que custa quase nada quando ociosa. Não fica preso ao seu notebook — fale com ele pelo Telegram enquanto ele trabalha numa VM na nuvem. + +Use qualquer modelo que quiser — [Nous Portal](https://portal.nousresearch.com), [OpenRouter](https://openrouter.ai) (200+ modelos), [NVIDIA NIM](https://build.nvidia.com) (Nemotron), [Xiaomi MiMo](https://platform.xiaomimimo.com), [z.ai/GLM](https://z.ai), [Kimi/Moonshot](https://platform.moonshot.ai), [MiniMax](https://www.minimax.io), [Hugging Face](https://huggingface.co), OpenAI ou seu próprio endpoint. Troque com `hermes model` — sem mudar código, sem aprisionamento. + + + + + + + + + +
Interface de terminal de verdadeTUI completa com edição multilinha, autocompletar de slash commands, histórico de conversa, interromper-e-redirecionar e saída de ferramenta em streaming.
Vive onde você estáTelegram, Discord, Slack, WhatsApp, Signal e CLI — tudo a partir de um único processo de gateway. Transcrição de mensagem de voz, continuidade de conversa entre plataformas.
Loop de aprendizado fechadoMemória curada pelo agente com lembretes periódicos. Criação autônoma de habilidades depois de tarefas complexas. Habilidades se aprimoram durante o uso. Busca de sessão FTS5 com sumarização por LLM para resgate entre sessões. Modelagem dialética de usuário com Honcho. Compatível com o padrão aberto agentskills.io.
Automações agendadasAgendador cron embutido com entrega para qualquer plataforma. Relatórios diários, backups noturnos, auditorias semanais — tudo em linguagem natural, rodando sem supervisão.
Delega e paralelizaCria subagentes isolados para fluxos de trabalho paralelos. Escreva scripts Python que chamam ferramentas via RPC, comprimindo pipelines de múltiplos passos em turnos com custo de contexto zero.
Roda em qualquer lugar, não só no seu notebookSete backends de terminal — local, Docker, SSH, Singularity, Modal, Daytona e Vercel Sandbox. Daytona e Modal oferecem persistência serverless — o ambiente do seu agente hiberna quando ocioso e acorda sob demanda, custando quase nada entre sessões. Roda num VPS de $5 ou num cluster de GPU.
Pronto para pesquisaGeração em lote de trajetórias, ambientes de RL Atropos, compressão de trajetórias para treinar a próxima geração de modelos com tool calling.
+ +--- + +## Instalação rápida + +### Linux, macOS, WSL2, Termux + +```bash +curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash +``` + +### Windows (nativo, PowerShell) — Beta inicial + +> **Atenção:** O suporte nativo ao Windows está em **beta inicial**. Instala e roda, mas ainda não foi testado tão amplamente quanto os caminhos Linux/macOS/WSL2. Por favor [abra issues](https://github.com/NousResearch/hermes-agent/issues) quando encontrar problemas. Para o setup mais estável no Windows hoje, rode o one-liner de Linux/macOS acima dentro do **WSL2**. + +Execute no PowerShell: + +```powershell +irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex +``` + +O instalador cuida de tudo: uv, Python 3.11, Node.js, ripgrep, ffmpeg **e um Git Bash portátil** (MinGit, descompactado em `%LOCALAPPDATA%\hermes\git` — sem precisar de admin, completamente isolado de qualquer instalação de Git do sistema). O Hermes usa esse Git Bash empacotado para rodar comandos shell. + +Se você já tem Git instalado, o instalador detecta e usa esse. Caso contrário, um download de ~45MB do MinGit é tudo que você precisa — e ele não toca nem interfere em nenhum Git do sistema. + +> **Android / Termux:** O caminho manual testado está documentado no [guia do Termux](https://hermes-agent.nousresearch.com/docs/getting-started/termux). No Termux, o Hermes instala um extra `.[termux]` curado, porque o extra completo `.[all]` puxa dependências de voz incompatíveis com Android. +> +> **Windows:** O Windows nativo é suportado como **beta inicial** — o one-liner do PowerShell acima instala tudo, mas espere imperfeições e por favor abra issues quando encontrar. Se preferir usar WSL2 (nosso caminho de Windows mais testado), o comando do Linux funciona lá também. A instalação nativa do Windows fica em `%LOCALAPPDATA%\hermes`; instalações WSL2 ficam em `~/.hermes` como no Linux. A única feature do Hermes que precisa especificamente de WSL2 hoje é o painel de chat baseado em navegador (usa um PTY POSIX — o CLI clássico e o gateway rodam ambos nativamente). + +Após a instalação: + +```bash +source ~/.bashrc # recarrega o shell (ou: source ~/.zshrc) +hermes # comece a conversar! +``` + +--- + +## Primeiros passos + +```bash +hermes # CLI interativo — comece uma conversa +hermes model # Escolha o provedor de LLM e o modelo +hermes tools # Configure quais ferramentas estão habilitadas +hermes config set # Defina valores de configuração individuais +hermes gateway # Inicia o gateway de mensagens (Telegram, Discord, etc.) +hermes setup # Roda o assistente de setup completo (configura tudo de uma vez) +hermes claw migrate # Migra do OpenClaw (se estiver vindo do OpenClaw) +hermes update # Atualiza para a versão mais recente +hermes doctor # Diagnostica problemas +``` + +📖 **[Documentação completa →](https://hermes-agent.nousresearch.com/docs/)** + +## Referência rápida: CLI x Mensagens + +O Hermes tem dois pontos de entrada: inicie a UI do terminal com `hermes`, ou rode o gateway e fale com ele pelo Telegram, Discord, Slack, WhatsApp, Signal ou Email. Uma vez dentro da conversa, muitos slash commands funcionam igual nas duas interfaces. + +| Ação | CLI | Plataformas de mensagem | +|---------|-----|---------------------| +| Começar a conversar | `hermes` | Rode `hermes gateway setup` + `hermes gateway start`, depois mande mensagem para o bot | +| Iniciar conversa nova | `/new` ou `/reset` | `/new` ou `/reset` | +| Trocar modelo | `/model [provider:model]` | `/model [provider:model]` | +| Definir personalidade | `/personality [name]` | `/personality [name]` | +| Refazer ou desfazer último turno | `/retry`, `/undo` | `/retry`, `/undo` | +| Comprimir contexto / ver uso | `/compress`, `/usage`, `/insights [--days N]` | `/compress`, `/usage`, `/insights [days]` | +| Listar habilidades | `/skills` ou `/` | `/` | +| Interromper trabalho atual | `Ctrl+C` ou enviar nova mensagem | `/stop` ou enviar nova mensagem | +| Status específico da plataforma | `/platforms` | `/status`, `/sethome` | + +Para a lista completa de comandos, veja o [guia do CLI](https://hermes-agent.nousresearch.com/docs/user-guide/cli) e o [guia do Gateway de Mensagens](https://hermes-agent.nousresearch.com/docs/user-guide/messaging). + +--- + +## Documentação + +Toda a documentação fica em **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)**: + +| Seção | O que cobre | +|---------|---------------| +| [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) | Instalar → configurar → primeira conversa em 2 minutos | +| [Uso do CLI](https://hermes-agent.nousresearch.com/docs/user-guide/cli) | Comandos, atalhos de teclado, personalidades, sessões | +| [Configuração](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) | Arquivo de config, provedores, modelos, todas as opções | +| [Gateway de Mensagens](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant | +| [Segurança](https://hermes-agent.nousresearch.com/docs/user-guide/security) | Aprovação de comandos, pareamento via DM, isolamento por container | +| [Ferramentas e Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) | 40+ ferramentas, sistema de toolsets, backends de terminal | +| [Sistema de Habilidades](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) | Memória procedural, Skills Hub, criação de habilidades | +| [Memória](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) | Memória persistente, perfis de usuário, boas práticas | +| [Integração MCP](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | Conecte qualquer servidor MCP para ampliar capacidades | +| [Agendamento Cron](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) | Tarefas agendadas com entrega entre plataformas | +| [Arquivos de Contexto](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) | Contexto de projeto que molda cada conversa | +| [Arquitetura](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) | Estrutura do projeto, loop do agente, classes principais | +| [Contribuir](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) | Setup de dev, processo de PR, estilo de código | +| [Referência do CLI](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) | Todos os comandos e flags | +| [Variáveis de Ambiente](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | Referência completa de variáveis de ambiente | + +--- + +## Migração do OpenClaw + +Se você está vindo do OpenClaw, o Hermes pode importar automaticamente suas configurações, memórias, habilidades e chaves de API. + +**Durante o setup inicial:** O assistente de setup (`hermes setup`) detecta `~/.openclaw` automaticamente e oferece migrar antes da configuração começar. + +**A qualquer momento depois da instalação:** + +```bash +hermes claw migrate # Migração interativa (preset completo) +hermes claw migrate --dry-run # Visualiza o que seria migrado +hermes claw migrate --preset user-data # Migra sem segredos +hermes claw migrate --overwrite # Sobrescreve conflitos existentes +``` + +O que é importado: +- **SOUL.md** — arquivo de persona +- **Memórias** — entradas de MEMORY.md e USER.md +- **Habilidades** — habilidades criadas pelo usuário → `~/.hermes/skills/openclaw-imports/` +- **Allowlist de comandos** — padrões de aprovação +- **Configurações de mensagem** — configs por plataforma, usuários permitidos, diretório de trabalho +- **Chaves de API** — segredos da allowlist (Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs) +- **Assets de TTS** — arquivos de áudio do workspace +- **Instruções de workspace** — AGENTS.md (com `--workspace-target`) + +Veja `hermes claw migrate --help` para todas as opções, ou use a habilidade `openclaw-migration` para uma migração guiada por agente em modo interativo, com prévia em dry-run. + +--- + +## Contribuir + +Contribuições são bem-vindas! Veja o [Guia de Contribuição](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) para setup de desenvolvimento, estilo de código e processo de PR. + +Início rápido para quem vai contribuir — clone e siga com `setup-hermes.sh`: + +```bash +git clone https://github.com/NousResearch/hermes-agent.git +cd hermes-agent +./setup-hermes.sh # instala uv, cria venv, instala .[all], cria symlink ~/.local/bin/hermes +./hermes # detecta o venv automaticamente, sem precisar `source` +``` + +Caminho manual (equivalente ao acima): + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +uv venv .venv --python 3.11 +source .venv/bin/activate +uv pip install -e ".[all,dev]" +scripts/run_tests.sh +``` + +> **Treinamento RL (opcional):** Para a integração com RL/Atropos (`environments/`) — veja [`CONTRIBUTING.md`](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#development-setup) para o setup completo. + +--- + +## Comunidade + +- 💬 [Discord](https://discord.gg/NousResearch) +- 📚 [Skills Hub](https://agentskills.io) +- 🐛 [Issues](https://github.com/NousResearch/hermes-agent/issues) +- 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — Bridge comunitário para WeChat: rode Hermes Agent e OpenClaw na mesma conta de WeChat. + +--- + +## Licença + +MIT — veja [LICENSE](LICENSE). + +Feito pela [Nous Research](https://nousresearch.com). diff --git a/README.zh-CN.md b/README.zh-CN.md index ea7fea8dcce0..8329b74e9d48 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -10,6 +10,7 @@ License: MIT Built by Nous Research English + Português (Brasil)

**由 [Nous Research](https://nousresearch.com) 构建的自进化 AI 代理。** 它是唯一内置学习闭环的智能代理——从经验中创建技能，在使用中改进技能，主动持久化知识，搜索过往对话，并在跨会话中逐步构建对你的深度理解。可以在 $5 的 VPS 上运行，也可以在 GPU 集群上运行，或者使用几乎零成本的 Serverless 基础设施。它不绑定你的笔记本——你可以在 Telegram 上与它对话，而它在云端 VM 上工作。 diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 6d6904d6cbfa..5b12a8c86ba7 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -24,7 +24,7 @@ const config: Config = { i18n: { defaultLocale: 'en', - locales: ['en', 'zh-Hans'], + locales: ['en', 'zh-Hans', 'pt-BR'], localeConfigs: { en: { label: 'English', @@ -33,6 +33,10 @@ const config: Config = { label: '简体中文', htmlLang: 'zh-Hans', }, + 'pt-BR': { + label: 'Português (Brasil)', + htmlLang: 'pt-BR', + }, }, }, diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-guide/features/image-generation.md b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-guide/features/image-generation.md new file mode 100644 index 000000000000..e67cbfaf0578 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-guide/features/image-generation.md @@ -0,0 +1,156 @@ +--- +title: Geração de Imagens +description: Gere imagens via FAL.ai — 9 modelos incluindo FLUX 2, GPT Image (1.5 e 2), Nano Banana Pro, Ideogram, Recraft V4 Pro e mais, selecionáveis em `hermes tools`. +sidebar_label: Geração de Imagens +sidebar_position: 6 +--- + +# Geração de Imagens + +O Hermes Agent gera imagens a partir de prompts de texto via FAL.ai. Nove modelos são suportados de fábrica, cada um com diferentes trade-offs de velocidade, qualidade e custo. O modelo ativo é configurável pelo usuário via `hermes tools` e fica persistido em `config.yaml`. + +## Modelos Suportados + +| Modelo | Velocidade | Pontos fortes | Preço | +|---|---|---|---| +| `fal-ai/flux-2/klein/9b` *(padrão)* | `<1s` | Rápido, texto nítido | $0,006/MP | +| `fal-ai/flux-2-pro` | ~6s | Fotorrealismo de estúdio | $0,03/MP | +| `fal-ai/z-image/turbo` | ~2s | Bilíngue EN/CN, 6B parâmetros | $0,005/MP | +| `fal-ai/nano-banana-pro` | ~8s | Gemini 3 Pro, raciocínio profundo, renderização de texto | $0,15/imagem (1K) | +| `fal-ai/gpt-image-1.5` | ~15s | Aderência ao prompt | $0,034/imagem | +| `fal-ai/gpt-image-2` | ~20s | Renderização de texto SOTA + CJK, fotorrealismo com noção de mundo | $0,04–0,06/imagem | +| `fal-ai/ideogram/v3` | ~5s | Melhor tipografia | $0,03–0,09/imagem | +| `fal-ai/recraft/v4/pro/text-to-image` | ~8s | Design, sistemas de marca, pronto pra produção | $0,25/imagem | +| `fal-ai/qwen-image` | ~12s | Baseado em LLM, texto complexo | $0,02/MP | + +Os preços são da FAL no momento desta escrita; consulte [fal.ai](https://fal.ai/) para os valores atuais. + +## Setup + +:::tip Assinantes Nous +Se você tem uma assinatura paga do [Nous Portal](https://portal.nousresearch.com), pode usar geração de imagens pelo **[Tool Gateway](tool-gateway.md)** sem chave de API da FAL. Sua escolha de modelo persiste nos dois caminhos. + +Se o gateway gerenciado retornar `HTTP 4xx` para um modelo específico, esse modelo ainda não está sendo proxiado pelo lado do portal — o agente vai te avisar, com passos de remediação (defina `FAL_KEY` para acesso direto, ou escolha outro modelo). +::: + +### Obtenha uma chave de API da FAL + +1. Cadastre-se em [fal.ai](https://fal.ai/) +2. Gere uma chave de API no seu dashboard + +### Configure e escolha um modelo + +Rode o comando de tools: + +```bash +hermes tools +``` + +Navegue até **🎨 Image Generation**, escolha seu backend (Nous Subscription ou FAL.ai) e o seletor mostra todos os modelos suportados numa tabela alinhada por colunas — setas pra navegar, Enter pra selecionar: + +``` + Modelo Velocidade Pontos fortes Preço + fal-ai/flux-2/klein/9b <1s Rápido, texto nítido $0,006/MP ← em uso + fal-ai/flux-2-pro ~6s Fotorrealismo de estúdio $0,03/MP + fal-ai/z-image/turbo ~2s Bilíngue EN/CN, 6B $0,005/MP + ... +``` + +Sua seleção é salva em `config.yaml`: + +```yaml +image_gen: + model: fal-ai/flux-2/klein/9b + use_gateway: false # true se estiver usando Nous Subscription +``` + +### Qualidade do GPT-Image + +A qualidade da requisição em `fal-ai/gpt-image-1.5` e `fal-ai/gpt-image-2` está fixada em `medium` (~$0,034–$0,06/imagem em 1024×1024). Não expomos os tiers `low` / `high` como opção visível ao usuário pra que o billing do Nous Portal fique previsível pra todo mundo — a diferença de custo entre tiers é de 3–22×. Se quiser uma opção mais barata, escolha Klein 9B ou Z-Image Turbo; se quiser maior qualidade, use Nano Banana Pro ou Recraft V4 Pro. + +## Uso + +O schema voltado pro agente é intencionalmente minimalista — o modelo pega o que você configurou: + +``` +Gere uma imagem de uma paisagem montanhosa serena com cerejeiras em flor +``` + +``` +Crie um retrato quadrado de uma coruja velha e sábia — use o modelo de tipografia +``` + +``` +Faz uma cidade futurista, orientação landscape +``` + +## Proporções (Aspect Ratios) + +Todo modelo aceita as mesmas três proporções da perspectiva do agente. Internamente, a especificação nativa de tamanho de cada modelo é preenchida automaticamente: + +| Entrada do agente | image_size (flux/z-image/qwen/recraft/ideogram) | aspect_ratio (nano-banana-pro) | image_size (gpt-image-1.5) | image_size (gpt-image-2) | +|---|---|---|---|---| +| `landscape` | `landscape_16_9` | `16:9` | `1536x1024` | `landscape_4_3` (1024×768) | +| `square` | `square_hd` | `1:1` | `1024x1024` | `square_hd` (1024×1024) | +| `portrait` | `portrait_16_9` | `9:16` | `1024x1536` | `portrait_4_3` (768×1024) | + +GPT Image 2 mapeia pra presets 4:3 em vez de 16:9 porque sua contagem mínima de pixels é 655.360 — o preset `landscape_16_9` (1024×576 = 589.824) seria rejeitado. + +Essa tradução acontece em `_build_fal_payload()` — o código do agente nunca precisa saber as diferenças de schema por modelo. + +## Upscaling Automático + +O upscaling via **Clarity Upscaler** da FAL é controlado por modelo: + +| Modelo | Upscale? | Por quê | +|---|---|---| +| `fal-ai/flux-2-pro` | ✓ | Compatibilidade pra trás (era o padrão antes do seletor) | +| Todos os outros | ✗ | Modelos rápidos perderiam o valor de subsegundos; modelos hi-res não precisam | + +Quando o upscaling roda, ele usa estas configurações: + +| Configuração | Valor | +|---|---| +| Fator de upscale | 2× | +| Criatividade | 0,35 | +| Resemblance | 0,6 | +| Escala de guidance | 4 | +| Passos de inferência | 18 | + +Se o upscaling falhar (problema de rede, rate limit), a imagem original é retornada automaticamente. + +## Como Funciona Internamente + +1. **Resolução do modelo** — `_resolve_fal_model()` lê `image_gen.model` do `config.yaml`, faz fallback pra variável de ambiente `FAL_IMAGE_MODEL` e depois pra `fal-ai/flux-2/klein/9b`. +2. **Construção do payload** — `_build_fal_payload()` traduz seu `aspect_ratio` pro formato nativo do modelo (preset enum, enum de aspect-ratio ou literal do GPT), mescla os parâmetros padrão do modelo, aplica overrides do chamador e depois filtra pela whitelist `supports` do modelo, então chaves não suportadas nunca são enviadas. +3. **Submissão** — `_submit_fal_request()` roteia via credenciais diretas da FAL ou pelo gateway gerenciado da Nous. +4. **Upscaling** — só roda se o metadata do modelo tiver `upscale: True`. +5. **Entrega** — URL final da imagem retornada ao agente, que emite uma tag `MEDIA:` que os adaptadores de plataforma convertem em mídia nativa. + +## Debugging + +Habilite logs de debug: + +```bash +export IMAGE_TOOLS_DEBUG=true +``` + +Os logs de debug vão pra `./logs/image_tools_debug_.json` com detalhes por chamada (modelo, parâmetros, timing, erros). + +## Entrega por Plataforma + +| Plataforma | Entrega | +|---|---| +| **CLI** | URL da imagem impressa em markdown `![](url)` — clique pra abrir | +| **Telegram** | Mensagem de foto com o prompt como legenda | +| **Discord** | Embed numa mensagem | +| **Slack** | URL desdobrada pelo Slack | +| **WhatsApp** | Mensagem de mídia | +| **Outros** | URL em texto puro | + +## Limitações + +- **Requer credenciais da FAL** (`FAL_KEY` direta ou Nous Subscription) +- **Apenas text-to-image** — sem inpainting, img2img ou edição por essa ferramenta +- **URLs temporárias** — a FAL retorna URLs hospedadas que expiram em horas/dias; salve localmente se precisar +- **Restrições por modelo** — alguns modelos não suportam `seed`, `num_inference_steps` etc. O filtro `supports` descarta silenciosamente parâmetros não suportados; isso é comportamento esperado From 99533238b55e87382a1b349d1ac7987a54b3e215 Mon Sep 17 00:00:00 2001 From: Wesley Simplicio Date: Fri, 8 May 2026 22:38:53 -0300 Subject: [PATCH 2/3] docs(i18n): translate tool-gateway.md to pt-BR Addresses Copilot review on #22178: image-generation.md (line 31) had a relative link to `tool-gateway.md` that did not resolve in the pt-BR locale. Translating tool-gateway.md fixes the link and matches the zh-Hans precedent (#20430), which translated the two docs as a pair for the same reason. Native pt-BR translation mirroring the en source structure 1:1 (matches the sibling image-generation.md style already in this PR). --- .../user-guide/features/tool-gateway.md | 176 ++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 website/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-guide/features/tool-gateway.md diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-guide/features/tool-gateway.md b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-guide/features/tool-gateway.md new file mode 100644 index 000000000000..2bd7f4a0ad9c --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-guide/features/tool-gateway.md @@ -0,0 +1,176 @@ +--- +title: "Nous Tool Gateway" +description: "Uma assinatura, todas as ferramentas. Busca web, geração de imagens, TTS e browsers em nuvem — tudo roteado pelo Nous Portal sem chaves de API extras." +sidebar_label: "Tool Gateway" +sidebar_position: 2 +--- + +# Nous Tool Gateway + +**Uma assinatura. Todas as ferramentas integradas.** + +O Tool Gateway está incluído em toda assinatura paga do [Nous Portal](https://portal.nousresearch.com). Ele roteia as chamadas de ferramentas do Hermes — busca web, geração de imagens, conversão de texto em fala e automação de browsers em nuvem — pela infraestrutura que a Nous já opera, então você não precisa se cadastrar no Firecrawl, FAL, OpenAI, Browser Use ou em qualquer outro serviço só pra deixar seu agente útil. + + + +## O que está incluído + +| | Ferramenta | O que você ganha | +|---|---|---| +| 🔍 | **Busca e extração web** | Busca web e extração de página inteira de qualidade para agentes via Firecrawl. Sem se preocupar com rate limits — o gateway cuida do escalonamento. | +| 🎨 | **Geração de imagens** | Nove modelos sob um único endpoint: **FLUX 2 Klein 9B**, **FLUX 2 Pro**, **Z-Image Turbo**, **Nano Banana Pro** (Gemini 3 Pro Image), **GPT Image 1.5**, **GPT Image 2**, **Ideogram V3**, **Recraft V4 Pro**, **Qwen Image**. Escolha por geração com uma flag, ou deixe o Hermes usar FLUX 2 Klein como padrão. | +| 🔊 | **Texto para fala** | Vozes do OpenAI TTS conectadas à ferramenta `text_to_speech`. Mande áudios pelo Telegram, gere áudio pra pipelines, narre o que quiser. | +| 🌐 | **Automação de browser em nuvem** | Sessões headless do Chromium via Browser Use. `browser_navigate`, `browser_click`, `browser_type`, `browser_vision` — todos os primitivos pra dirigir o agente, sem precisar de conta no Browserbase. | + +Os quatro são cobrados sob demanda na sua assinatura Nous. Use qualquer combinação — rode o gateway pra web e imagens enquanto mantém sua chave do ElevenLabs pra TTS, ou roteie tudo pela Nous. + +## Por que isso existe + +Construir um agente que de fato *faça coisas* significa juntar 5+ assinaturas de API — cada uma com seu próprio cadastro, rate limits, cobrança e particularidades. O gateway colapsa isso numa única conta: + +- **Uma fatura.** Pague à Nous; nós cuidamos do resto. +- **Um cadastro.** Sem contas no Firecrawl, FAL, Browser Use ou OpenAI audio pra gerenciar. +- **Uma chave.** Seu OAuth do Nous Portal cobre todas as ferramentas. +- **Mesma qualidade.** Os mesmos backends usados pelo caminho de chave direta — só que com a Nous na frente. + +Traga suas próprias chaves quando quiser — por ferramenta, a qualquer momento. O gateway não é lock-in, é atalho. + +## Comece a usar + +```bash +hermes model # Escolha Nous Portal como provider +``` + +Ao selecionar o Nous Portal, o Hermes oferece ativar o Tool Gateway. Aceite, e pronto — toda ferramenta suportada fica viva na próxima execução. + +Confira o que está ativo a qualquer momento: + +```bash +hermes status +``` + +Você verá uma seção como: + +``` +◆ Nous Tool Gateway + Nous Portal ✓ managed tools available + Web tools ✓ active via Nous subscription + Image gen ✓ active via Nous subscription + TTS ✓ active via Nous subscription + Browser ○ active via Browser Use key +``` + +Ferramentas marcadas com "active via Nous subscription" estão indo pelo gateway. Qualquer outra está usando suas próprias chaves. + +## Elegibilidade + +O Tool Gateway é um recurso **de assinatura paga**. Contas Nous gratuitas podem usar o Portal pra inferência mas não incluem ferramentas gerenciadas — [faça upgrade do plano](https://portal.nousresearch.com/manage-subscription) pra desbloquear o gateway. + +## Misture e combine + +O gateway é por ferramenta. Ative só pra o que você quer: + +- **Tudo via Nous** — mais fácil; uma assinatura, e acabou. +- **Gateway pra web + imagens, TTS próprio** — mantenha sua voz do ElevenLabs, deixe a Nous cuidar do resto. +- **Gateway só pra coisas que você não tem chave** — "já pago Browserbase, mas não quero conta no Firecrawl" funciona perfeitamente. + +Troque qualquer ferramenta a qualquer momento via: + +```bash +hermes tools # Seletor interativo por categoria de ferramenta +``` + +Selecione a ferramenta, escolha **Nous Subscription** como provider (ou qualquer provider direto que preferir). Sem editar config na mão. + +## Usando modelos individuais de imagem + +A geração de imagens usa FLUX 2 Klein 9B como padrão, por velocidade. Sobrescreva por chamada passando o ID do modelo pra ferramenta `image_generate`: + +| Modelo | ID | Melhor pra | +|---|---|---| +| FLUX 2 Klein 9B | `fal-ai/flux-2/klein/9b` | Rápido, bom padrão | +| FLUX 2 Pro | `fal-ai/flux-2/pro` | FLUX de fidelidade maior | +| Z-Image Turbo | `fal-ai/z-image/turbo` | Estilizado, rápido | +| Nano Banana Pro | `fal-ai/gemini-3-pro-image` | Google Gemini 3 Pro Image | +| GPT Image 1.5 | `fal-ai/gpt-image-1/5` | Geração de imagem da OpenAI, texto+imagem | +| GPT Image 2 | `fal-ai/gpt-image-2` | OpenAI mais recente | +| Ideogram V3 | `fal-ai/ideogram/v3` | Boa aderência a prompt + tipografia | +| Recraft V4 Pro | `fal-ai/recraft/v4/pro` | Estilo vetorial, design gráfico | +| Qwen Image | `fal-ai/qwen-image` | Multimodal da Alibaba | + +O conjunto evolui — `hermes tools` → Image Generation mostra a lista atual ao vivo. + +--- + +## Referência de configuração + +A maioria dos usuários nunca precisa mexer aqui — `hermes model` e `hermes tools` cobrem todo workflow de forma interativa. Esta seção é pra quem edita `config.yaml` direto ou roteiriza setups. + +### Flag `use_gateway` por ferramenta + +O bloco de config de cada ferramenta aceita um booleano `use_gateway`: + +```yaml +web: + backend: firecrawl + use_gateway: true + +image_gen: + use_gateway: true + +tts: + provider: openai + use_gateway: true + +browser: + cloud_provider: browser-use + use_gateway: true +``` + +Precedência: `use_gateway: true` roteia pela Nous independentemente de chaves diretas no `.env`. `use_gateway: false` (ou ausente) usa chaves diretas se disponíveis e só faz fallback pro gateway quando nenhuma existe. + +### Desativando o gateway + +```yaml +web: + use_gateway: false # Hermes agora usa FIRECRAWL_API_KEY do .env +``` + +`hermes tools` limpa a flag automaticamente quando você escolhe um provider que não é o gateway, então isso geralmente acontece sozinho. + +### Gateway self-hosted (avançado) + +Rodando seu próprio gateway compatível com a Nous? Sobrescreva os endpoints em `~/.hermes/.env`: + +```bash +TOOL_GATEWAY_DOMAIN=seu-dominio.exemplo.com +TOOL_GATEWAY_SCHEME=https +TOOL_GATEWAY_USER_TOKEN=seu-token # normalmente preenchido automaticamente pelo login do Portal +FIRECRAWL_GATEWAY_URL=https://... # sobrescrever um endpoint específico +``` + +Esses parâmetros existem pra setups de infraestrutura customizada (deploys enterprise, ambientes de dev). Assinantes regulares nunca precisam definir. + +## FAQ + +### Funciona com Telegram / Discord / outros gateways de mensagem? + +Sim. O Tool Gateway opera na camada de execução de ferramentas, não no CLI. Toda interface que pode chamar uma ferramenta — CLI, Telegram, Discord, Slack, IRC, Teams, o servidor de API, qualquer coisa — se beneficia dele de forma transparente. + +### O que acontece se minha assinatura expirar? + +Ferramentas roteadas pelo gateway param de funcionar até você renovar ou trocar por chaves de API diretas via `hermes tools`. O Hermes mostra um erro claro apontando pro portal. + +### Dá pra ver uso ou custos por ferramenta? + +Sim — o [dashboard do Nous Portal](https://portal.nousresearch.com) quebra o uso por ferramenta pra você ver o que está pesando na sua conta. + +### O Modal (terminal serverless) está incluído? + +O Modal está disponível como **add-on opcional** da assinatura Nous, não faz parte do bundle padrão do Tool Gateway. Configure via `hermes setup terminal` ou direto no `config.yaml` quando quiser uma sandbox remota pra execução de shell. + +### Preciso apagar minhas chaves de API existentes ao ativar o gateway? + +Não — mantenha elas no `.env`. Quando `use_gateway: true`, o Hermes ignora chaves diretas e usa o gateway. Volta a flag pra `false` e suas chaves voltam a ser a fonte. O gateway não é lock-in. From 646b3dac3ddade2397606dee28c0bf2aff67614d Mon Sep 17 00:00:00 2001 From: Wesley Simplicio Date: Sat, 9 May 2026 12:29:13 -0300 Subject: [PATCH 3/3] security: block cloud provider credentials and git credential prompts in subprocesses (salvage of #7990) Cloud provider credentials (AWS, Azure, GCP, KUBECONFIG, Docker TLS, NPM/PyPI tokens, SSH agent socket, GPG agent) were not in the subprocess env blocklist, allowing agent-spawned commands to silently access cloud infrastructure. GIT_TERMINAL_PROMPT was not forced to 0, allowing git to prompt for credentials inside subprocesses and potentially blocking execution or leaking timing info. Changes: - _build_provider_env_blocklist(): add 14 cloud/infra credential vars (AWS_ACCESS_KEY_ID/SECRET/SESSION/SECURITY, AZURE_CLIENT_SECRET/ID/TENANT, GOOGLE_APPLICATION_CREDENTIALS, KUBECONFIG, DOCKER_HOST/CERT_PATH, NPM_TOKEN, PYPI_TOKEN, SSH_AUTH_SOCK, GPG_AGENT_INFO) - Add _GIT_HARDENING_VARS = {'GIT_TERMINAL_PROMPT': '0'} - Apply _GIT_HARDENING_VARS in both _make_run_env() (execute path) and _sanitize_subprocess_env() (subprocess delegation path) New tests in TestCloudCredentialBlocklist and TestGitHardeningVars verify blocking and hardening via the existing _run_with_env() test harness. Salvage of abandoned PR NousResearch/hermes-agent#7990 (27 days stale). Stash-verify: 6 tests fail without fix, all 24 pass with it. --- tests/tools/test_local_env_blocklist.py | 67 +++++++++++++++++++++++++ tools/environments/local.py | 26 ++++++++++ 2 files changed, 93 insertions(+) diff --git a/tests/tools/test_local_env_blocklist.py b/tests/tools/test_local_env_blocklist.py index e3e7c310c5e3..898e93d1f713 100644 --- a/tests/tools/test_local_env_blocklist.py +++ b/tests/tools/test_local_env_blocklist.py @@ -299,6 +299,73 @@ def test_gateway_runtime_vars_are_in_blocklist(self): assert extras.issubset(_HERMES_PROVIDER_ENV_BLOCKLIST) +class TestCloudCredentialBlocklist: + """Cloud provider credentials must not leak into subprocess env.""" + + def test_aws_credentials_blocked(self): + aws_vars = { + "AWS_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE", + "AWS_SECRET_ACCESS_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", + "AWS_SESSION_TOKEN": "session-token-value", + "AWS_SECURITY_TOKEN": "security-token-value", + } + result_env = _run_with_env(extra_os_env=aws_vars) + for var in aws_vars: + assert var not in result_env, f"{var} leaked into subprocess env" + + def test_azure_credentials_blocked(self): + azure_vars = { + "AZURE_CLIENT_SECRET": "azure-secret", + "AZURE_CLIENT_ID": "azure-client-id", + "AZURE_TENANT_ID": "azure-tenant-id", + } + result_env = _run_with_env(extra_os_env=azure_vars) + for var in azure_vars: + assert var not in result_env, f"{var} leaked into subprocess env" + + def test_gcp_and_infra_credentials_blocked(self): + infra_vars = { + "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json", + "KUBECONFIG": "/home/user/.kube/config", + "DOCKER_HOST": "tcp://localhost:2376", + "DOCKER_CERT_PATH": "/home/user/.docker/certs", + "NPM_TOKEN": "npm_token_value", + "PYPI_TOKEN": "pypi-token-value", + "SSH_AUTH_SOCK": "/run/user/1000/ssh-agent.socket", + "GPG_AGENT_INFO": "/run/user/1000/gnupg/S.gpg-agent:0:1", + } + result_env = _run_with_env(extra_os_env=infra_vars) + for var in infra_vars: + assert var not in result_env, f"{var} leaked into subprocess env" + + def test_cloud_creds_in_blocklist_constant(self): + cloud_vars = { + "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", + "AWS_SESSION_TOKEN", "AWS_SECURITY_TOKEN", + "AZURE_CLIENT_SECRET", "AZURE_CLIENT_ID", "AZURE_TENANT_ID", + "GOOGLE_APPLICATION_CREDENTIALS", "KUBECONFIG", + "DOCKER_HOST", "DOCKER_CERT_PATH", + "NPM_TOKEN", "PYPI_TOKEN", + "SSH_AUTH_SOCK", "GPG_AGENT_INFO", + } + assert cloud_vars.issubset(_HERMES_PROVIDER_ENV_BLOCKLIST) + + +class TestGitHardeningVars: + """GIT_TERMINAL_PROMPT must be set to 0 in all subprocess envs.""" + + def test_git_terminal_prompt_set_to_zero(self): + result_env = _run_with_env() + assert result_env.get("GIT_TERMINAL_PROMPT") == "0", ( + "GIT_TERMINAL_PROMPT must be '0' to disable git credential prompts" + ) + + def test_git_terminal_prompt_not_overrideable_from_os(self): + """User env GIT_TERMINAL_PROMPT=1 must be overridden by hardening.""" + result_env = _run_with_env(extra_os_env={"GIT_TERMINAL_PROMPT": "1"}) + assert result_env.get("GIT_TERMINAL_PROMPT") == "0" + + class TestSanePathIncludesHomebrew: """Verify _SANE_PATH includes macOS Homebrew directories.""" diff --git a/tools/environments/local.py b/tools/environments/local.py index 985bf4bdce87..a80b844ed38c 100644 --- a/tools/environments/local.py +++ b/tools/environments/local.py @@ -133,6 +133,22 @@ def _build_provider_env_blocklist() -> frozenset: "MODAL_TOKEN_ID", "MODAL_TOKEN_SECRET", "DAYTONA_API_KEY", + # Cloud provider credentials + "AWS_ACCESS_KEY_ID", + "AWS_SECRET_ACCESS_KEY", + "AWS_SESSION_TOKEN", + "AWS_SECURITY_TOKEN", + "AZURE_CLIENT_SECRET", + "AZURE_CLIENT_ID", + "AZURE_TENANT_ID", + "GOOGLE_APPLICATION_CREDENTIALS", + "KUBECONFIG", + "DOCKER_HOST", + "DOCKER_CERT_PATH", + "NPM_TOKEN", + "PYPI_TOKEN", + "SSH_AUTH_SOCK", + "GPG_AGENT_INFO", "VERCEL_OIDC_TOKEN", "VERCEL_TOKEN", "VERCEL_PROJECT_ID", @@ -144,6 +160,12 @@ def _build_provider_env_blocklist() -> frozenset: _HERMES_PROVIDER_ENV_BLOCKLIST = _build_provider_env_blocklist() +# Git hardening: disable credential prompts in all subprocesses. +_GIT_HARDENING_VARS = { + "GIT_TERMINAL_PROMPT": "0", +} + + def _sanitize_subprocess_env(base_env: dict | None, extra_env: dict | None = None) -> dict: """Filter Hermes-managed secrets from a subprocess environment.""" try: @@ -172,6 +194,8 @@ def _sanitize_subprocess_env(base_env: dict | None, extra_env: dict | None = Non if _profile_home: sanitized["HOME"] = _profile_home + # Apply git hardening: disable credential prompts in subprocesses + sanitized.update(_GIT_HARDENING_VARS) return sanitized @@ -274,6 +298,8 @@ def _make_run_env(env: dict) -> dict: if _profile_home: run_env["HOME"] = _profile_home + # Apply git hardening: disable credential prompts in subprocesses + run_env.update(_GIT_HARDENING_VARS) return run_env