cristiano.hoshikawa/agent_platform_oci
1
2
Fork 0
mirror of https://github.com/hoshikawa2/agent_platform_oci.git synced 2026-11-06 03:14:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: Spec Agent Runtime

Browse Source
This commit is contained in:
Cristiano Hoshikawa
2026-10-30 10:39:34 -03:00
parent ddd9d9a0d4
commit f035580c21
22 changed files with 4614 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
specs/en/SPEC-009-Channel-Gateway.md Normal file
View File

@@ -0,0 +1,197 @@
# SPEC-009 — Channel Gateway
## Scope
O Channel Gateway normaliza payloads of canais external for GatewayRequest and traduz ChannelResponse for the formato of Response of the canal.
## Modos of Operations
| Modo | Description |
|---|---|
| Embedded | Normalização no próprio backend for demos and cenários simples. |
| External | service dedicado for canais corporativos. |
## GatewayRequest
```json
{
"channel": "whatsapp",
"tenant_id": "default",
"agent_id": "telecom_contas",
"payload": {
"message": "Segunda via de fatura",
"session_id": "5511999999999",
"user_id": "5511999999999",
"message_id": "wamid.123",
"business_context": {
"customer_key": "5511999999999",
"interaction_key": "wamid.123",
"session_key": "5511999999999"
},
"metadata": {
"source_channel": "whatsapp",
"source_message_type": "interactive"
}
}
}
```
## ChannelResponse
```json
{
"channel": "whatsapp",
"session_id": "default:telecom_contas:5511999999999",
"text": "Encontrei sua fatura...",
"metadata": {
"tenant_id": "default",
"agent_id": "telecom_contas",
"route": "billing_agent",
"intent": "billing_invoice_explanation"
}
}
```
## Flow External
```mermaid
sequenceDiagram
participant Canal
participant CG as Channel Gateway
participant AG as Agent Gateway
participant RT as Agent Runtime
Canal->>CG: payload bruto
CG->>CG: autenticação, parse, dedupe
CG->>AG: GatewayRequest
AG->>RT: execução
RT-->>AG: ChannelResponse
AG-->>CG: ChannelResponse
CG-->>Canal: resposta do canal
```
## Responsibilities
| Responsibility | Detalhe |
|---|---|
| Auth | validate assinatura, token or origem. |
| Parse | Interpretar payload bruto. |
| Dedup | Evitar reprocessamento por message_id. |
| Normalize | create GatewayRequest. |
| Business Context | Mapear chaves canônicas. |
| Forward | Chamar Agent Gateway. |
| Translate | Converter ChannelResponse for canal. |
| Observe | emit logs, Metrics and traces. |
## Idempotência
Chave:
```text
tenant_id:channel:user_id:message_id
```
Comportamentos:
| Situação | Ação |
|---|---|
| Primeira Message | Processar. |
| Duplicada em andamento | return 202 or Response controlada. |
| Duplicada concluída | return Response previous. |
## Versionamento
Header:
```http
X-Agent-Framework-Contract: gateway-request-v1
```
field alternativo:
```json
{
"payload": {
"metadata": {
"contract_version": "gateway-request-v1"
}
}
}
```
## Security
Validations:
- assinatura of the webhook;
- origem allowed;
- tamanho máximo;
- tipo of evento allowed;
- anexos permitidos;
- sanitização of texto;
- remoção of tokens;
- máscara of Data sensíveis;
- rate limit;
- deduplicação.
## Erros
| Código HTTP | Uso |
|---|---|
| 400 | Payload invalid of the canal. |
| 401 | Authentication ausente. |
| 403 | Origem No autorizada. |
| 422 | GatewayRequest invalid. |
| 429 | Rate limit. |
| 500 | Error Internal. |
| 503 | Runtime unavailable. |
## Anti-patterns
- Agent lendo payload bruto.
- Workflow tratando `channel == whatsapp`.
- MCP recebendo payload bruto.
- Tokens of the canal em metadata.
- Gateway External executando regra of Agent.
- Frontend enviando fields outside of the Contract.
## 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
- [ ] Payload bruto is convertido for GatewayRequest.
- [ ] GatewayRequest is validado.
- [ ] message_id Is used to idempotência.
- [ ] business_context contains chaves canônicas.
- [ ] Response of the runtime is traduzida for the canal.
- [ ] Payload bruto No chega ao Agent Runtime.
- [ ] Auth/rate limit/dedup are implementados.
- [ ] Erros are padronizados.
- [ ] Contract possui Version.
- [ ] Logs/traces usam request_id and trace_id.
## 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. |