cristiano.hoshikawa/agent_platform_oci
1
2
Fork 0
mirror of https://github.com/hoshikawa2/agent_platform_oci.git synced 2026-09-07 18:23:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

New features: Domain_Requested_LLM_Composition, Domain_Requested_RAG, Offline_Workflow_Regression, Pause_Resume_Workflow, Voice_Interruption_Replay, Workflow_Error_Recovery, Durable Idempotency, Workflow_Pause_Resume, Dynamic_Transaction_States, Post_Finalization_Replay, Retrieval_Tool_Guardrails

Browse Source
This commit is contained in:
Cristiano Hoshikawa
2026-08-19 09:25:38 -03:00
parent 23d32bbcfc
commit 560e79d21b
89 changed files with 6261 additions and 864 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
docs/features/pt-BR/01_authentication.md Normal file
View File

@@ -0,0 +1,83 @@
# Autenticação
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `security/authentication.py`
---
### 1. O que é
Verifica quem pode acessar APIs, gateways e serviços protegidos antes que a requisição chegue ao agente.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
Cliente/Sistema
↓
Authentication Provider
↓
credencial válida?
├─ não → 401/nega acesso
└─ sim → principal autenticado → agente
```
### 4. Como funciona internamente
O framework contém uma abstração `AuthenticationProvider` e implementações para cenários diferentes. Entre as implementações atuais estão `NoAuthenticationProvider`, `DenyAuthenticationProvider`, `BasicAuthenticationProvider`, `ApiKeyAuthenticationProvider`, `StaticBearerAuthenticationProvider`, `JwtAuthenticationProvider`, `OAuth2IntrospectionAuthenticationProvider` e `TrustedProxyAuthenticationProvider`.
A autenticação produz um `AuthenticatedPrincipal` com `subject`, `scheme` e, quando aplicável, `claims`. A regra de negócio do agente não deve validar senha/token diretamente.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```python
from agent_framework.security.authentication import BasicAuthenticationProvider
provider = BasicAuthenticationProvider(
client_id="client-a",
secret_hash="pbkdf2_sha256:...",
)
result = await provider.authenticate(request)
if not result.authenticated:
# negar acesso
...
```
Segredos podem ser verificados em formato simples, SHA-256 ou PBKDF2; em produção, prefira hashes fortes e secret stores.
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Basic auth retornando 401: validar `Authorization: Basic ...` e o secret configurado.
- Confundir autenticação do usuário com `OCI_AUTH_MODE`: são problemas diferentes.
- Usar `NoAuthenticationProvider` em produção sem decisão explícita de arquitetura.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/security/authentication.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

92
docs/features/pt-BR/02_deterministic_transactional_workflow.md Normal file
View File

@@ -0,0 +1,92 @@
# Workflow Transacional Determinístico
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `workflows/runtime.py + mcp/tool_policy.py`
---
### 1. O que é
Garante que operações que alteram estado sigam passos previsíveis, com confirmação e controle de execução, em vez de depender da criatividade do LLM.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
Mensagem do cliente
↓
LLM entende intenção
↓
Tool policy = transactional
↓
Workflow determinístico
↓
confirmação
↓
execução controlada
↓
resultado
```
### 4. Como funciona internamente
O LLM pode ajudar a interpretar a intenção e extrair parâmetros, mas não deve decidir a sequência crítica de uma transação. O `ToolPolicyRegistry` classifica tools, e `operation_type: transactional` ativa a política transacional. O `WorkflowRuntime` executa o workflow, mantém estado e integra pause/resume e recuperação de erro.
A configuração `ENABLE_TRANSACTIONAL_WORKFLOWS` controla a capability global, e `WORKFLOWS_PATH` aponta para os YAMLs.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```yaml
tools:
cancelar_servico:
operation_type: transactional
requires_confirmation: true
```
```text
1. localizar serviço
2. validar elegibilidade
3. pedir confirmação
4. PAUSE
5. receber confirmação
6. RESUME
7. executar side effect
```
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Marcar uma tool de escrita como `read_only` elimina proteções transacionais.
- Reexecutar steps anteriores ao pause pode duplicar side effects; use o runtime oficial.
- Não use prompt como única garantia de confirmação.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/workflows/runtime.py`
- `libs/agent_framework/src/agent_framework/mcp/tool_policy.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

79
docs/features/pt-BR/03_domain_requested_llm_composition.md Normal file
View File

