First commit

2026-10-30 22:04:44 -03:00
commit 645ecdfb07
2794 changed files with 282545 additions and 0 deletions
--- a/specs/en/SPEC-010-Agent-Development.md
+++ b/specs/en/SPEC-010-Agent-Development.md
@@ -0,0 +1,333 @@
+# SPEC-010 — Agent Development
+
+## Scope
+
+Esta SPEC Defines o Standard for Creation of Agents usando templates, Configuration YAML, BusinessContext, MCP, guardrails, judges, RAG, Memory, Observability and evals.
+
+## structure of the Template
+
+```text
+templates/agent_template_backend/
+├── app/
+│   ├── main.py
+│   ├── state.py
+│   ├── workflows/
+│   │   └── agent_graph.py
+│   ├── agents/
+│   │   ├── runtime.py
+│   │   └── domain_agent.py
+│   └── examples/
+├── config/
+│   ├── agents.yaml
+│   ├── routing.yaml
+│   ├── tools.yaml
+│   ├── mcp_servers.yaml
+│   ├── mcp_parameter_mapping.yaml
+│   ├── identity.yaml
+│   ├── guardrails.yaml
+│   ├── judges.yaml
+│   ├── prompt_policy.yaml
+│   └── agents/<agent_id>/
+├── Dockerfile
+├── requirements.txt
+└── .env.example
+```
+
+## Responsibilities of the Framework
+
+- LangGraph;
+- Memory;
+- checkpoint;
+- Session;
+- router;
+- supervisor;
+- guardrails;
+- judges;
+- telemetry;
+- MCP integration;
+- RAG genérico;
+- cache;
+- providers LLM;
+- event bus.
+
+## Responsibilities of the Agent
+
+- prompts of Domain;
+- Rules of negócio;
+- schemas específicos;
+- Decision of uso of evidências;
+- handling of fields required;
+- Messages of Domain;
+- ICs of jornada;
+- datasets of eval específicos.
+
+## Registration of the Agent
+
+```yaml
+agents:
+  financeiro_agent:
+    enabled: true
+    description: "Agente financeiro"
+    profile: financeiro_agent
+    rag_namespace: financeiro
+    allowed_tools:
+      - consultar_fatura
+      - consultar_pagamentos
+```
+
+## Routing
+
+```yaml
+intents:
+  financeiro_consulta_fatura:
+    route: financeiro_agent
+    keywords:
+      - fatura
+      - boleto
+      - cobrança
+    mcp_tools:
+      - consultar_fatura
+```
+
+## Tool Mapping
+
+```yaml
+tools:
+  consultar_fatura:
+    map:
+      customer_key: msisdn
+      contract_key: invoice_id
+      interaction_key: ura_call_id
+      session_key: session_id
+```
+
+## Classe of Agent
+
+```python
+class FinanceiroAgent(AgentRuntimeMixin):
+    name = "financeiro_agent"
+
+    def __init__(
+        self,
+        llm,
+        telemetry=None,
+        tool_router=None,
+        rag_service=None,
+        cache=None,
+        settings=None,
+        observer=None,
+        memory=None,
+        summary_memory=None,
+    ):
+        self.llm = llm
+        self.telemetry = telemetry
+        self.tool_router = tool_router
+        self.rag_service = rag_service
+        self.cache = cache
+        self.settings = settings
+        self.observer = observer
+        self.memory = memory
+        self.summary_memory = summary_memory
+
+    async def run(self, state):
+        await self._emit_ic("IC.FINANCEIRO_AGENT_STARTED", state, {})
+        tool_context = await self._collect_mcp_context(state)
+        rag_context, rag_metadata = await self._retrieve_rag_context(state)
+        response = await self._invoke_llm_cached(
+            state,
+            "FinanceiroAgent",
+            [
+                {"role": "system", "content": "Você é um agente financeiro."},
+                {"role": "user", "content": state.get("sanitized_input") or state.get("user_text", "")},
+            ],
+        )
+        await self._emit_ic("IC.FINANCEIRO_AGENT_COMPLETED", state, {})
+        return {
+            "response_text": response,
+            "mcp_results": tool_context,
+            "rag_metadata": rag_metadata,
+        }
+```
+
+## Ordem of Confiança of the Data
+
+1. `tool_arguments`
+2. `business_context`
+3. `context`
+4. `session.metadata`
+5. `state`
+6. extração complementar of the texto
+
+## Prompt Policy
+
+```yaml
+prompt_policy:
+  system_prompt_path: prompts/system.md
+  response_style: concise
+  require_evidence: true
+  allow_tool_usage: true
+```
+
+## Guardrails por Agent
+
+```yaml
+input:
+  - code: FIN_INPUT_POLICY
+    enabled: true
+    mode: observe
+
+output:
+  - code: FIN_OUTPUT_COMPLIANCE
+    enabled: true
+    mode: enforce
+```
+
+## Judges por Agent
+
+```yaml
+judges:
+  - name: response_quality
+    enabled: true
+    threshold: 0.75
+  - name: groundedness
+    enabled: true
+    threshold: 0.70
+```
+
+## Dataset of Eval
+
+```yaml
+dataset:
+  name: financeiro_agent_regression
+  version: 1.0.0
+  items:
+    - id: fin-001
+      input: "Quero consultar minha fatura"
+      business_context:
+        customer_key: "11999999999"
+        contract_key: "3000131180"
+      expected:
+        route: financeiro_agent
+        tools:
+          - consultar_fatura
+        min_scores:
+          quality: 0.75
+          groundedness: 0.70
+```
+
+
+## Contract Required for Agents transacionais
+
+Ao create a Agent that Uses tools transacionais of the framework, o desenvolvedor No must create a motor paralelo of coleta/confirmação. must reutilizar `AgentRuntime` and garantir that o `AgentState` of the host mantenha o latch durável:
+
+```python
+active_transaction: dict[str, Any]
+last_transaction: dict[str, Any]
+```
+
+during a transação ativa, parâmetros já coletados are preservados and new values are mesclados incrementalmente. Em `COLLECTING_PARAMETERS`, a Response that satisfaz a Parameter pendente tem precedência sobre keywords genéricas. changes of intent explícitas and inequívocas continuam permitidas.
+
+before publicar a new template/host, execute os cenários multi-turno descritos no [`Transaction State Developer Guide`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
+
+
+## Contract MCP Multi-item
+
+for a intent that opere sobre múltiplos itens homogêneos, o Agent **No must implement fan-out/loop of Calls MCP por conta própria**. must reutilizar The runtime and declarar o Contract natural of the tool. A Input Can be escalar or coleção; `type: array/list` No is Requirement for suporte multi-item.
+
+Rules:
+
+1. canonicalização of itens pertence ao MCP/pre-validation and can use `transaction_decision.resolved_arguments`;
+2. confirmação transacional must representar o conjunto efetivo of itens;
+3. a tool primária Must return `results[]` with dois or mais itens containing `success` or `ok` booleano por item;
+4. for workflow-backed tools, a source preferencial is `workflow.output[tool_name].results`;
+5. The runtime normaliza o agregado for `SUCCESS`, `PARTIAL_SUCCESS` or `FAILED`;
+6. Failure em stage auxiliar posterior No can apagar evidência terminal of itens concluídos;
+7. a `eligible=false` global em pre-validation encerra toda transação; for processing parcial, mantenha `eligible=true` when houver ao menos a item acionável and deixe a tool primária materializar o result por item.
+
+Referência of Implementation: [`MCP Multi-item — Guia do Desenvolvedor`](../docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE.md).
+
+
+## Tests
+
+| Test | Scope |
+|---|---|
+| Unitário | Classe of the Agent. |
+| Routing | Intent and rota. |
+| MCP Mapping | BusinessContext for argumentos. |
+| Guardrails | Input and Output. |
+| Judges | Scores minimum. |
+| Runtime | Execution completa. |
+| Memory | continuity of conversation. |
+| Checkpoint | Resume/replay. |
+| Observability | Trace and Events. |
+| Certification | Evidências finais. |
+
+## Definition of Done
+
+- Agent registrado;
+- rota configured;
+- tools declaradas;
+- mapping definido;
+- prompts versionados;
+- guardrails configurados;
+- judges configurados;
+- dataset criado;
+- Tests executados;
+- traces gerados;
+- certification suite aprovada;
+- documentation of the Agent atualizada.
+
+## Anti-patterns
+
+- Agent criando Session;
+- Agent abrindo SSE;
+- Agent compilando LangGraph;
+- Agent chamando system External diretamente;
+- prompt hardcoded without Policy;
+- lógica genérica duplicada no Agent;
+- payload bruto of canal inside of the Agent;
+- ausência of dataset of eval.
+
+
+## Requirements No Funcionais
+
+| Categoria | Requirement |
+|---|---|
+| Availability | Components deployáveis expõem `/health` and `/ready`. |
+| Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
+| Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
+| Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
+| Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
+| Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
+| Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |
+
+
+## Acceptance criteria
+
+- [ ] new Agent is criado without alterar core of the framework.
+- [ ] if houver transações multi-turno, `AgentState` declara `active_transaction` and `last_transaction`.
+- [ ] Configuration ocorre por YAML and `.env`.
+- [ ] Agent Uses BusinessContext.
+- [ ] Agent acessa MCP por router/gateway.
+- [ ] Casos multi-item usam o Contract natural of the Operations (escalar or coleção) + result por item, without loop MCP of negócio inside of the Agent.
+- [ ] Agent No conhece payload bruto of canal.
+- [ ] Guardrails and judges are configurados.
+- [ ] Dataset of eval existe.
+- [ ] Tests minimum executam.
+- [ ] Trace completo is gerado.
+- [ ] Definition of Done is atendida.
+
+
+## Glossário
+
+| Termo | Definição |
+|---|---|
+| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
+| Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
+| Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
+| Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
+| Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
+| AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
+| MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
+| Evaluator | layer of Evaluation online/offline, regressão and Certification. |
+| Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |