chatgraph 1.3.1__tar.gz → 1.4.0__tar.gz

{chatgraph-1.3.1 → chatgraph-1.4.0}/.env.example

@@ -36,6 +36,30 @@ ROUTER_API_PASSWORD=f078b1cf-b4c8-11f0-b4fe-0242ac140002
 TEST_USER_ID=6107
 TEST_COMPANY_ID=business-tech
 
+# ====================================
+# Agentes de IA (extra opcional: pip install chatgraph[agent])
+# ====================================
+# OpenRouter (provedor de LLM)
+OPENROUTER_API_KEY=sk-or-...
+# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1  # opcional
+
+# Modelo usado pelo Agent (qualquer modelo do OpenRouter)
+AGENT_MODEL=openai/gpt-4o-mini
+# AGENT_TEMPERATURE=0.7        # opcional (default 0.7)
+# AGENT_MAX_TOKENS=2048        # opcional (default 2048)
+# AGENT_MAX_TOOL_LOOPS=5       # opcional (default 5)
+# AGENT_HISTORY_LIMIT=20       # opcional (default 20)
+# AGENT_SYSTEM_PROMPT_FILE=prompts/personalidade.md  # opcional
+
+# Diagnóstico: loga o AgentContext COMPLETO (inclui dados do usuário
+# na observation). Use apenas em debug local.
+# LOG_AGENT_CONTEXT=1
+
+# Bots com agente: um turno de LLM pode levar vários segundos; com
+# RABBIT_PREFETCH=1 o consumer processa 1 mensagem por vez e a fila
+# serializa. Considere aumentar (com o caveat de ordenação por chat).
+# RABBIT_PREFETCH=4
+
 # Log Publisher (RabbitMQ - opcional)
 # Defina LOG_RABBIT_QUEUE para ativar o envio de logs de erro para fila RabbitMQ.
 # O exchange e routing key padrão seguem o padrão do Go: exchange = vhost, routing key = chatbot.{queue}

{chatgraph-1.3.1 → chatgraph-1.4.0}/.github/skills/chatgraph-framework/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chatgraph-framework
-description: "Use when: implementing a chatbot with chatgraph, creating routes with @app.route or @router.route, using UserCall, Route, Message, File, Button, EndChatResponse, RedirectResponse, TransferToMenu, TransferToHuman, BackgroundTask, setting up ChatbotApp, ChatbotRouter, include_router, configuring RabbitMQ consumer, adding per-user file logging with UserLoggerManager, integrating chatgraph in a new Python project."
+description: "Use when: implementing a chatbot with chatgraph, creating routes with @app.route or @router.route, using UserCall, Route, Message, File, Button, EndChatResponse, RedirectResponse, TransferToMenu, BackgroundTask, setting up ChatbotApp, ChatbotRouter, include_router, configuring RabbitMQ consumer, adding per-user file logging with UserLoggerManager, integrating chatgraph in a new Python project."
 argument-hint: "Descreva o fluxo de rotas que deseja implementar (opcional)"
 ---
 
@@ -200,22 +200,28 @@ return RedirectResponse('choice_start')
 return Route('aguardando_resposta')
 ```
 
-### `EndChatResponse(end_chat_id, end_chat_name?, observations?)` — Encerra o chat
+### `EndChatResponse(end_chat_id, end_chat_name?, observations?)` — Encerra o chat OU transfere para humano
+No chatbot-router, encerrar o atendimento e transferir para um atendente humano são a
+**mesma operação**: uma tabulação de encerramento com ID/nome próprio. Não existe um tipo de
+retorno separado para "transferir para humano" — use `EndChatResponse` com a end action de
+atendimento humano configurada no router.
 ```python
 return EndChatResponse('voll_ended')
 return EndChatResponse('', end_chat_name='Encerrado pelo usuário', observations='motivo')
+return EndChatResponse('ea_atendimento_humano')  # transferência para humano é um end_chat_id específico
 ```
 
-### `TransferToMenu(menu, user_message, route?)` — Transfere para outro menu
+### `TransferToMenu(menu, user_message, route?)` — Transfere para OUTRO BOT (menu)
+`TransferToMenu` é só bot→bot (outro menu/robô configurado no router). **Nunca** use para chegar a
+um atendente humano — isso é `EndChatResponse` (ver acima). Confundir os dois faz o handler prometer
+uma transferência que o router rejeita, porque o "menu" de atendimento humano não existe como menu.
 ```python
 return TransferToMenu('p0299_suporte_ti', 'Transferindo...')
 return TransferToMenu('p0299_suporte_ti', 'Transferindo...', route='etapa_inicial')  # inicia em rota específica
 ```
 
-### `TransferToHuman(campaign_id?, campaign_name?, observations?)` — Transfere para humano
-```python
-return TransferToHuman(campaign_name='Suporte N2')
-```
+> `TransferToHuman` (`chatgraph.types.end_types`) é **obsoleto**: não tem efeito no pipeline HTTP
+> (só existia no caminho gRPC legado). Não é mais exportado por `chatgraph/__init__.py`.
 
 ### `BackgroundTask(async_func, *args, **kwargs)` — Executa tarefa em background e encadeia o retorno
 ```python