@@ -0,0 +1,79 @@
# Composição por LLM Solicitada pelo Domínio
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `runtime/agent_runtime.py`
---
### 1. O que é
Permite que a regra de negócio calcule o resultado e peça ao LLM apenas para redigir a resposta final.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
Regra de negócio calcula
↓
requires_llm_composition=true
↓
framework impede resposta MCP direta
↓
LLMProvider oficial
↓
redação natural
```
### 4. Como funciona internamente
O domínio retorna dados confiáveis e uma instrução de composição. O `AgentRuntimeMixin` detecta `requires_llm_composition` de forma recursiva no resultado da tool/workflow e não encerra a resposta pelo caminho direto de MCP. A composição segue pelo LLM oficial do agente, preservando profiles, tracing, usage e políticas do framework.
O LLM deve redigir; ele não deve recalcular valores nem decidir regras de negócio já resolvidas.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```json
{
"success": true,
"refund_amount": "38,00",
"requires_llm_composition": true,
"response_instruction": "Explique a devolução usando somente os valores calculados."
}
```
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Instrução muito aberta pode fazer o LLM adicionar conteúdo não autorizado.
- Não envie ao LLM a responsabilidade de recalcular valores determinísticos.
- Se não houver necessidade de redação livre, prefira resposta determinística direta.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

84
docs/features/pt-BR/04_domain_requested_rag.md Normal file
View File

@@ -0,0 +1,84 @@
# RAG Solicitado pelo Domínio
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `runtime/agent_runtime.py`
---
### 1. O que é
Permite que uma tool ou workflow declare que a resposta precisa consultar conhecimento externo, mesmo quando já existe resultado MCP.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
Tool/Workflow
↓
requires_rag=true
↓
rag_query / rag_queries
↓
RagService do framework
↓
Retrieval Guardrails
↓
LLM/resposta
```
### 4. Como funciona internamente
Normalmente o framework pode pular RAG quando MCP já trouxe informação suficiente (`SKIP_RAG_WHEN_MCP_SUFFICIENT`). Esta feature permite que o domínio substitua essa decisão para um caso específico. O resultado pode declarar `requires_rag`, `rag_query` ou `rag_queries`; o runtime usa essas queries como override e executa o `RagService`.
O domínio informa **o que precisa saber**. Ele não implementa cliente de vetor, retriever ou prompt RAG paralelo.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```json
{
"requires_rag": true,
"rag_queries": [
"Como cancelar YouTube Premium?",
"Como cancelar Aya Books?"
]
}
```
Configurações relacionadas incluem `RAG_TOP_K` e `SKIP_RAG_WHEN_MCP_SUFFICIENT`.
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Declarar RAG para fatos transacionais já resolvidos pela API pode aumentar custo e latência.
- Query genérica demais reduz relevância.
- Nunca confie no retrieval sem `Retrieval Guardrails` quando o dado influencia resposta crítica.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

84
docs/features/pt-BR/05_long_term_memory.md Normal file
View File

