Projeto do Agent Contas ORACLE
This commit is contained in:
83
agent_framework_oci/docs/features/en/01_authentication.md
Normal file
83
agent_framework_oci/docs/features/en/01_authentication.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# Authentication
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `security/authentication.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Checks who may access protected APIs, gateways, and services before the request reaches the 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
|
||||
Client/System
|
||||
↓
|
||||
Authentication Provider
|
||||
↓
|
||||
valid credential?
|
||||
├─ no → 401/deny
|
||||
└─ yes → authenticated principal → agent
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The framework exposes an `AuthenticationProvider` abstraction with multiple implementations. Current providers include `NoAuthenticationProvider`, `DenyAuthenticationProvider`, `BasicAuthenticationProvider`, `ApiKeyAuthenticationProvider`, `StaticBearerAuthenticationProvider`, `JwtAuthenticationProvider`, `OAuth2IntrospectionAuthenticationProvider`, and `TrustedProxyAuthenticationProvider`.
|
||||
|
||||
Authentication produces an `AuthenticatedPrincipal` containing `subject`, `scheme`, and optional `claims`. Domain code should not validate credentials directly.
|
||||
|
||||
### 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
|
||||
|
||||
```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:
|
||||
# deny access
|
||||
...
|
||||
```
|
||||
|
||||
Secrets may be verified as plain, SHA-256, or PBKDF2 values; for production, prefer strong hashes and managed secret stores.
|
||||
|
||||
### 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
|
||||
|
||||
- Basic auth returns 401: validate the `Authorization: Basic ...` header and configured secret.
|
||||
- Do not confuse API authentication with `OCI_AUTH_MODE`; they solve different problems.
|
||||
- Avoid `NoAuthenticationProvider` in production unless explicitly accepted by architecture.
|
||||
|
||||
### 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/security/authentication.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,92 @@
|
||||
# Deterministic Transactional Workflow
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `workflows/runtime.py + mcp/tool_policy.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Ensures state-changing operations follow predictable steps with confirmation and execution control instead of depending on LLM creativity.
|
||||
|
||||
### 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
|
||||
Customer message
|
||||
↓
|
||||
LLM understands intent
|
||||
↓
|
||||
Tool policy = transactional
|
||||
↓
|
||||
Deterministic workflow
|
||||
↓
|
||||
confirmation
|
||||
↓
|
||||
controlled execution
|
||||
↓
|
||||
result
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The LLM may help interpret intent and extract parameters, but it should not decide the critical sequence of a transaction. `ToolPolicyRegistry` classifies tools, and `operation_type: transactional` activates transactional behavior. `WorkflowRuntime` executes the workflow, preserves state, and integrates pause/resume and error recovery.
|
||||
|
||||
`ENABLE_TRANSACTIONAL_WORKFLOWS` controls the capability globally, while `WORKFLOWS_PATH` points to workflow YAML files.
|
||||
|
||||
### 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
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
cancel_service:
|
||||
operation_type: transactional
|
||||
requires_confirmation: true
|
||||
```
|
||||
|
||||
```text
|
||||
1. locate service
|
||||
2. validate eligibility
|
||||
3. ask for confirmation
|
||||
4. PAUSE
|
||||
5. receive confirmation
|
||||
6. RESUME
|
||||
7. execute side effect
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
- Marking a write tool as `read_only` bypasses transactional protections.
|
||||
- Re-running steps before a pause can duplicate side effects; use the official runtime.
|
||||
- Do not use prompts as the only confirmation guarantee.
|
||||
|
||||
### 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/workflows/runtime.py`
|
||||
- `libs/agent_framework/src/agent_framework/mcp/tool_policy.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,79 @@
|
||||
# Domain Requested LLM Composition
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Lets domain logic compute the authoritative result and ask the LLM only to compose the final user-facing response.
|
||||
|
||||
### 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
|
||||
Domain logic computes
|
||||
↓
|
||||
requires_llm_composition=true
|
||||
↓
|
||||
framework prevents direct MCP answer
|
||||
↓
|
||||
official LLMProvider
|
||||
↓
|
||||
natural-language response
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The domain returns authoritative data plus a composition instruction. `AgentRuntimeMixin` recursively detects `requires_llm_composition` in tool/workflow results and avoids terminating through the direct MCP-answer path. Composition then uses the agent's official LLM provider, preserving profiles, tracing, usage accounting, and framework policies.
|
||||
|
||||
The LLM should compose language, not recalculate values or override already-resolved business rules.
|
||||
|
||||
### 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
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"refund_amount": "38.00",
|
||||
"requires_llm_composition": true,
|
||||
"response_instruction": "Explain the refund using only the computed values."
|
||||
}
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
- An overly broad instruction may let the LLM add unauthorized content.
|
||||
- Do not delegate deterministic calculations back to the LLM.
|
||||
- If free-form wording is unnecessary, prefer a deterministic direct response.
|
||||
|
||||
### 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/runtime/agent_runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,84 @@
|
||||
# Domain Requested RAG
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Allows a tool or workflow to declare that external knowledge retrieval is required even when an MCP result already exists.
|
||||
|
||||
### 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
|
||||
Tool/Workflow
|
||||
↓
|
||||
requires_rag=true
|
||||
↓
|
||||
rag_query / rag_queries
|
||||
↓
|
||||
framework RagService
|
||||
↓
|
||||
Retrieval Guardrails
|
||||
↓
|
||||
LLM/response
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
Normally the framework may skip RAG when MCP already provides sufficient data (`SKIP_RAG_WHEN_MCP_SUFFICIENT`). This feature lets the domain override that decision for a specific case. A result may declare `requires_rag`, `rag_query`, or `rag_queries`; the runtime uses those queries as overrides and invokes `RagService`.
|
||||
|
||||
The domain declares **what knowledge is needed**. It does not implement its own vector client, retriever, or parallel RAG prompt stack.
|
||||
|
||||
### 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
|
||||
|
||||
```json
|
||||
{
|
||||
"requires_rag": true,
|
||||
"rag_queries": [
|
||||
"How to cancel YouTube Premium?",
|
||||
"How to cancel Aya Books?"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Related settings include `RAG_TOP_K` and `SKIP_RAG_WHEN_MCP_SUFFICIENT`.
|
||||
|
||||
### 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
|
||||
|
||||
- Requesting RAG for transactional facts already resolved by an API adds unnecessary cost and latency.
|
||||
- Queries that are too broad reduce relevance.
|
||||
- Do not trust retrieved content for critical responses without Retrieval Guardrails.
|
||||
|
||||
### 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/runtime/agent_runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
84
agent_framework_oci/docs/features/en/05_long_term_memory.md
Normal file
84
agent_framework_oci/docs/features/en/05_long_term_memory.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# Long Term Memory
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `memory/long_term_memory.py + memory/long_term_store.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Allows useful information to persist across different sessions without depending on the full transcript of a previous conversation.
|
||||
|
||||
### 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
|
||||
Session A
|
||||
↓
|
||||
extract relevant memory
|
||||
↓
|
||||
Long Term Memory Store
|
||||
↓
|
||||
... days later ...
|
||||
↓
|
||||
Session B
|
||||
↓
|
||||
retrieve relevant context
|
||||
↓
|
||||
agent
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
Long-term memory is different from message history and checkpoints. It persists useful facts/preferences and retrieves them as context for a future session. The framework supports `memory`, `sqlite`, `autonomous`, and `oracle` providers.
|
||||
|
||||
Important settings include `ENABLE_LONG_TERM_MEMORY`, `LONG_TERM_MEMORY_PROVIDER`, `LONG_TERM_MEMORY_MAX_CONTEXT_ITEMS`, `LONG_TERM_MEMORY_MIN_CONFIDENCE`, `LONG_TERM_MEMORY_AUTO_EXTRACT`, and `LONG_TERM_MEMORY_INJECT_CONTEXT`.
|
||||
|
||||
### 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_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. 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
|
||||
|
||||
- Do not confuse LTM with replaying the entire transcript.
|
||||
- Irrelevant or low-confidence memories should not be injected.
|
||||
- For multiple replicas, prefer shared durable storage over local memory.
|
||||
|
||||
### 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/memory/long_term_memory.py`
|
||||
- `libs/agent_framework/src/agent_framework/memory/long_term_store.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,82 @@
|
||||
# Offline Workflow Regression
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `workflows/runtime.py + Tuning-Performance/Offline_Workflow_Regression`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Allows workflow logic to be regression-tested without requiring the full production infrastructure.
|
||||
|
||||
### 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
|
||||
Test
|
||||
↓
|
||||
explicit deterministic test backend
|
||||
↓
|
||||
run → PAUSED
|
||||
↓
|
||||
resume → COMPLETED
|
||||
↓
|
||||
state/side-effect assertions
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
`WorkflowRuntime` includes an **explicitly opt-in deterministic/offline test backend**. When `allow_deterministic_fallback=True`, this backend is explicitly selected even if LangGraph is installed, keeping regression results reproducible across developer machines and CI. It can validate DSL rules, conditions, pause/resume behavior, and duplicate-execution protection without depending on LangGraph internals, a database, OCI, or external APIs.
|
||||
|
||||
Production behavior still uses LangGraph. Offline mode must never become a silent fallback when LangGraph fails or is unavailable in production.
|
||||
|
||||
### 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
|
||||
|
||||
```text
|
||||
run(workflow)
|
||||
action_a = executed once
|
||||
status = PAUSED
|
||||
|
||||
resume(workflow)
|
||||
action_a remains executed once
|
||||
action_b = executed once
|
||||
status = COMPLETED
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
- Using the offline backend in production hides real issues.
|
||||
- Over-mocking can stop the test from validating real DSL behavior.
|
||||
- Failing to assert pre-pause side effects may hide duplicate execution.
|
||||
|
||||
### 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/workflows/runtime.py`
|
||||
- `libs/agent_framework/src/agent_framework/Tuning-Performance/Offline_Workflow_Regression`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,83 @@
|
||||
# Resume de Workflow / Pause / Resume Workflow
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `workflows/runtime.py + workflows/graph.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Allows a workflow to stop at a safe point, persist state, and continue later using user input or another event.
|
||||
|
||||
### 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
|
||||
Workflow
|
||||
↓
|
||||
pre-pause actions
|
||||
↓
|
||||
PAUSE
|
||||
↓
|
||||
checkpoint/state
|
||||
↓
|
||||
new message
|
||||
↓
|
||||
RESUME
|
||||
↓
|
||||
remaining actions
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
`WorkflowRuntime` exposes `arun(...)` and `aresume(...)`. The pause node is separated from the preceding action so previous side effects are not executed again on resume. The same `execution_id/thread_id` identifies the paused and resumed execution.
|
||||
|
||||
The runtime supports declarative conditions such as `all`, `any`, `not`, `eq`, `neq`, and `exists`, so pause/continue decisions do not need to live in the prompt.
|
||||
|
||||
### 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
|
||||
|
||||
```text
|
||||
status = await runtime.arun(...)
|
||||
# status == PAUSED
|
||||
|
||||
status = await runtime.aresume(execution_id, input={"confirmed": true})
|
||||
# status == COMPLETED
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
- Losing the `execution_id` prevents resuming the right execution.
|
||||
- Restarting the workflow from scratch after confirmation may duplicate side effects.
|
||||
- Pause without shared checkpoint/state storage is fragile across multiple replicas.
|
||||
|
||||
### 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/workflows/runtime.py`
|
||||
- `libs/agent_framework/src/agent_framework/workflows/graph.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
76
agent_framework_oci/docs/features/en/08_route_stickiness.md
Normal file
76
agent_framework_oci/docs/features/en/08_route_stickiness.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Route Stickiness
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `routing/enterprise_router.py + runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 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/`
|
||||
@@ -0,0 +1,77 @@
|
||||
# Voice Interruption Replay
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `channels/interruption.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Decides whether audio received while the agent is speaking represents a new intent, a backchannel/noise event, or something that should simply replay/continue the previous speech.
|
||||
|
||||
### 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
|
||||
audio during speech
|
||||
↓
|
||||
InterruptionPolicy
|
||||
├─ process → new message
|
||||
├─ classify → lightweight classifier
|
||||
└─ replay → previous speech
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The policy lives in the framework rather than domain code. It distinguishes terminal sessions, `idle_nudge`, non-interruptible speech, and potentially interruptible speech. When needed, it may use a lightweight classifier backed by `LLMProvider`; on classification failure, it can fail safely to replay.
|
||||
|
||||
The goal is to prevent “uh-huh”, noise, echo, or residual audio fragments from being interpreted as a full new intent.
|
||||
|
||||
### 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
|
||||
|
||||
```text
|
||||
Agent: "Your invoice contains..."
|
||||
User: "uh-huh"
|
||||
→ replay/continue
|
||||
|
||||
Agent: "Your invoice contains..."
|
||||
User: "wait, I want to ask something else"
|
||||
→ process new intent
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
- Sending every noise fragment to an LLM increases latency and cost.
|
||||
- Allowing interruption during non-interruptible transactional speech may corrupt UX/state.
|
||||
- Replay should use a real previous utterance, not a technical envelope.
|
||||
|
||||
### 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/channels/interruption.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,84 @@
|
||||
# Workflow Error Recovery
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `workflows/runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Preserves partial execution state when a later step fails, making it possible to know what already happened and avoid repeating side effects.
|
||||
|
||||
### 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
|
||||
step A ✅
|
||||
step B ✅
|
||||
step C ❌
|
||||
↓
|
||||
FAILED + partial snapshot
|
||||
↓
|
||||
recovery decides what may continue/retry
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The runtime preserves the partial LangGraph snapshot when a later step fails and produces generic `error_details`. When an external exception provides structured information, HTTP status, body, attempt count, code, and metadata may be preserved.
|
||||
|
||||
This feature does not mean “retry everything”. Safe recovery depends on knowing what already executed, idempotency guarantees, and the nature of the failure.
|
||||
|
||||
### 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
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "FAILED",
|
||||
"error_details": {
|
||||
"status": 503,
|
||||
"attempts": 3,
|
||||
"code": "UPSTREAM_UNAVAILABLE"
|
||||
},
|
||||
"state": {
|
||||
"protocol_created": true,
|
||||
"operation_completed": true,
|
||||
"sms_sent": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
- Blind retries may repeat transactions.
|
||||
- If external exceptions discard metadata, recovery becomes less precise.
|
||||
- Always combine with Durable Idempotency for critical side effects.
|
||||
|
||||
### 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/workflows/runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
85
agent_framework_oci/docs/features/en/11_clarification.md
Normal file
85
agent_framework_oci/docs/features/en/11_clarification.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# Clarification
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
When required information is missing or a tool finds multiple options, the framework asks the user instead of guessing.
|
||||
|
||||
### 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
|
||||
ambiguous request
|
||||
↓
|
||||
NEEDS_CLARIFICATION
|
||||
↓
|
||||
question + options
|
||||
↓
|
||||
user answers
|
||||
↓
|
||||
framework resolves
|
||||
↓
|
||||
resume same tool/workflow
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The runtime supports clarification for both missing parameters and ambiguous tool results. For tool-result clarification, a result with `status: NEEDS_CLARIFICATION` may include options; the runtime persists `pending_tool_clarification`, moves to `TOOL_RESULT_CLARIFICATION`, and can resolve responses by ordinal or name.
|
||||
|
||||
After selection, the framework reuses the same tool and injects resolved arguments, preventing the router from treating a short reply as a brand-new intent.
|
||||
|
||||
### 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
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "NEEDS_CLARIFICATION",
|
||||
"question": "Which service?",
|
||||
"options": [
|
||||
{"id": "tim_music", "label": "TIM Music"},
|
||||
{"id": "hbo_max", "label": "HBO Max"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
User: `the second one` → `hbo_max`.
|
||||
|
||||
### 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
|
||||
|
||||
- Do not discard `pending_tool_clarification` between turns.
|
||||
- A short answer should be resolved against pending options before normal routing.
|
||||
- Options without stable identifiers/labels reduce resolution quality.
|
||||
|
||||
### 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/runtime/agent_runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,82 @@
|
||||
# Durable Idempotency
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `idempotency.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Prevents the same critical operation from executing twice, including when a retry lands on another replica/pod.
|
||||
|
||||
### 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
|
||||
request
|
||||
↓
|
||||
idempotency key
|
||||
↓
|
||||
durable store
|
||||
├─ exists → return previous result
|
||||
└─ missing → execute → persist result
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
`create_idempotency_store(settings, ...)` chooses a backend according to configuration/platform. The framework provides `IdempotencyStore` and `InMemoryIdempotencyStore`, but distributed production should prefer shared storage. Settings include `IDEMPOTENCY_PROVIDER`, `IDEMPOTENCY_REQUIRE_DURABLE`, and `IDEMPOTENCY_TTL_SECONDS`.
|
||||
|
||||
Idempotency is different from retry: retry repeats an attempt; idempotency guarantees that repetition does not create another side effect.
|
||||
|
||||
### 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
|
||||
|
||||
```text
|
||||
Pod A receives cancellation
|
||||
→ key=customer:service:operation
|
||||
→ executes
|
||||
→ stores result
|
||||
|
||||
Pod A crashes
|
||||
|
||||
Pod B receives retry
|
||||
→ same key
|
||||
→ finds stored result
|
||||
→ DOES NOT cancel again
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
- An in-memory store across multiple pods is not durable idempotency.
|
||||
- A key that is too broad may block legitimate operations; too narrow may allow duplicates.
|
||||
- TTL should match the real retry/replay window.
|
||||
|
||||
### 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/idempotency.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,79 @@
|
||||
# Dynamic Transaction States
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `runtime/agent_runtime.py + mcp/tool_policy.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Allows confirmation states to be derived from the current agent/domain instead of hardcoding every business domain into the framework.
|
||||
|
||||
### 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
|
||||
transactional tool
|
||||
↓
|
||||
current agent/domain
|
||||
↓
|
||||
WAITING_<PREFIX>_CONFIRMATION
|
||||
↓
|
||||
confirm/reject
|
||||
↓
|
||||
next state
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
Instead of maintaining fixed states such as `WAITING_BILLING_CONFIRMATION`, `WAITING_PRODUCT_CONFIRMATION`, and so on for every known domain, the runtime derives a prefix from the current agent and builds the confirmation state dynamically. This keeps the framework generic.
|
||||
|
||||
`operation_type` accepts `read_only`, `transactional`, `conversational`, and `internal`; only `transactional` enters the transactional confirmation path.
|
||||
|
||||
### 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
|
||||
|
||||
```text
|
||||
VasAgent + cancel_vas
|
||||
→ WAITING_VAS_CONFIRMATION
|
||||
|
||||
AddressAgent + change_address
|
||||
→ WAITING_ADDRESS_CONFIRMATION
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
- Hardcoding states in domain code reduces reuse.
|
||||
- Classifying a tool as `conversational` should not trigger transactional confirmation.
|
||||
- Changing agent identifiers may change state prefixes; keep IDs stable.
|
||||
|
||||
### 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/runtime/agent_runtime.py`
|
||||
- `libs/agent_framework/src/agent_framework/mcp/tool_policy.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,80 @@
|
||||
# Post Finalization Replay
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `channels/interruption.py + config/settings.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Prevents residual audio or late messages from reopening a session that has already been finalized.
|
||||
|
||||
### 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
|
||||
terminal session
|
||||
↓
|
||||
residual input
|
||||
↓
|
||||
policy detects finalization
|
||||
↓
|
||||
replay last utterance/fallback
|
||||
↓
|
||||
DO NOT reopen LangGraph
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The interruption policy checks terminal-session metadata before treating an input as a new intent. When terminal speech is available, it uses `last_assistant_text`/`terminal_replay_text`; otherwise it may use `POST_FINALIZE_REPLAY_MESSAGE`.
|
||||
|
||||
The purpose is to protect the logical end of a session, especially on voice channels where audio packets may arrive after the finalization event.
|
||||
|
||||
### 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
|
||||
|
||||
```text
|
||||
Agent: "The interaction is complete."
|
||||
→ session finalized
|
||||
|
||||
late fragment arrives: "uh..."
|
||||
→ replay "The interaction is complete."
|
||||
→ no new routing / tool / LLM call
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
- If terminal state is not persisted, another replica may reopen the journey.
|
||||
- Do not replay technical/JSON envelopes as user-facing speech.
|
||||
- This feature does not replace an intentional new-session policy.
|
||||
|
||||
### 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/channels/interruption.py`
|
||||
- `libs/agent_framework/src/agent_framework/config/settings.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,86 @@
|
||||
# Retrieval / Tool Guardrails
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `guardrails/pipeline.py + guardrails/rails.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Applies safety and validation not only to user input and final output, but also to RAG-retrieved knowledge and tool arguments/results.
|
||||
|
||||
### 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
|
||||
User
|
||||
↓
|
||||
Input Guardrails
|
||||
↓
|
||||
RAG → Retrieval Guardrails
|
||||
↓
|
||||
LLM/Tool call → Tool Guardrails
|
||||
↓
|
||||
API
|
||||
↓
|
||||
Output Guardrails
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The framework has distinct guardrail stages. For retrieval, rails such as `RAGSEC` and `RET_REL` can validate retrieved-content safety and relevance. For tools, `TOOL_VAL` validates usage/arguments before or around execution.
|
||||
|
||||
Global settings include `ENABLE_INPUT_GUARDRAILS`, `ENABLE_OUTPUT_GUARDRAILS`, `ENABLE_PARALLEL_GUARDRAILS`, `GUARDRAILS_FAIL_FAST`, and `GUARDRAILS_CONFIG_PATH`. The agent YAML is the source of truth for enabled rails.
|
||||
|
||||
### 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
|
||||
|
||||
```yaml
|
||||
retrieval:
|
||||
rails:
|
||||
- RAGSEC
|
||||
- RET_REL
|
||||
|
||||
tool:
|
||||
rails:
|
||||
- TOOL_VAL
|
||||
```
|
||||
|
||||
Example: the question concerns canceling a service, but RAG retrieves modem documentation. `RET_REL` can reject that context before it is used in the answer.
|
||||
|
||||
### 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
|
||||
|
||||
- Having a rail implementation does not mean it is enabled: check `guardrails.yaml`.
|
||||
- Fail-fast behavior should be chosen intentionally for each stage.
|
||||
- Tool guardrails do not replace business validation inside the API/action itself.
|
||||
|
||||
### 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/guardrails/pipeline.py`
|
||||
- `libs/agent_framework/src/agent_framework/guardrails/rails.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
19
agent_framework_oci/docs/features/en/README.md
Normal file
19
agent_framework_oci/docs/features/en/README.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Feature Guides — English (EN)
|
||||
|
||||
Documentation for the main `agent_framework_oci` features.
|
||||
|
||||
- [Authentication](01_authentication.md)
|
||||
- [Deterministic Transactional Workflow](02_deterministic_transactional_workflow.md)
|
||||
- [Domain Requested LLM Composition](03_domain_requested_llm_composition.md)
|
||||
- [Domain Requested RAG](04_domain_requested_rag.md)
|
||||
- [Long Term Memory](05_long_term_memory.md)
|
||||
- [Offline Workflow Regression](06_offline_workflow_regression.md)
|
||||
- [Resume de Workflow / Pause / Resume Workflow](07_pause_resume_workflow.md)
|
||||
- [Route Stickiness](08_route_stickiness.md)
|
||||
- [Voice Interruption Replay](09_voice_interruption_replay.md)
|
||||
- [Workflow Error Recovery](10_workflow_error_recovery.md)
|
||||
- [Clarification](11_clarification.md)
|
||||
- [Durable Idempotency](12_durable_idempotency.md)
|
||||
- [Dynamic Transaction States](13_dynamic_transaction_states.md)
|
||||
- [Post Finalization Replay](14_post_finalization_replay.md)
|
||||
- [Retrieval / Tool Guardrails](15_retrieval_tool_guardrails.md)
|
||||
Reference in New Issue
Block a user