cristiano.hoshikawa/agent_contas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

bugfix: route stickness precedences (transaction in the same intent)

Browse Source
This commit is contained in:
Cristiano Hoshikawa
2026-08-20 09:22:03 -03:00
parent bb0ef019bf
commit 9df2467deb
434 changed files with 7098 additions and 281 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
agent_framework_oci/Documentacao/IMPLEMENTACAO_WORKFLOWS_TRANSACIONAIS.md Normal file
View File

@@ -0,0 +1,64 @@
# Implementação — workflows transacionais determinísticos
## Entrega
Foi adicionada ao `agent_framework_oci` uma capacidade opcional para executar transações multi-etapas como workflows determinísticos compilados em LangGraph.
### Módulo novo
`libs/agent_framework/src/agent_framework/workflows/`
- `models.py`: contratos Pydantic e validação estrutural;
- `repository.py`: resolução de versão ativa e leitura de YAML imutável;
- `registry.py`: registro desacoplado de actions sync/async;
- `runtime.py`: compilação, cache e execução do StateGraph;
- `tool_executor.py`: integração com a política da tool;
- `__init__.py`: API pública.
### Política expandida
`ToolPolicy` agora aceita:
```yaml
execution:
mode: direct_tool | workflow | agent
workflow: nome_do_workflow
version: active | 1
```
O default permanece `direct_tool`, preservando compatibilidade.
### Configuração
Foram adicionados:
- `ENABLE_TRANSACTIONAL_WORKFLOWS=false`;
- `WORKFLOWS_PATH=./workflows`.
### Template
Inclui um exemplo completo de devolução de pedido com:
- confirmação e campos obrigatórios pela política;
- workflow YAML versionado;
- actions de domínio no backend;
- bifurcação determinística baseada no resultado da validação.
## Validação realizada
- `tests/unit/test_tool_policies.py`: 4 testes aprovados;
- compilação Python de framework, template e novos testes: aprovada;
- o teste funcional novo do LangGraph foi criado, mas não pôde ser executado neste container porque `langgraph` não está instalado no ambiente. A dependência já está declarada no `pyproject.toml` do framework.
## Escopo e segurança
Esta entrega cria o motor e a integração de política. Para operações críticas em produção ainda é necessário conectar:
- execution store persistente;
- idempotência de negócio nas actions/APIs;
- autorização por escopo;
- telemetria IC/NOC específica de workflow;
- compensação/Saga quando aplicável;
- estratégia corporativa de timeout e retry.
Esses itens foram explicitamente documentados para evitar a falsa impressão de que retry por si só garante segurança transacional.

987
agent_framework_oci/Documentacao/Implementando_Basic_Auth.md Normal file
View File