@@ -0,0 +1,84 @@
# Memória de Longo Prazo
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `memory/long_term_memory.py + memory/long_term_store.py`
---
### 1. O que é
Permite lembrar informações úteis entre sessões diferentes, sem depender do histórico completo de uma conversa.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
Sessão A
↓
extração de memória relevante
↓
Long Term Memory Store
↓
... dias depois ...
↓
Sessão B
↓
recupera contexto relevante
↓
agente
```
### 4. Como funciona internamente
A memória de longo prazo é diferente de histórico de mensagens e de checkpoint. Ela persiste fatos/preferências úteis e os recupera como contexto de uma nova sessão. O framework oferece providers `memory`, `sqlite`, `autonomous` e `oracle`.
Configurações importantes: `ENABLE_LONG_TERM_MEMORY`, `LONG_TERM_MEMORY_PROVIDER`, `LONG_TERM_MEMORY_MAX_CONTEXT_ITEMS`, `LONG_TERM_MEMORY_MIN_CONFIDENCE`, `LONG_TERM_MEMORY_AUTO_EXTRACT` e `LONG_TERM_MEMORY_INJECT_CONTEXT`.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```env
ENABLE_LONG_TERM_MEMORY=true
LONG_TERM_MEMORY_PROVIDER=oracle
LONG_TERM_MEMORY_MAX_CONTEXT_ITEMS=20
LONG_TERM_MEMORY_MIN_CONFIDENCE=0.70
LONG_TERM_MEMORY_AUTO_EXTRACT=true
LONG_TERM_MEMORY_INJECT_CONTEXT=true
```
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Não confundir LTM com replay de toda conversa.
- Memória irrelevante ou de baixa confiança não deveria ser injetada.
- Em múltiplas réplicas, prefira storage durável compartilhado em vez de memória local.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/memory/long_term_memory.py`
- `libs/agent_framework/src/agent_framework/memory/long_term_store.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

82
docs/features/pt-BR/06_offline_workflow_regression.md Normal file
View File

@@ -0,0 +1,82 @@
# Regressão Offline de Workflow
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `workflows/runtime.py + Tuning-Performance/Offline_Workflow_Regression`
---
### 1. O que é
Permite testar a lógica de workflows sem exigir toda a infraestrutura de produção.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
Teste
↓
backend determinístico explicitamente habilitado
↓
run → PAUSED
↓
resume → COMPLETED
↓
asserts de estado/side effects
```
### 4. Como funciona internamente
O `WorkflowRuntime` possui um caminho determinístico/offline **explicitamente opt-in para testes**. Quando `allow_deterministic_fallback=True`, esse backend é selecionado de forma explícita mesmo que LangGraph esteja instalado, garantindo regressões reproduzíveis entre máquinas e CI. Ele permite validar DSL, condições, pause/resume e proteção contra reexecução sem depender do comportamento interno do LangGraph, banco, OCI ou APIs externas.
O comportamento de produção continua usando LangGraph. O modo offline não deve virar fallback silencioso quando LangGraph falha ou está ausente em produção.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```text
run(workflow)
action_a = 1 execução
status = PAUSED
resume(workflow)
action_a continua com 1 execução
action_b = 1 execução
status = COMPLETED
```
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Usar o backend offline em produção mascara problemas reais.
- Mockar tanto que o teste deixa de validar a DSL real.
- Não verificar side effects anteriores ao pause pode esconder duplicações.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/workflows/runtime.py`
- `libs/agent_framework/src/agent_framework/Tuning-Performance/Offline_Workflow_Regression`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

83
docs/features/pt-BR/07_pause_resume_workflow.md Normal file
View File

@@ -0,0 +1,83 @@
# Pause
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `workflows/runtime.py + workflows/graph.py`
---
### 1. O que é
Permite interromper um workflow em um ponto seguro, persistir o estado e continuar depois com a resposta do usuário ou outro evento.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
Workflow
↓
ações prévias
↓
PAUSE
↓
checkpoint/estado
↓
nova mensagem
↓
RESUME
↓
ações seguintes
```
### 4. Como funciona internamente
`WorkflowRuntime` expõe `arun(...)` e `aresume(...)`. O nó de pause é separado da action anterior para evitar reexecutar side effects quando o workflow retoma. O mesmo `execution_id/thread_id` identifica a execução pausada e retomada.
O runtime suporta condições declarativas como `all`, `any`, `not`, `eq`, `neq` e `exists`, permitindo definir quando pausar ou continuar sem colocar lógica conversacional no prompt.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```text
status = await runtime.arun(...)
# status == PAUSED
status = await runtime.aresume(execution_id, input={"confirmed": true})
# status == COMPLETED
```
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Perder o `execution_id` impede retomar a execução correta.
- Reexecutar o workflow do zero após confirmação pode repetir side effects.
- Pause sem storage/checkpoint compartilhado é frágil em múltiplas réplicas.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/workflows/runtime.py`
- `libs/agent_framework/src/agent_framework/workflows/graph.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

76
docs/features/pt-BR/08_route_stickiness.md Normal file
View File

@@ -0,0 +1,76 @@
# Aderência de Rota
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `routing/enterprise_router.py + runtime/agent_runtime.py`
---
### 1. O que é
Evita que pequenas mensagens de continuação façam a conversa trocar de agente sem necessidade.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
mensagem atual
+ histórico curto
+ rota anterior
↓
continuidade semântica
↓
manter rota ou handoff
```
### 4. Como funciona internamente
Route Stickiness avalia se a nova mensagem continua semanticamente ligada ao assunto/agente atual. Isso reduz ping-pong de agentes em mensagens como “e esse valor?”, “sim”, “o segundo” ou “e no mês passado?”.
Configurações existentes incluem `ENABLE_ROUTE_STICKINESS`, `ROUTE_STICKINESS_LLM_PROFILE`, `ROUTE_STICKINESS_CONFIDENCE_THRESHOLD`, `ROUTE_STICKINESS_HISTORY_TURNS` e `ROUTE_STICKINESS_MAX_TOKENS`. A decisão pode permitir handoff quando há evidência suficiente de mudança de assunto.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```env
ENABLE_ROUTE_STICKINESS=true
ROUTE_STICKINESS_CONFIDENCE_THRESHOLD=0.90
ROUTE_STICKINESS_HISTORY_TURNS=2
ROUTE_STICKINESS_MAX_TOKENS=80
```
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Threshold muito baixo pode prender o cliente no agente errado.
- Threshold alto demais perde continuidade em mensagens curtas.
- Stickiness não deve bloquear handoff explícito quando a intenção realmente mudou.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/routing/enterprise_router.py`
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