@@ -526,3 +532,191 @@ async def aguardar_escolha(usercall: UserCall):
 
 app.start()
 ```
+
+## 14. Agentes de IA (`chatgraph.agent`)
+
+Requer o extra opcional: `pip install chatgraph[agent]` (pydantic>=2).
+Port do protocolo single-agent do `chatgraph-go`: uma chamada de LLM
+decide navegação E escreve a resposta, com tool calling declarativo.
+
+### Conceitos
+
+- **`Agent`**: configura LLM client, modelo, prompt de personalidade,
+  tools locais, menus, end actions e o modelo pydantic da observation.
+- **`description` da rota é o prompt de comportamento** daquela rota —
+  injetada no system prompt do protocolo. `ai_visible=True` expõe a
+  rota ao roteamento do agente.
+- **Tools locais** (`@agent.tool`): o modelo as chama via ação
+  `call_tool`; o resultado entra na observation sob `result_key` e o
+  agente decide de novo (até `max_tool_loops`, default 5).
+- **Ações do protocolo** mapeiam nos tipos de retorno existentes:
+  `send_message`→`Message`, `next_route`→`Route`,
+  `redirect`→`RedirectResponse`, `set_observation`→merge aditivo na
+  observation.
+- **`end_session`→`EndChatResponse`** cobre TANTO encerrar o
+  atendimento QUANTO transferir para um atendente humano — no
+  chatbot-router as duas são a mesma operação (uma tabulação de
+  encerramento). Seleção por **name** do `EndActionInfo` configurado
+  em `Agent(end_actions=[...])`.
+- **`transfer_menu`→`TransferToMenu`** é só bot→bot (seleção por
+  **name** do `MenuInfo`). **Nunca** configure um menu para representar
+  "atendimento humano" — isso pertence a `end_actions`/`end_session`.
+  Confundir os dois faz o agente prometer uma transferência que o
+  router rejeita (o "menu" de humano não existe como menu).
+- **Histórico**: com `history_store` configurado no `ChatbotApp`, o
+  agente recebe a conversa (janela `history_limit`, default 20) com o
+  pareamento assistant/tool preservado.
+- **Ação inválida do modelo** (menu/end_action_id que não existe na
+  lista configurada) dispara um re-prompt corretivo automático (1
+  tentativa por turno, via `AgentContext.last_action_error`); se a
+  correção também falhar, o turno termina com uma mensagem neutra em
+  vez de silêncio ou uma promessa que não vai se cumprir.
+
+### Env vars
+
+```
+OPENROUTER_API_KEY=sk-or-...   # obrigatória p/ OpenRouterClient
+OPENROUTER_BASE_URL=...        # opcional
+AGENT_MODEL=openai/gpt-4o-mini # obrigatória p/ Agent.load_dotenv
+AGENT_TEMPERATURE / AGENT_MAX_TOKENS / AGENT_MAX_TOOL_LOOPS /
+AGENT_HISTORY_LIMIT / AGENT_SYSTEM_PROMPT_FILE   # opcionais
+LOG_AGENT_CONTEXT=1            # debug: loga contexto completo (PII!)
+```
+
+### Exemplo
+
+```python
+from pydantic import BaseModel
+from chatgraph import (
+    Agent, ChatbotApp, EndActionInfo, MenuInfo, OpenRouterClient, Route,
+    UserCall,
+)
+from chatgraph.history.store import MemoryHistoryStore
+
+
+class PedidoObs(BaseModel):
+    cpf: str = ''
+    numero_pedido: str = ''
+
+
+agent = Agent(
+    llm_client=OpenRouterClient.load_dotenv(),
+    model='openai/gpt-4o-mini',
+    system_prompt='Você é o assistente da loja. Responda em pt-BR.',
+    observation_model=PedidoObs,
+    # transfer_menu: só bot→bot (outro robô configurado no router).
+    menus=[MenuInfo(name='suporte_ti', description='Bot de suporte técnico.')],
+    # end_session: encerrar OU transferir para atendente humano — NÃO
+    # é um menu. "id" é opcional (o seletor por name já basta).
+    end_actions=[
+        EndActionInfo(name='humano', description='Atendente humano.'),
+        EndActionInfo(name='resolvido', description='Atendimento concluído.'),
+    ],
+)
+
+# Opcional, no boot do bot (fora do caminho de mensagem): confirma que
+# os menus/end_actions acima existem de verdade no chatbot-router,
+# falhando cedo em vez de só na primeira transferência de um usuário.
+# await agent.validate_config(router_client)
+
+
+@agent.tool(
+    description='Consulta pedido por CPF e número.',
+    parameters={
+        'type': 'object',
+        'properties': {
+            'cpf': {'type': 'string'},
+            'numero_pedido': {'type': 'string'},
+        },
+        'required': ['cpf', 'numero_pedido'],
+    },
+)
+async def consultar_pedido(cpf: str, numero_pedido: str) -> dict:
+    return {'status': 'Entregue'}
+
+
+app = ChatbotApp(history_store=MemoryHistoryStore())
+
+
+@app.route(
+    'buscar_pedido',
+    description="Order lookup — collect cpf and numero_pedido. Call "
+        "consultar_pedido with result_key='dados_pedido', then "
+        'redirect to exibir_pedido.',
+    ai_visible=True,
+)
+async def buscar_pedido(call: UserCall, route: Route):
+    return await agent.execute(call, route)
+```
+
+### Regras e cuidados
+
+- Handlers com agente devem ser `async` (sync roda em thread e não
+  pode `await`).
+- Um turno de agente pode levar vários segundos (até `max_tool_loops`
+  chamadas de LLM). Com `RABBIT_PREFETCH=1` a fila serializa —
+  considere aumentar o prefetch para bots com agente.
+- Redirects têm limite global (`MAX_REDIRECT_DEPTH=5` em
+  `chatbot_model.py`): um agente que redirecionar em ciclo é
+  interrompido com erro no log.
+- `await agent.validate_config(router_client)` é opcional e não é
+  chamado automaticamente — confere no boot se os `menus`/`end_actions`
+  configurados existem de verdade no chatbot-router. Chame fora do
+  caminho de mensagem (uma vez, ao subir o bot).
+- Proteções do executor (port do Go): dedup de tool por `result_key`,
+  máx. 2 tentativas por tool com degradação, self-redirect vira
+  "none", alvo de rota desconhecido vira "none" com warning, redirect
+  é silencioso (a rota destino responde), transfer inválido falha
+  ANTES de qualquer side effect.
+- Exemplo completo: `examples/agents_bot.py`.
+
+## 15. Geração de conteúdo desacoplada (`generate_content`)
+
+Requer o mesmo extra opcional: `pip install chatgraph[agent]`.
+
+**Para dados internos do bot, não para turno de chat.** Caso de uso:
+o bot tem acesso a uma base interna (ex.: uma consulta a banco) e
+precisa que a IA analise esse conteúdo e devolva um insight — não é
+uma mensagem de cliente, não tem rota, não tem menu, não passa por
+`UserCall`/`Route`/`AgentContext`. `generate_content` é uma função
+solta, independente de `Agent`: funciona com qualquer `LLMClient`
+(inclusive `OpenRouterClient` já existente), sem exigir menus, tools,
+observation_model ou histórico de conversa configurados.
+
+```python
+import json
+
+from pydantic import BaseModel
+from chatgraph import OpenRouterClient, generate_content
+
+
+class VendasInsight(BaseModel):
+    resumo: str
+    tendencia: str
+    produtos_em_alerta: list[str] = []
+
+
+async def gerar_relatorio(dados_do_banco: list[dict]) -> VendasInsight | None:
+    result = await generate_content(
+        OpenRouterClient.load_dotenv(),
+        model='openai/gpt-4o-mini',
+        content=json.dumps(dados_do_banco, ensure_ascii=False),
+        system_prompt='Você é um analista de vendas. Responda em pt-BR.',
+        response_model=VendasInsight,  # opcional; sem ele, result.data é None
+    )
+    return result.data  # ou result.text, se response_model não foi passado
+```
+
+- **`content`** é uma string já serializada pelo chamador (JSON, CSV,
+  texto) — a função não sabe de onde o dado vem.
+- **`response_model`** opcional (mesmo padrão do `observation_model` do
+  `Agent`): com ele, o Structured Output usa o schema fechado do
+  modelo e `result.data` vem parseado; sem ele, só `result.text`.
+- **`history`** opcional para follow-up sobre o mesmo conteúdo (ex.:
+  uma segunda pergunta sobre o mesmo relatório) — sem `HistoryStore`,
+  cada chamada é isolada por padrão.
+- **O retorno não passa pelo pipeline** (`Message`/`Route`/etc.): é
+  consumido diretamente por quem chamou — envie via `usercall.send(...)`
+  se estiver dentro de um handler, ou grave em log/banco se for um job
+  agendado sem turno de chat nenhum.
+- Exemplo completo: `examples/content_insight.py`.

chatgraph-1.4.0/CLAUDE.md

@@ -0,0 +1,130 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+`chatgraph` é uma **biblioteca** (não uma aplicação) para construir chatbots orientados a rotas.
+Este arquivo trata de desenvolver a biblioteca. Para *usá-la* em um bot, a referência de API
+está em `.github/skills/chatgraph-framework/SKILL.md`.
+
+## Comandos
+
+O ambiente real de trabalho é o `.venv/` do repositório. `taskipy` **não** está instalado nele,
+então as tasks `poetry run task test|lint|format` documentadas no README e no PROGRESS.md não
+funcionam — use os binários diretamente:
+
+```bash
+.venv/bin/python -m pytest tests/unit -q            # suíte rápida (500 testes, ~20s)
+.venv/bin/python -m pytest tests/unit/test_agent_executor.py -v          # um arquivo
+.venv/bin/python -m pytest tests/unit/test_agent_executor.py::TestNome::test_caso -v   # um teste
+.venv/bin/python -m pytest -m integration -v        # integração (auto-skip sem env vars)
+.venv/bin/ruff check chatgraph                      # lint
+.venv/bin/ruff format .                             # format (aspas simples, linha 79)
+```
+
+`pytest-asyncio` roda em modo strict (sem `asyncio_mode` no `pyproject.toml`): todo teste async
+precisa de `@pytest.mark.asyncio` explícito.
+
+**O lint não está limpo e isso é pré-existente.** Em 2026-08-14, `ruff check .` reportava 775
+erros (174 em `chatgraph/`, 590 em `tests/`), dominados por `PLR6301` (no-self-use nos testes) e
+`E501`; `ruff format --check` acusava 7 arquivos. Não trate esses erros como regressão da sua
+mudança, e não faça um mutirão de correção junto com uma feature — verifique apenas os arquivos
+que você tocou.
+
+Testes de integração leem `ROUTER_API_BASE_URL` (+ `_USERNAME`/`_PASSWORD`) e são **pulados
+silenciosamente** se ela não estiver definida — um "tudo verde" pode significar "nada rodou".
+A lista completa de env vars está em `.env.example`.
+
+## Arquitetura
+
+Pipeline de um turno:
+
+```
+RabbitMQ → MessageConsumer → ChatbotApp.process_message → default_functions (regex)
+        → guard (auth_level) → handler da rota → __process_func_response → UserCall → RouterHTTPClient
+```
+
+Pontos que não se deduzem lendo um arquivo só:
+
+- **O despacho usa apenas o último segmento da rota.** `process_message` calcula
+  `route.split('.')[-1]` e busca essa chave em `self.__routes`, enquanto os decorators registram
+  o nome literal passado. Ou seja: registre handlers com o **nome folha** (`@app.route('choice')`),
+  nunca com o caminho pontuado (`'start.choice'` fica inalcançável). O caminho pontuado é a
+  *posição* do usuário, mantida no backend — não a chave de registro. O README ainda mostra o
+  formato antigo com ponto; ele está desatualizado.
+- **O retorno do handler é a API de efeitos.** `__process_func_response` faz dispatch por tipo:
+  `Message`/`File` envia, `Route` avança e espera nova mensagem, `RedirectResponse` reexecuta o
+  pipeline no mesmo turno, `EndChatResponse`/`TransferToMenu` encerram, `BackgroundTask` roda e
+  encadeia o próprio retorno, `list`/`tuple` processa em sequência. Retornar `None`/falsy
+  **duplica o último segmento** da rota atual (mecanismo de "fica no nó"); `Route.get_previous()`
+  desduplica segmentos repetidos ao voltar. Adicionar um novo tipo de resposta = adicionar um
+  ramo aqui, e não lógica no handler.
+- **`MAX_REDIRECT_DEPTH = 5`** (`bot/chatbot_model.py`) corta cadeias de `RedirectResponse` no
+  mesmo turno. Sem isso um handler (ou agente de IA) em ciclo recursa até estourar a pilha e
+  travar o consumer. `MESSAGE_IN` só é gravado no histórico em `_redirect_depth == 0`, senão a
+  mesma mensagem entraria várias vezes com rotas diferentes.
+- **Handlers podem ser sync ou async.** Sync roda em `run_in_executor`, então um handler sync
+  **não pode** `await` — handlers com agente de IA precisam ser `async`.
+- **Injeção de parâmetros é por anotação de tipo**, não por nome: `build_route_entry`
+  (`bot/route_registry.py`) mapeia `{tipo: nome_do_param}`. Dois parâmetros com a mesma anotação
+  colidem (o último vence) — limitação conhecida e documentada no módulo.
+- **Não existe estado local.** Todo estado de usuário/sessão vive na API externa via
+  `RouterHTTPClient`; `Container.get_router_client()` é o singleton (lê `ROUTER_URL`/`ROUTER_TOKEN`).
+  Não introduza cache nem banco local sem decisão explícita.
+- **Histórico e log de erro são fire-and-forget.** Os hooks de `HistoryStore` e o `LogPublisher`
+  capturam `BaseException` e só emitem warning — observabilidade nunca derruba o turno. Se você
+  adicionar um hook, mantenha esse contrato. `history_store=None` e `LogPublisher` sem
+  `LOG_RABBIT_QUEUE` são no-ops válidos (retrocompatibilidade).
+
+### `chatgraph/agent/` — extra opcional
+
+Port fiel do protocolo **single-agent** do projeto irmão `chatgraph-go` (uma chamada de LLM decide
+navegação *e* escreve a resposta). Regras que orientam mudanças aqui:
+
+- `pydantic` é dependência **só** deste módulo (extra `chatgraph[agent]`). Os símbolos de agente
+  são exportados de forma lazy no `chatgraph/__init__.py` via `__getattr__` (PEP 562), para que
+  quem não instalou o extra não pague o custo nem quebre. Ao adicionar um export de agente,
+  registre-o em `_AGENT_EXPORTS` **e** em `__all__` (o `# ruff: noqa: F822` no topo existe por isso).
+- O executor **não executa efeitos**: ele devolve uma lista dos tipos de retorno já existentes do
+  framework, que o pipeline processa sem alteração. Preserve essa separação.
+- Paridade com o Go é o critério de projeto: `prompts.py` e `schema.py` são ports literais.
+  Divergências devem ser conscientes e registradas (a atual: `transfer_menu` seleciona menu por
+  **name**, porque o client Python não transfere por queue).
+- Proteções do turno que existem por motivo específico, não as remova sem substituto: dedup de
+  tool por `result_key`, `MAX_ATTEMPTS_PER_TOOL = 2`, guard de self-redirect, alvo de rota
+  desconhecido vira "none", transfer inválido falha **antes** de qualquer side effect.
+
+## Convenções
+
+- **Commits em português do Brasil**, Conventional Commits (`feat`, `fix`, `chore`, `refactor`,
+  `test`, `docs`, `style`, `perf`) — ex.: `feat(agent): adiciona guardrails de saída`.
+- **Logs sempre via `UserLoggerManager`**, nunca `print`: dentro de rota use `usercall.logger`
+  (vai para `chatgraph_logs/{user_id}_{company_id}.log`); fora de rota,
+  `UserLoggerManager.get_system_logger()`.
+- **Injeção de dependência manual** por construtor; sem framework de DI, sem prefixo `I` em
+  interfaces. Contratos plugáveis usam `typing.Protocol` (ex.: `HistoryStore`), não ABC.
+- **Docstrings e comentários em português**, seguindo o código existente. Comentário bom aqui
+  explica *por que* a proteção existe (ver `MAX_REDIRECT_DEPTH`), não o que a linha faz.
+- Testes agrupados em classes por unidade sob teste (`Test<Nome>`), fixtures em `conftest.py`,
+  HTTP mockado com `respx`, marcadores `@pytest.mark.unit` / `@pytest.mark.integration`.
+
+## Notas do repositório
+
+- **A CLI não está instalada.** `[project.scripts]` no `pyproject.toml` está comentado, então o
+  comando `chatgraph` documentado no README não existe; `chatgraph/cli/` só roda via
+  `python -m` / import direto. Também é o módulo mais antigo (usa gRPC, imports fora do padrão).
+- `[project] dev-dependencies` no `pyproject.toml` é um campo **não padrão** e ignorado pelos
+  instaladores; as dev deps efetivas estão em `[dependency-groups] dev`. Existem `poetry.lock` e
+  `uv.lock` no repo — confirme qual gerenciador está sendo usado antes de mexer em dependências.
+- Não há CI configurado (`.github/workflows/` não existe): a validação antes de commitar é manual.
+- `chatgraph/pb/` é **gerado** a partir do protobuf — não edite à mão.
+
+## Contexto adicional
+
+- `PROGRESS.md` — linha do tempo, decisões técnicas com justificativa e backlog priorizado.
+  Mantenha-o atualizado ao concluir uma área.
+- `docs/gaps-go-to-python.md` e `docs/gaps-python-to-go.md` — paridade com o `chatgraph-go`; é a
+  fonte de verdade sobre o que falta portar (timeout por rota, route triggers, `validate_routes`,
+  helper de teste tipo `EngineTester`).
+- `.github/copilot-instructions.md` define um fluxo de agentes (Architect → Developer →
+  CodeReviewer, definidos em `.github/agents/`) usado pelo Copilot; não é carregado pelo Claude
+  Code, mas as convenções de código e commit dele são as mesmas resumidas acima.