@@ -0,0 +1,987 @@
# Implementando Basic Auth
Para validar **todo o circuito com Basic Auth**, você precisa configurar três relações distintas:
```text
Cliente de teste
└─ Basic Auth A ─► Agent Gateway :8010
└─ Basic Auth B ─► Agent Backend :8000
└─ Basic Auth C ─► MCP Gateway :8300
```
Há um detalhe importante: no pacote atual, a autenticação Basic já funciona para chamadas **de entrada**, mas os clientes internos ainda não enviam Basic Auth:
* `Agent Gateway → Agent Backend` não envia credencial;
* `Agent Backend → MCP Gateway` envia apenas Bearer Token.
Portanto, para testar o circuito inteiro com Basic Auth, faça os dois pequenos ajustes de código descritos abaixo.
---
# 1. Preparar o ambiente
Considere que o ZIP foi extraído em:
```bash
cd agent_framework_oci_authentication_v2_1
```
Crie um único ambiente virtual para facilitar o teste:
```bash
python -m venv .venv
source .venv/bin/activate
```
No Windows PowerShell:
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```
Instale o framework e as dependências dos três componentes:
```bash
pip install -U pip
pip install -e ./libs/agent_framework
pip install \
-r ./Tuning-Performance/Authentication/agent_template_backend_authentication/requirements.txt \
-r ./apps/agent_gateway/requirements.txt \
-r ./apps/mcp_gateway/requirements.txt
```
Confirme a importação:
```bash
python -c "from agent_framework.security import install_authentication; print('framework ok')"
```
---
# 2. Criar três pares de Client ID e Secret
Use credenciais diferentes para cada trecho. Para teste local:
| Fluxo | Client ID | Secret de teste |
| ----------------------- | -------------------- | --------------------------- |
| Cliente → Agent Gateway | `tia-test` | `TiaGateway-Test-2026!` |
| Agent Gateway → Backend | `agent-gateway-test` | `GatewayBackend-Test-2026!` |
| Backend → MCP Gateway | `agent-backend-test` | `BackendMcp-Test-2026!` |
Esses valores são apenas para ambiente local. Não os reutilize em produção.
## Gerar os hashes
O script está em:
```text
Tuning-Performance/Authentication/
agent_template_backend_authentication/
scripts/generate_secret_hash.py
```
Execute:
```bash
python Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/generate_secret_hash.py \
--secret 'TiaGateway-Test-2026!'
```
Depois:
```bash
python Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/generate_secret_hash.py \
--secret 'GatewayBackend-Test-2026!'
```
E:
```bash
python Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/generate_secret_hash.py \
--secret 'BackendMcp-Test-2026!'
```
Você receberá três valores semelhantes a:
```text
pbkdf2_sha256:310000:<salt>:<digest>
```
Guarde-os temporariamente:
```bash
HASH_CLIENT_GATEWAY='pbkdf2_sha256:310000:...'
HASH_GATEWAY_BACKEND='pbkdf2_sha256:310000:...'
HASH_BACKEND_MCP='pbkdf2_sha256:310000:...'
```
O hash muda a cada execução porque o salt é aleatório. Isso é esperado.
---
# 3. Configurar o Agent Gateway
Entre no diretório:
```bash
cd apps/agent_gateway
```
Copie o exemplo:
```bash
cp .env.example .env
```
Adicione ao final do `.env`:
```env
# Entrada: cliente/TIA -> Agent Gateway
AGENT_GATEWAY_AUTH_ENABLED=true
AGENT_GATEWAY_AUTH_MODE=basic
AGENT_GATEWAY_AUTH_BASIC_CLIENT_ID=tia-test
AGENT_GATEWAY_AUTH_BASIC_SECRET_HASH=COLE_AQUI_HASH_CLIENT_GATEWAY
AGENT_GATEWAY_AUTH_BASIC_REALM=agent-gateway
AGENT_GATEWAY_AUTH_PUBLIC_PATHS=/health,/docs,/openapi.json,/redoc
AGENT_GATEWAY_AUTH_PUBLIC_PREFIXES=
# Saída: Agent Gateway -> Agent Backend
BACKEND_AUTH_MODE=basic
BACKEND_AUTH_CLIENT_ID=agent-gateway-test
BACKEND_AUTH_SECRET=GatewayBackend-Test-2026!
```
Não coloque aspas no `.env`:
```env
BACKEND_AUTH_SECRET=GatewayBackend-Test-2026!
```
O arquivo de backends já aponta o backend Contas para:
```yaml
contas:
url: http://localhost:8000
```
Arquivo:
```text
apps/agent_gateway/config/backends.yaml
```
Para este teste, mantenha apenas o backend `contas` ou force o backend no payload. Caso contrário, pedidos sobre ofertas e suporte podem ser roteados para portas em que nenhum backend está rodando.
---
# 4. Fazer o Agent Gateway enviar Basic Auth ao backend
Abra:
```text
libs/agent_framework/src/agent_framework/global_supervisor/client.py
```
Substitua a classe `BackendClient` por uma versão que aceite autenticação Basic.
No início do arquivo, adicione:
```python
import os
```
Altere o construtor:
```python
class BackendClient:
def __init__(
self,
timeout_seconds: float = 120.0,
basic_client_id: str | None = None,
basic_secret: str | None = None,
):
self.timeout_seconds = timeout_seconds
self.basic_client_id = basic_client_id
self.basic_secret = basic_secret
def _auth(self) -> httpx.BasicAuth | None:
if self.basic_client_id and self.basic_secret:
return httpx.BasicAuth(
username=self.basic_client_id,
password=self.basic_secret,
)
return None
```
No método `call_message`, troque:
```python
resp = await client.post(url, json=payload)
```
por:
```python
resp = await client.post(
url,
json=payload,
auth=self._auth(),
)
```
No método `health`, você pode manter `/health` público. Caso queira enviar autenticação também, use:
```python
resp = await client.get(url, auth=self._auth())
```
Agora abra:
```text
apps/agent_gateway/app/main.py
```
Adicione:
```python
import os
```
Troque:
```python
backend_client = BackendClient(
timeout_seconds=settings.BACKEND_TIMEOUT_SECONDS
)
```
por:
```python
backend_client = BackendClient(
timeout_seconds=settings.BACKEND_TIMEOUT_SECONDS,
basic_client_id=os.getenv("BACKEND_AUTH_CLIENT_ID"),
basic_secret=os.getenv("BACKEND_AUTH_SECRET"),
)
```
Isso implementa:
```text
Agent Gateway → Agent Backend
Authorization: Basic base64(agent-gateway-test:GatewayBackend-Test-2026!)
```
---
# 5. Configurar o Agent Backend autenticado
Entre no diretório:
```bash
cd Tuning-Performance/Authentication/agent_template_backend_authentication
```
Copie o exemplo:
```bash
cp .env.example .env
```
Ajuste a seção de autenticação:
```env
# Entrada: Agent Gateway -> Agent Backend
AGENT_AUTH_ENABLED=true
AGENT_AUTH_MODE=basic
AGENT_AUTH_BASIC_CLIENT_ID=agent-gateway-test
AGENT_AUTH_BASIC_SECRET_HASH=COLE_AQUI_HASH_GATEWAY_BACKEND
AGENT_AUTH_BASIC_REALM=agent-contas
AGENT_AUTH_PUBLIC_PATHS=/health,/docs,/openapi.json,/redoc
AGENT_AUTH_PUBLIC_PREFIXES=
```
Para usar o MCP Gateway:
```env
MCP_GATEWAY_ENABLED=true
MCP_GATEWAY_URL=http://localhost:8300
MCP_GATEWAY_TIMEOUT_SECONDS=60
# Saída: Agent Backend -> MCP Gateway
MCP_GATEWAY_AUTH_MODE=basic
MCP_GATEWAY_BASIC_CLIENT_ID=agent-backend-test
MCP_GATEWAY_BASIC_SECRET=BackendMcp-Test-2026!
```
Para evitar dependências externas durante o primeiro teste, configure também:
```env
LLM_PROVIDER=mock
ENABLE_LANGFUSE=false
ENABLE_ANALYTICS=false
SESSION_REPOSITORY_PROVIDER=memory
MEMORY_REPOSITORY_PROVIDER=memory
CHECKPOINT_REPOSITORY_PROVIDER=memory
CACHE_PROVIDER=memory
USAGE_REPOSITORY_PROVIDER=memory
```
Os nomes exatos de alguns providers podem depender do arquivo de configuração atual do framework. Caso o `.env.example` já contenha valores locais ou mock, preserve-os.
---
# 6. Fazer o Backend enviar Basic Auth ao MCP Gateway
Abra:
```text
libs/agent_framework/src/agent_framework/gateways/mcp_gateway_client.py
```
Substitua a implementação por:
```python
from __future__ import annotations
import base64
from typing import Any
import httpx
class MCPGatewayClient:
def __init__(
self,
base_url: str,
token: str | None = None,
timeout_seconds: int = 60,
auth_mode: str | None = None,
basic_client_id: str | None = None,
basic_secret: str | None = None,
):
self.base_url = base_url.rstrip("/")
self.token = token
self.timeout_seconds = timeout_seconds
self.auth_mode = (auth_mode or "").strip().lower()
self.basic_client_id = basic_client_id
self.basic_secret = basic_secret
def _headers(self) -> dict[str, str]:
if (
self.auth_mode == "basic"
and self.basic_client_id
and self.basic_secret
):
raw = f"{self.basic_client_id}:{self.basic_secret}".encode("utf-8")
encoded = base64.b64encode(raw).decode("ascii")
return {"Authorization": f"Basic {encoded}"}
if self.token:
return {"Authorization": f"Bearer {self.token}"}
return {}
async def list_tools(self) -> dict[str, Any]:
async with httpx.AsyncClient(
timeout=self.timeout_seconds
) as client:
response = await client.get(
f"{self.base_url}/v1/tools",
headers=self._headers(),
)
response.raise_for_status()
return response.json()
async def invoke_tool(
self,
*,
tenant_id: str,
agent_id: str,
channel: str | None,
tool_name: str,
arguments: dict[str, Any] | None = None,
business_context: dict[str, Any] | None = None,
metadata: dict[str, Any] | None = None,
) -> dict[str, Any]:
payload = {
"tenant_id": tenant_id,
"agent_id": agent_id,
"channel": channel,
"tool_name": tool_name,
"arguments": arguments or {},
"business_context": business_context or {},
"metadata": metadata or {},
}
async with httpx.AsyncClient(
timeout=self.timeout_seconds
) as client:
response = await client.post(
f"{self.base_url}/v1/tools/{tool_name}/invoke",
json=payload,
headers=self._headers(),
)
response.raise_for_status()
return response.json()
```
Agora abra:
```text
libs/agent_framework/src/agent_framework/mcp/tool_router.py
```
Localize:
```python
MCPGatewayClient(
base_url=getattr(
settings,
"MCP_GATEWAY_URL",
"http://localhost:8300",
),
token=getattr(settings, "MCP_GATEWAY_TOKEN", None),
timeout_seconds=getattr(
settings,
"MCP_GATEWAY_TIMEOUT_SECONDS",
settings.MCP_TOOL_TIMEOUT_SECONDS,
),
)
```
Altere para:
```python
MCPGatewayClient(
base_url=getattr(
settings,
"MCP_GATEWAY_URL",
"http://localhost:8300",
),
token=getattr(settings, "MCP_GATEWAY_TOKEN", None),
timeout_seconds=getattr(
settings,
"MCP_GATEWAY_TIMEOUT_SECONDS",
settings.MCP_TOOL_TIMEOUT_SECONDS,
),
auth_mode=getattr(
settings,
"MCP_GATEWAY_AUTH_MODE",
None,
),
basic_client_id=getattr(
settings,
"MCP_GATEWAY_BASIC_CLIENT_ID",
None,
),
basic_secret=getattr(
settings,
"MCP_GATEWAY_BASIC_SECRET",
None,
),
)
```
Adicione estes campos em:
```text
libs/agent_framework/src/agent_framework/config/settings.py
```
Próximo das configurações existentes de MCP Gateway:
```python
MCP_GATEWAY_AUTH_MODE: str | None = None
MCP_GATEWAY_BASIC_CLIENT_ID: str | None = None
MCP_GATEWAY_BASIC_SECRET: str | None = None
```
Há também uma factory local em:
```text
Tuning-Performance/Authentication/
agent_template_backend_authentication/
app/mcp_gateway_client_factory.py
```
Ajuste para:
```python
from __future__ import annotations
import os
from agent_framework.gateways import MCPGatewayClient
def build_mcp_gateway_client() -> MCPGatewayClient | None:
if os.getenv("MCP_GATEWAY_ENABLED", "true").lower() != "true":
return None
return MCPGatewayClient(
base_url=os.getenv(
"MCP_GATEWAY_URL",
"http://localhost:8300",
),
token=os.getenv("MCP_GATEWAY_TOKEN") or None,
timeout_seconds=int(
os.getenv("MCP_GATEWAY_TIMEOUT_SECONDS", "60")
),
auth_mode=os.getenv("MCP_GATEWAY_AUTH_MODE"),
basic_client_id=os.getenv(
"MCP_GATEWAY_BASIC_CLIENT_ID"
),
basic_secret=os.getenv(
"MCP_GATEWAY_BASIC_SECRET"
),
)
```
---
# 7. Configurar o MCP Gateway
Entre no diretório:
```bash
cd apps/mcp_gateway
```
Crie `.env`:
```bash
cp .env.example .env
```
Adicione:
```env
# Entrada: Agent Backend -> MCP Gateway
MCP_GATEWAY_AUTH_ENABLED=true
MCP_GATEWAY_AUTH_MODE=basic
MCP_GATEWAY_AUTH_BASIC_CLIENT_ID=agent-backend-test
MCP_GATEWAY_AUTH_BASIC_SECRET_HASH=COLE_AQUI_HASH_BACKEND_MCP
MCP_GATEWAY_AUTH_BASIC_REALM=mcp-gateway
MCP_GATEWAY_AUTH_PUBLIC_PATHS=/health,/ready,/docs,/openapi.json,/redoc
MCP_GATEWAY_AUTH_PUBLIC_PREFIXES=
MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
```
## Desabilitar o mecanismo Bearer legado
O MCP Gateway ainda possui um segundo mecanismo antigo, configurado dentro de:
```text
apps/mcp_gateway/config/mcp_gateway.yaml
```
Localize a seção:
```yaml
auth:
enabled: true
```
Altere para:
```yaml
auth:
enabled: false
```
Isso é necessário porque o novo middleware já faz a autenticação Basic. Caso o `auth_check()` legado continue habilitado, a requisição passará pelo Basic e depois será rejeitada por não possuir Bearer Token.
---
# 8. Subir os componentes
Use quatro terminais.
## Terminal 1 — MCP Servers
O MCP Gateway precisa ter pelo menos um servidor MCP disponível para demonstrar uma chamada real.
Na raiz do projeto:
```bash
source .venv/bin/activate
```
Suba o servidor telecom:
```bash
uvicorn mcp.servers.telecom_mcp_server.main:app \
--host 0.0.0.0 \
--port 8100 \
--reload
```
Em outro terminal, caso queira também o retail:
```bash
uvicorn mcp.servers.retail_mcp_server.main:app \
--host 0.0.0.0 \
--port 8200 \
--reload
```
Confira as URLs configuradas em:
```text
apps/mcp_gateway/config/mcp_gateway.yaml
```
Para execução local, devem apontar para:
```yaml
url: http://localhost:8100
```
e:
```yaml
url: http://localhost:8200
```
---
## Terminal 2 — MCP Gateway
```bash
cd apps/mcp_gateway
source ../../.venv/bin/activate
```
Suba usando `--env-file`. Isso é importante porque o middleware lê variáveis com `os.getenv()`:
```bash
uvicorn app.main:app \
--host 0.0.0.0 \
--port 8300 \
--reload \
--env-file .env
```
Teste a saúde pública:
```bash
curl http://localhost:8300/health
```
Teste um endpoint protegido sem credencial:
```bash
curl -i http://localhost:8300/v1/tools
```
Esperado:
```text
HTTP/1.1 401 Unauthorized
```
Teste com Basic Auth:
```bash
curl -i \
-u 'agent-backend-test:BackendMcp-Test-2026!' \
http://localhost:8300/v1/tools
```
Esperado:
```text
HTTP/1.1 200 OK
```
---
## Terminal 3 — Agent Backend
```bash
cd Tuning-Performance/Authentication/agent_template_backend_authentication
source ../../../.venv/bin/activate
```
Suba:
```bash
uvicorn app.main:app \
--host 0.0.0.0 \
--port 8000 \
--reload \
--env-file .env
```
Teste saúde:
```bash
curl http://localhost:8000/health
```
Teste endpoint protegido sem credencial:
```bash
curl -i http://localhost:8000/agents
```
Esperado:
```text
HTTP/1.1 401 Unauthorized
```
Teste com a credencial usada pelo Agent Gateway:
```bash
curl -i \
-u 'agent-gateway-test:GatewayBackend-Test-2026!' \
http://localhost:8000/agents
```
Esperado:
```text
HTTP/1.1 200 OK
```
Teste mensagem diretamente:
```bash
curl -X POST http://localhost:8000/gateway/message \
-u 'agent-gateway-test:GatewayBackend-Test-2026!' \
-H 'Content-Type: application/json' \
-d '{
"channel": "web",
"agent_id": "telecom_contas",
"tenant_id": "default",
"payload": {
"text": "Quero consultar minha fatura",
"session_id": "teste-backend-001",
"user_id": "user-001",
"customer_id": "12345",
"message_id": "msg-001"
}
}'
```
---
## Terminal 4 — Agent Gateway
```bash
cd apps/agent_gateway
source ../../.venv/bin/activate
```
Suba:
```bash
uvicorn app.main:app \
--host 0.0.0.0 \
--port 8010 \
--reload \
--env-file .env
```
Teste saúde:
```bash
curl http://localhost:8010/health
```
Teste endpoint protegido sem credencial:
```bash
curl -i http://localhost:8010/backends
```
Esperado:
```text
HTTP/1.1 401 Unauthorized
```
Teste com a credencial externa:
```bash
curl -i \
-u 'tia-test:TiaGateway-Test-2026!' \
http://localhost:8010/backends
```
Esperado:
```text
HTTP/1.1 200 OK
```
---
# 9. Validar o circuito completo
Force o backend `contas` para evitar que o roteador selecione um backend não iniciado:
```bash
curl -X POST http://localhost:8010/gateway/message \
-u 'tia-test:TiaGateway-Test-2026!' \
-H 'Content-Type: application/json' \
-d '{
"channel": "web",
"backend_id": "contas",
"tenant_id": "default",
"agent_id": "telecom_contas",
"session_id": "circuito-basic-001",
"payload": {
"text": "Quero consultar minha fatura",
"session_id": "circuito-basic-001",
"user_id": "user-001",
"customer_id": "12345",
"message_id": "msg-circuito-001"
}
}'
```
O circuito esperado é:
```text
curl
│ Basic tia-test
▼
Agent Gateway :8010
│ Basic agent-gateway-test
▼
Agent Backend :8000
│ Basic agent-backend-test
▼
MCP Gateway :8300
▼
MCP Server :8100 ou :8200
```
---
# 10. Como comprovar cada autenticação
Faça testes negativos em cada trecho.
## Secret externo incorreto
```bash
curl -i \
-u 'tia-test:senha-errada' \
http://localhost:8010/backends
```
Resultado esperado:
```text
401 Unauthorized
```
## Secret do gateway para backend incorreto
Altere temporariamente no `apps/agent_gateway/.env`:
```env
BACKEND_AUTH_SECRET=senha-errada
```
Reinicie o Agent Gateway e envie uma mensagem.
O gateway deverá retornar erro de backend, normalmente:
```text
502 Bad Gateway
```
O erro interno será originado por um:
```text
401 Unauthorized
```
do Agent Backend.
## Secret do backend para MCP incorreto
Altere temporariamente:
```env
MCP_GATEWAY_BASIC_SECRET=senha-errada
```
Reinicie o backend e execute uma frase que acione uma ferramenta MCP.
O backend deverá registrar falha na chamada ao MCP Gateway com:
```text
401 Unauthorized
```
---
# 11. Verificação rápida de portas
No Linux ou WSL:
```bash
ss -lntp | grep -E ':8000|:8010|:8100|:8200|:8300'
```
No Windows PowerShell:
```powershell
Get-NetTCPConnection -State Listen |
Where-Object LocalPort -in 8000,8010,8100,8200,8300 |
Sort-Object LocalPort
```
Você deverá ver:
```text
8000 Agent Backend
8010 Agent Gateway
8100 Telecom MCP Server
8200 Retail MCP Server
8300 MCP Gateway
```
## Observação importante
O segredo original precisa existir no componente cliente:
```text
TIA ou curl:
TiaGateway-Test-2026!
Agent Gateway:
GatewayBackend-Test-2026!
Agent Backend:
BackendMcp-Test-2026!
```
Os componentes servidores armazenam apenas os hashes:
```text
Agent Gateway:
hash de TiaGateway-Test-2026!
Agent Backend:
hash de GatewayBackend-Test-2026!
MCP Gateway:
hash de BackendMcp-Test-2026!
```
Em produção, os segredos originais e hashes devem vir de Vault ou Kubernetes Secret, não de arquivos `.env`.