77
docs/features/pt-BR/09_voice_interruption_replay.md Normal file
View File

@@ -0,0 +1,77 @@
# Replay em Interrupções de Voz
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `channels/interruption.py`
---
### 1. O que é
Decide se um áudio recebido durante a fala do agente representa uma nova intenção, um ruído/backchannel ou algo que deve apenas repetir/continuar a última fala.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
áudio durante fala
↓
InterruptionPolicy
├─ process → nova mensagem
├─ classify → classificador leve
└─ replay → última fala
```
### 4. Como funciona internamente
A política fica no framework, não no domínio. Ela diferencia sessão terminal, `idle_nudge`, fala não interrompível e fala potencialmente interrompível. Quando necessário, pode usar um classificador leve baseado no `LLMProvider`; quando a classificação falha, a política é conservadora e pode optar por replay.
O objetivo é evitar que “aham”, ruído, eco ou fragmentos residuais sejam tratados como uma nova intenção completa.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```text
Agente: "Sua fatura possui..."
Cliente: "aham"
→ replay/continua
Agente: "Sua fatura possui..."
Cliente: "espera, quero falar de outra coisa"
→ processa nova intenção
```
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Classificar todo ruído com LLM aumenta latência e custo.
- Permitir interrupção em fala transacional não interrompível pode corromper UX/estado.
- Replay deve usar uma fala real anterior, não um envelope técnico.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/channels/interruption.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

84
docs/features/pt-BR/10_workflow_error_recovery.md Normal file
View File

@@ -0,0 +1,84 @@
# Recuperação de Erro em Workflow
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `workflows/runtime.py`
---
### 1. O que é
Preserva o estado parcial de uma execução quando um passo posterior falha, permitindo entender o que já aconteceu e evitar repetir side effects.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
passo A ✅
passo B ✅
passo C ❌
↓
FAILED + snapshot parcial
↓
recovery decide o que pode continuar/repetir
```
### 4. Como funciona internamente
O runtime preserva o snapshot parcial do LangGraph quando uma etapa posterior falha e produz `error_details` genérico. Quando a exceção externa possui informações estruturadas, podem ser preservados status HTTP, body, número de tentativas, code e metadata.
A feature não significa “tentar tudo de novo”. Recuperação segura depende de conhecer o estado já executado, a idempotência e a natureza do erro.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```json
{
"status": "FAILED",
"error_details": {
"status": 503,
"attempts": 3,
"code": "UPSTREAM_UNAVAILABLE"
},
"state": {
"protocol_created": true,
"operation_completed": true,
"sms_sent": false
}
}
```
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Retry indiscriminado pode repetir transações.
- Se a exceção externa perde metadata, a recuperação fica menos precisa.
- Combine sempre com Durable Idempotency em side effects críticos.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/workflows/runtime.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

85
docs/features/pt-BR/11_clarification.md Normal file
View File