{chatgraph-1.3.1 → chatgraph-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chatgraph
-Version: 1.3.1
+Version: 1.4.0
 Summary: A user-friendly chatbot library
 Project-URL: Homepage, https://github.com/irissonnlima/chatgraph
 Project-URL: Repository, https://github.com/irissonnlima/chatgraph
@@ -20,6 +20,8 @@ Requires-Dist: protobuf>=6.31.1
 Requires-Dist: python-dotenv>=1.0.1
 Requires-Dist: rich>=13.8.1
 Requires-Dist: typer>=0.12.5
+Provides-Extra: agent
+Requires-Dist: pydantic>=2; extra == 'agent'
 Description-Content-Type: text/markdown
 
 ### **README - ChatGraph**

{chatgraph-1.3.1 → chatgraph-1.4.0}/PROGRESS.md

@@ -1,6 +1,6 @@
 # Progresso do Projeto ChatGraph
 
-**Última atualização:** 2026-08-05
+**Última atualização:** 2026-08-17
 
 ## 1. Visão Geral do Projeto
 
@@ -50,6 +50,8 @@ tests/
 
 | Data | Commit | Descrição |
 |------|--------|-----------|
+| 2026-08-17 | - | **Fix: vocabulário de encerramento do agente + re-prompt corretivo.** Dois turnos de produção em 2026-08-14 falharam por causa raiz comum: o protocolo do agente não distinguia "transferir para outro bot" (`transfer_menu`) de "encerrar atendimento/transferir para humano" (`end_session`, ambos a mesma operação de EndAction no chatbot-router) — um bot acabou configurando um `MenuInfo` chamado `humano`, que o router rejeitou (`sql: no rows in result set`) só depois da promessa já ter sido enviada ao usuário. Correções: (1) `EndActionInfo`/`Agent(end_actions=...)`/`AgentContext.available_end_actions`, seção `AVAILABLE END ACTIONS` no prompt, resolução em `executor.py` (seletor por name/id, falha ANTES de side effect); (2) `AgentActionError` + `AgentContext.last_action_error` — ação inválida (transfer_menu ou end_session com seletor desconhecido) dispara 1 re-prompt corretivo por turno em vez de estourar o turno inteiro; sem correção, fallback é uma mensagem neutra fixa (nunca o `result.response`, que nesses casos costuma ser a promessa que acabou de falhar); (3) `build_agent_result_schema` parametrizado com enum de `menu`/`end_action_id` por Agent (`lru_cache(maxsize=32)`, antes `maxsize=1` sem args); (4) `agent.validate_config(router_client)` opt-in, confere no boot se menus/end_actions existem de verdade; (5) `TransferToHuman` aposentado do público (`__init__.py`, SKILL.md) — código morto no pipeline HTTP, mesma fonte de confusão um nível abaixo. Log DEBUG do raw response da LLM em `openrouter.py` para diagnosticar o próximo caso. Bug lateral corrigido: `Message.from_dict` não convertia `file` de dict para `File`, quebrando o registro de histórico em mensagens com anexo (`'dict' object has no attribute 'to_dict'`). |
+| 2026-08-14 | - | **Agentes de IA (v1.4.0):** novo módulo `chatgraph/agent/` portando o protocolo single-agent do `chatgraph-go`: `Agent` (tools locais via `@agent.tool`, `generate_protocol`), `OpenRouterClient` (httpx, retry/backoff/Retry-After, structured outputs), normalização de JSON Schema (`schema.py`, port do `normalize.go`), prompts portados literalmente, executor com proteções (dedup por `result_key`, máx. 2 tentativas por tool, self-redirect guard, redirect silencioso, parada na primeira ação terminal, merge aditivo de observation), `history_bridge` (pareamento assistant/tool + `trim_safe`). Integração: `description=`/`ai_visible=` nos decorators (builder comum `route_registry.py`), `Route.infos`, `MAX_REDIRECT_DEPTH=5` no pipeline (corrige loop infinito de redirects e MESSAGE_IN duplicado em redirects). Extra opcional `chatgraph[agent]` (pydantic>=2) com exports lazy (PEP 562). Divergência consciente do Go: `transfer_menu` seleciona por **name** (client Python não transfere por queue). 461 testes unitários. |
 | 2026-08-05 | `c24cbbd` | **Fix: acúmulo de `[ChatID: ...]` nos logs:** `ChatIDFilter.filter()` tornado idempotente (verifica `startswith` antes de prefixar); `remove_user_logger()` agora remove instâncias de `ChatIDFilter` antes de fechar handlers; `ChatID.__str__` adicionado (`user_id:company_id`); prefixo hardcoded removido da exceção em `UserCall.__send()`. Testes: `TestChatIDFilter` (3 novos), `test_remove_user_logger_removes_chatid_filters`, `test_remove_then_get_has_exactly_one_chatid_filter`, `test_chatid_str`, `TestSendException`. Revisão: ⚠️ CUIDADO — edge case `startswith` com `record.msg` não-string; teste de exceção poderia validar ausência de prefixo com `assert '[ChatID:' not in ...`. |
 | 2026-08-04 | `672e4df` | **LogPublisher + integração final do histórico:** `LogPublisher` para publicação de erros via RabbitMQ com auto-configuração via `load_dotenv()`; `LogEnvelope`, `ErrorLogPayload`, `EventType` e mapeamento `error_code` por tipo de exceção. Integração completa do `HistoryStore` no pipeline: hooks `MESSAGE_IN`/`MESSAGE_OUT`/`ROUTE_CHANGE`/`TRANSFER`/`END_CHAT` no `UserCall` e `ChatbotApp`; repasse via `MessageConsumer`. Novas properties em `UserCall`: `user_state`, `session_id`, `message`, `history`. Publicação de erros em `ChatbotApp._publish_error_log` e `MessageConsumer._process_message_callback`. |
 | 2026-08-04 | `c24cbbd` | **Testes:** `TestLogPublisher`, `TestLogEnvelope`, `TestChatbotAppLogPublisher`, `TestMessageConsumerLogPublisher`, `TestHistoryStore`, `TestHistoryIntegration`, `TestUserStateProperty`. Total: 283 testes unitários. |
@@ -74,9 +76,10 @@ tests/
 | **HTTP Router Client** | ✅ | RouterHTTPClient para integração com API REST |
 | **Logging** | ✅ | UserLoggerManager com logs por usuário e sistema |
 | **CLI** | ✅ | Comandos básicos (campaigns, delete-ustate) |
-| **Testes Unitários** | ✅ | 283 testes passando (histórico + log publisher + UserState) |
+| **Agentes de IA** | ✅ | Módulo `chatgraph/agent/` (protocolo single-agent do Go): Agent + tools locais, OpenRouterClient, schema normalizer, executor com proteções (inclui re-prompt corretivo de ação inválida), histórico com pareamento assistant/tool, `end_actions`/`validate_config`, `generate_content` desacoplado do turno de chat. Extra `chatgraph[agent]`. Futuro: two-agent, MCP, memória, guardrails |
+| **Testes Unitários** | ✅ | 500 testes passando (agent + histórico + log publisher + UserState) |
 | **Testes de Integração** | ⚠️ | Requer variáveis de ambiente configuradas |
-| **Documentação** | ⚠️ | README completo, falta docs/ detalhada |
+| **Documentação** | ⚠️ | README completo + SKILL.md §14 (agentes); falta docs/ detalhada |
 
 **Legenda:**
 - ✅ Completo
@@ -158,15 +161,25 @@ poetry run ruff check . && ruff format .
 | gRPC | protobuf | Contratos tipados e performance |
 | History Store | Protocol (não ABC) | Plugável, sem acoplamento a classe base |
 | Log Publisher | load_dotenv() + opcional | Retrocompatível — se `LOG_RABBIT_QUEUE` não estiver definido, o publisher é `None` e os erros não são publicados |
+| Agentes de IA | Port fiel do Go, sem pydantic-ai/SDK openai | Paridade de comportamento entre os frameworks; cliente OpenRouter próprio via httpx; pydantic>=2 isolado ao módulo `agent/` (extra opcional `chatgraph[agent]`, exports lazy PEP 562) |
+| transfer_menu do agente | Seletor por `name` do menu | O client Python só transfere por nome (`Menu.from_name`); queue/menu_id do Go não mapeiam — reintroduzir se o RouterHTTPClient ganhar transfer por queue |
+| Redirects | `MAX_REDIRECT_DEPTH=5` global | Recursão de `RedirectResponse` era ilimitada (risco de loop, agravado por agentes); a reentrada por redirect também não regrava MESSAGE_IN no histórico |
+| end_session do agente | Seletor por `name` (depois `id`) de `EndActionInfo`, mesmo critério do `transfer_menu` | `end_session` cobre encerrar E transferir para humano (mesma EndAction no chatbot-router); sem `end_actions` configuradas, `end_action_id` continua livre (retrocompatível) |
+| Ação inválida do agente | Re-prompt corretivo (1 tentativa/turno via `AgentContext.last_action_error`), depois mensagem neutra fixa | Um `transfer_menu`/`end_session` com seletor inexistente perdia o turno inteiro em silêncio (ou, pior, enviava a promessa antes do router rejeitar); "falha antes de side effect" continua valendo — a correção nunca executa ação |
+| TransferToHuman | Aposentado do público (`__init__.py`, SKILL.md); classe mantida em `end_types.py` só por compatibilidade de import | Código morto no pipeline HTTP (sem ramo em `__process_func_response`, sem método no `RouterHTTPClient`) — mesma confusão de "transferir para humano" um nível abaixo do bug de `transfer_menu`/`humano` |
 
 ## 9. Trabalhos Pendentes
 
 | Prioridade | Tarefa | Área | Status |
 |------------|--------|------|--------|
 | Alta | Eliminar duplicação de lógica de registro entre `ChatbotApp.__record_message_in` e `UserCall.__record_history` | chatgraph/bot + types | ⚠️ |
+| Média | Agentes: protocolo two-agent (`DecideRoute`+`Speak`) | chatgraph/agent | ❌ |
+| Média | Agentes: MCP (stdio/SSE/HTTP) como fonte de tools | chatgraph/agent | ❌ |
+| Média | Agentes: memória de longo prazo (`MemoryContext`) e guardrails | chatgraph/agent | ❌ |
 | Média | Documentação técnica detalhada | docs/ | ❌ |
 | Média | Mais testes de integração | tests/integration/ | ⚠️ |
-| Baixa | Exemplos adicionais | examples/ | ❌ |
+| Baixa | Dispatcher com serialização por chat_id (prefetch > 1 seguro p/ bots com agente) | messages/ | ❌ |
+| Baixa | Exemplos adicionais | examples/ | ⚠️ (`examples/agents_bot.py` criado) |
 | Baixa | Suporte a mais plataformas | bot/ | ❌ |
 
 ## 10. Notas e Observações

chatgraph-1.4.0/chatgraph/__init__.py

@@ -0,0 +1,123 @@
+# ruff: noqa: F822 - os símbolos do agente em __all__ resolvem via
+# __getattr__ (PEP 562, import lazy); o ruff não os enxerga.
+from .auth.credentials import Credential
+from .bot.chatbot_model import ChatbotApp
+from .bot.chatbot_router import ChatbotRouter
+from .bot.default_guard import default_guard
+from .container.container import Container
+from .logger import logger, set_level
+from .messages.log_publisher import LogPublisher
+from .messages.message_consumer import MessageConsumer
+from .models.log_envelope import (
+    ErrorLogPayload,
+    EventType,
+    LogEnvelope,
+)
+from .models.message import Button, File, Message, SendType, TextMessage
+from .models.platform_state import PlatformState, VollStateData
+from .models.userstate import (
+    AuthLevel,
+    ChatID,
+    Menu,
+    User,
+    UserData,
+    UserIdentity,
+    UserInternal,
+    UserState,
+)
+from .types.background_task import BackgroundTask
+from .types.end_types import (
+    EndChatResponse,
+    RedirectResponse,
+    TransferToMenu,
+)
+from .types.route import Route
+from .types.usercall import UserCall
+
+# Símbolos do módulo de agentes de IA (extra opcional `agent`).
+# Import lazy via PEP 562: quem não instalou pydantic não paga o custo
+# nem quebra; o erro amigável vem do guard em chatgraph/agent/__init__.
+_AGENT_EXPORTS = {
+    'Agent': 'chatgraph.agent.agent',
+    'AgentAction': 'chatgraph.agent.protocol',
+    'AgentActionError': 'chatgraph.agent.errors',
+    'AgentContext': 'chatgraph.agent.protocol',
+    'AgentError': 'chatgraph.agent.errors',
+    'AgentResult': 'chatgraph.agent.protocol',
+    'ContentResult': 'chatgraph.agent.content',
+    'EndActionInfo': 'chatgraph.agent.protocol',
+    'LLMClientError': 'chatgraph.agent.errors',
+    'MenuInfo': 'chatgraph.agent.protocol',
+    'OpenRouterClient': 'chatgraph.agent.openrouter',
+    'RouteInfo': 'chatgraph.agent.protocol',
+    'Tool': 'chatgraph.agent.types',
+    'ToolExecutionError': 'chatgraph.agent.errors',
+    'ToolInfo': 'chatgraph.agent.protocol',
+    'Usage': 'chatgraph.agent.types',
+    'execute_single_agent': 'chatgraph.agent.executor',
+    'generate_content': 'chatgraph.agent.content',
+}
+
+
+def __getattr__(name: str):
+    if name in _AGENT_EXPORTS:
+        import importlib  # noqa: PLC0415 - import lazy proposital
+
+        module = importlib.import_module(_AGENT_EXPORTS[name])
+        return getattr(module, name)
+    raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+
+__all__ = [
+    'Agent',
+    'AgentAction',
+    'AgentActionError',
+    'AgentContext',
+    'AgentError',
+    'AgentResult',
+    'ContentResult',
+    'EndActionInfo',
+    'LLMClientError',
+    'MenuInfo',
+    'OpenRouterClient',
+    'RouteInfo',
+    'Tool',
+    'ToolExecutionError',
+    'ToolInfo',
+    'Usage',
+    'execute_single_agent',
+    'generate_content',
+    'set_level',
+    'ChatbotApp',
+    'Credential',
+    'UserCall',
+    'ChatbotRouter',
+    'RedirectResponse',
+    'MessageConsumer',
+    'LogPublisher',
+    'LogEnvelope',
+    'ErrorLogPayload',
+    'EventType',
+    'Route',
+    'EndChatResponse',
+    'TransferToMenu',
+    'UserState',
+    'ChatID',
+    'Menu',
+    'AuthLevel',
+    'User',
+    'UserData',
+    'UserIdentity',
+    'UserInternal',
+    'Message',
+    'Button',
+    'File',
+    'TextMessage',
+    'SendType',
+    'BackgroundTask',
+    'Container',
+    'logger',
+    'default_guard',
+    'PlatformState',
+    'VollStateData',
+]

chatgraph-1.4.0/chatgraph/agent/__init__.py

@@ -0,0 +1,28 @@
+"""Módulo de agentes de IA do chatgraph.
+
+Requer o extra opcional ``agent``::
+
+    pip install chatgraph[agent]
+"""
+
+try:
+    import pydantic  # noqa: F401
+except ImportError as exc:  # pragma: no cover
+    raise ModuleNotFoundError(
+        'O módulo chatgraph.agent requer o extra "agent". '
+        'Instale com: pip install chatgraph[agent]'
+    ) from exc
+
+from .errors import (
+    AgentConfigurationError,
+    AgentError,
+    LLMClientError,
+    ToolExecutionError,
+)
+
+__all__ = [
+    'AgentConfigurationError',
+    'AgentError',
+    'LLMClientError',
+    'ToolExecutionError',
+]