mirror of
https://github.com/hoshikawa2/agent_platform_oci.git
synced 2026-09-07 10:13:46 +00:00
bugfixes: transaction parameter collector, generic formatting messages, guardrails, prompts. Testing contas
This commit is contained in:
151
docs/features/08_route_stickiness.md
Normal file
151
docs/features/08_route_stickiness.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# Aderência de Rota / Route Stickiness
|
||||
|
||||
> Feature do `agent_framework_oci` — guia bilíngue PT-BR / EN.
|
||||
|
||||
**Implementação principal / Main implementation:** `routing/enterprise_router.py + runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
## Português (PT-BR)
|
||||
|
||||
### 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/`
|
||||
|
||||
---
|
||||
|
||||
## English (EN)
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Prevents short follow-up messages from unnecessarily switching the conversation to another agent.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
current message
|
||||
+ short history
|
||||
+ previous route
|
||||
↓
|
||||
semantic continuity
|
||||
↓
|
||||
keep route or handoff
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
Route Stickiness evaluates whether a new message is semantically continuous with the current subject/agent. It reduces agent ping-pong for messages such as “what about that amount?”, “yes”, “the second one”, or “and last month?”.
|
||||
|
||||
Existing settings include `ENABLE_ROUTE_STICKINESS`, `ROUTE_STICKINESS_LLM_PROFILE`, `ROUTE_STICKINESS_CONFIDENCE_THRESHOLD`, `ROUTE_STICKINESS_HISTORY_TURNS`, and `ROUTE_STICKINESS_MAX_TOKENS`. The decision may still allow handoff when there is enough evidence of a topic change.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```env
|
||||
ENABLE_ROUTE_STICKINESS=true
|
||||
ROUTE_STICKINESS_CONFIDENCE_THRESHOLD=0.90
|
||||
ROUTE_STICKINESS_HISTORY_TURNS=2
|
||||
ROUTE_STICKINESS_MAX_TOKENS=80
|
||||
```
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- A threshold that is too low may trap the user on the wrong agent.
|
||||
- A threshold that is too high may lose continuity on short follow-ups.
|
||||
- Stickiness should not block explicit handoff when the user clearly changes intent.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `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/`
|
||||
Reference in New Issue
Block a user