@@ -0,0 +1,85 @@
# Clarificação
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `runtime/agent_runtime.py`
---
### 1. O que é
Quando faltam dados ou uma tool encontra múltiplas opções, o framework pergunta ao usuário em vez de adivinhar.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
pedido ambíguo
↓
NEEDS_CLARIFICATION
↓
pergunta + opções
↓
usuário responde
↓
framework resolve
↓
retoma mesma tool/workflow
```
### 4. Como funciona internamente
O runtime suporta clarificação tanto de parâmetros faltantes quanto de resultados de tools. Para tool-result clarification, um resultado com `status: NEEDS_CLARIFICATION` pode trazer opções; o runtime persiste `pending_tool_clarification`, entra em `TOOL_RESULT_CLARIFICATION` e consegue resolver respostas por ordinal ou nome.
Depois da escolha, o framework reutiliza a mesma tool e injeta os argumentos resolvidos, evitando que o roteador trate a resposta curta como uma intenção nova.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```json
{
"status": "NEEDS_CLARIFICATION",
"question": "Qual serviço?",
"options": [
{"id": "tim_music", "label": "TIM Music"},
{"id": "hbo_max", "label": "HBO Max"}
]
}
```
Usuário: `o segundo` → `hbo_max`.
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Não descarte `pending_tool_clarification` entre turns.
- Uma resposta curta deve ser resolvida contra as opções antes do roteamento normal.
- Opções sem identificador/label consistente pioram a resolução.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

82
docs/features/pt-BR/12_durable_idempotency.md Normal file
View File

@@ -0,0 +1,82 @@
# Idempotência Durável
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `idempotency.py`
---
### 1. O que é
Impede que a mesma operação crítica seja executada duas vezes, inclusive quando outra réplica/pod recebe a repetição.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
requisição
↓
idempotency key
↓
store durável
├─ existe → retorna resultado anterior
└─ não existe → executa → persiste resultado
```
### 4. Como funciona internamente
`create_idempotency_store(settings, ...)` escolhe o backend conforme configuração/plataforma. O framework possui `IdempotencyStore` e `InMemoryIdempotencyStore`, mas produção distribuída deve preferir storage compartilhado. As configurações incluem `IDEMPOTENCY_PROVIDER`, `IDEMPOTENCY_REQUIRE_DURABLE` e `IDEMPOTENCY_TTL_SECONDS`.
Idempotência é diferente de retry: retry repete a tentativa; idempotência garante que a repetição não produza um novo side effect.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```text
Pod A recebe cancelamento
→ key=cliente:servico:operacao
→ executa
→ grava resultado
Pod A cai
Pod B recebe retry
→ mesma key
→ encontra resultado
→ NÃO cancela de novo
```
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Usar store em memória com múltiplos pods não é idempotência durável.
- Chave ampla demais pode bloquear operações legítimas; estreita demais permite duplicidade.
- TTL deve ser compatível com a janela real de retry/replay.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/idempotency.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

79
docs/features/pt-BR/13_dynamic_transaction_states.md Normal file
View File

@@ -0,0 +1,79 @@
# Estados Transacionais Dinâmicos
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `runtime/agent_runtime.py + mcp/tool_policy.py`
---
### 1. O que é
Permite criar estados de confirmação baseados no agente/domínio atual sem hardcode de todos os domínios dentro do framework.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
tool transactional
↓
agente/domínio atual
↓
WAITING_<PREFIX>_CONFIRMATION
↓
confirmação/rejeição
↓
estado seguinte
```
### 4. Como funciona internamente
Em vez de manter estados fixos como `WAITING_BILLING_CONFIRMATION`, `WAITING_PRODUCT_CONFIRMATION` etc. para cada domínio conhecido, o runtime deriva o prefixo do agente atual e gera o estado dinamicamente. A função interna de estado transacional mantém o framework genérico.
A classificação `operation_type` aceita `read_only`, `transactional`, `conversational` e `internal`; somente `transactional` entra no caminho de confirmação transacional.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```text
VasAgent + cancelar_vas
→ WAITING_VAS_CONFIRMATION
AddressAgent + alterar_endereco
→ WAITING_ADDRESS_CONFIRMATION
```
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Hardcode de estados no domínio reduz reutilização.
- Classificar uma tool como `conversational` não deve ativar confirmação transacional.
- Mudanças no identificador do agente podem mudar o prefixo; mantenha IDs estáveis.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
- `libs/agent_framework/src/agent_framework/mcp/tool_policy.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

80
docs/features/pt-BR/14_post_finalization_replay.md Normal file
View File

@@ -0,0 +1,80 @@
# Replay Após Finalização
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `channels/interruption.py + config/settings.py`
---
### 1. O que é
Evita que áudio residual ou mensagens tardias reabram uma sessão já finalizada.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
sessão terminal
↓
entrada residual
↓
policy detecta finalização
↓
replay última fala/fallback
↓
NÃO reabre LangGraph
```
### 4. Como funciona internamente
A política de interrupção verifica metadata de sessão terminal antes de tratar uma entrada como nova intenção. Quando há texto terminal disponível, usa `last_assistant_text`/`terminal_replay_text`; caso contrário, pode usar a mensagem configurada em `POST_FINALIZE_REPLAY_MESSAGE`.
O objetivo é proteger o fechamento lógico da sessão, especialmente em canais de voz onde pacotes de áudio podem chegar depois do evento de finalização.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```text
Agente: "Atendimento concluído."
→ sessão finalizada
chega fragmento: "ã..."
→ replay "Atendimento concluído."
→ nenhum routing / tool / LLM novo
```
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Se o estado terminal não for persistido, outra réplica pode reabrir a jornada.
- Não use replay técnico/JSON como fala do cliente.
- Essa feature não substitui política de nova sessão intencional.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/channels/interruption.py`
- `libs/agent_framework/src/agent_framework/config/settings.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

86
docs/features/pt-BR/15_retrieval_tool_guardrails.md Normal file
View File

@@ -0,0 +1,86 @@
# Guardrails de Retrieval e Tools
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
**Implementação principal:** `guardrails/pipeline.py + guardrails/rails.py`
---
### 1. O que é
Aplica proteção não apenas na mensagem do usuário e na resposta final, mas também no conhecimento recuperado por RAG e nos argumentos/resultados de ferramentas.
### 2. Problema que resolve
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
### 3. Fluxo simplificado
```text
Usuário
↓
Input Guardrails
↓
RAG → Retrieval Guardrails
↓
LLM/Tool call → Tool Guardrails
↓
API
↓
Output Guardrails
```
### 4. Como funciona internamente
O framework possui stages distintos de guardrails. Para retrieval, rails como `RAGSEC` e `RET_REL` podem validar segurança e relevância do conteúdo recuperado. Para tools, `TOOL_VAL` valida o uso/argumentos antes ou ao redor da execução.
As configurações globais incluem `ENABLE_INPUT_GUARDRAILS`, `ENABLE_OUTPUT_GUARDRAILS`, `ENABLE_PARALLEL_GUARDRAILS`, `GUARDRAILS_FAIL_FAST` e `GUARDRAILS_CONFIG_PATH`. O YAML é a fonte de verdade dos rails ativados por agente.
### 5. Como ativar/configurar
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
### 6. Exemplo
```yaml
retrieval:
rails:
- RAGSEC
- RET_REL
tool:
rails:
- TOOL_VAL
```
Exemplo: a pergunta é sobre cancelamento de um serviço, mas o RAG retorna documentação de modem. `RET_REL` pode rejeitar o contexto antes que ele seja usado na resposta.
### 7. Telemetria e observabilidade
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
### 8. Como testar
1. Crie um teste unitário do comportamento principal.
2. Crie um teste de integração do runtime quando houver estado entre turns.
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
5. Em produção, valide também telemetria e correlação de IDs.
### 9. Erros comuns
- Ter a implementação do rail não significa que ele está ativo: confira `guardrails.yaml`.
- Fail-fast deve ser escolhido conscientemente para cada stage.
- Tool guardrail não substitui validação de negócio dentro da própria API/action.
### 10. Relação com outras features
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
### 11. Referências no repositório
- `libs/agent_framework/src/agent_framework/guardrails/pipeline.py`
- `libs/agent_framework/src/agent_framework/guardrails/rails.py`
- `Tuning-Performance/`
- `Documentacao/`
- `libs/agent_framework/docs/`

19
docs/features/pt-BR/README.md Normal file
View File

@@ -0,0 +1,19 @@
# Feature Guides — Português (PT-BR)
Documentação das principais features do `agent_framework_oci`.
- [Autenticação](01_authentication.md)
- [Workflow Transacional Determinístico](02_deterministic_transactional_workflow.md)
- [Composição por LLM Solicitada pelo Domínio](03_domain_requested_llm_composition.md)
- [RAG Solicitado pelo Domínio](04_domain_requested_rag.md)
- [Memória de Longo Prazo](05_long_term_memory.md)
- [Regressão Offline de Workflow](06_offline_workflow_regression.md)
- [Pause](07_pause_resume_workflow.md)
- [Aderência de Rota](08_route_stickiness.md)
- [Replay em Interrupções de Voz](09_voice_interruption_replay.md)
- [Recuperação de Erro em Workflow](10_workflow_error_recovery.md)
- [Clarificação](11_clarification.md)
- [Idempotência Durável](12_durable_idempotency.md)
- [Estados Transacionais Dinâmicos](13_dynamic_transaction_states.md)
- [Replay Após Finalização](14_post_finalization_replay.md)
- [Guardrails de Retrieval e Tools](15_retrieval_tool_guardrails.md)