313 lines
6.7 KiB
Markdown
313 lines
6.7 KiB
Markdown
# SPEC-012 — Canonical Contracts
|
|
|
|
## Agent Platform OCI
|
|
|
|
Version: 1.0.0
|
|
|
|
|
|
---
|
|
|
|
## Reading guide
|
|
|
|
each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
|
|
|
|
The document structure is:
|
|
|
|
1. Concept.
|
|
2. Problem addressed.
|
|
3. When to use.
|
|
4. When not to use.
|
|
5. Architecture.
|
|
6. Implementation.
|
|
7. Examples.
|
|
8. Common errors.
|
|
9. Acceptance criteria.
|
|
|
|
---
|
|
|
|
|
|
# 1. Concept
|
|
|
|
contracts canônicos are structures padronizadas usadas for desacoplar canais, gateways, runtime, Agents, tools, LLMs, evaluator and Observability.
|
|
|
|
The platform Uses contracts to ensure that Components independentes possam evoluir without quebrar uns aos outros.
|
|
|
|
# 2. Problem addressed
|
|
|
|
without contracts:
|
|
|
|
- each canal envia payload diferente;
|
|
- Agents passam a conhecer WhatsApp, Voice, Teams or CRM;
|
|
- MCP tools recebem parâmetros inconsistentes;
|
|
- LLM calls ficam acopladas ao provider;
|
|
- evaluator No consegue comparar responses;
|
|
- Observability fica fragmentada.
|
|
|
|
with contracts:
|
|
|
|
```text
|
|
Canal → GatewayRequest → Runtime → BusinessContext → ToolInvocation → ToolResult
|
|
```
|
|
|
|
# 3. Catalog of contracts
|
|
|
|
| Contract | Uso |
|
|
| --- | --- |
|
|
| GatewayRequest | Input canônica of the plataforma. |
|
|
| ChannelResponse | Response canônica ao canal. |
|
|
| BusinessContext | Identity canônica of negócio. |
|
|
| AgentState | State Internal of the runtime. |
|
|
| Session | Session técnica/conversational. |
|
|
| Checkpoint | Persistence of State LangGraph. |
|
|
| ToolInvocation | Call canônica of tool MCP. |
|
|
| ToolResult | Response canônica of tool MCP. |
|
|
| LLMRequest | Call canônica ao AI Gateway. |
|
|
| LLMResponse | Response canônica of the AI Gateway. |
|
|
| EvaluationRun | Execution of the evaluator. |
|
|
| EvaluationResult | result of Evaluation. |
|
|
| CertificationResult | result of Certification. |
|
|
| EventEnvelope | Envelope of Events IC/NOC/GRL. |
|
|
|
|
|
|
# 4. GatewayRequest
|
|
|
|
## 4.1. Uso
|
|
|
|
Used por Channel Gateway and Agent Gateway for enviar Messages ao Runtime.
|
|
|
|
```json
|
|
{
|
|
"channel": "web",
|
|
"tenant_id": "default",
|
|
"agent_id": "telecom_contas",
|
|
"payload": {
|
|
"message": "Quero consultar minha fatura",
|
|
"session_id": "session-001",
|
|
"user_id": "user-001",
|
|
"message_id": "msg-001",
|
|
"business_context": {
|
|
"customer_key": "11999999999",
|
|
"contract_key": "3000131180",
|
|
"interaction_key": "301953872",
|
|
"session_key": "session-001"
|
|
},
|
|
"metadata": {
|
|
"request_id": "req-001",
|
|
"contract_version": "gateway-request-v1"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 4.2. fields required
|
|
|
|
- `channel`;
|
|
- `payload.message`;
|
|
- `payload.session_id`;
|
|
- `payload.message_id`;
|
|
- `tenant_id` quando multi-tenant;
|
|
- `agent_id` quando não houver roteamento global.
|
|
|
|
# 5. ChannelResponse
|
|
|
|
```json
|
|
{
|
|
"channel": "web",
|
|
"session_id": "default:telecom_contas:session-001",
|
|
"text": "Resposta final do agente.",
|
|
"metadata": {
|
|
"tenant_id": "default",
|
|
"agent_id": "telecom_contas",
|
|
"route": "billing_agent",
|
|
"intent": "billing_invoice_explanation",
|
|
"guardrails": [],
|
|
"judges": []
|
|
}
|
|
}
|
|
```
|
|
|
|
# 6. BusinessContext
|
|
|
|
## 6.1. Uso
|
|
|
|
BusinessContext transporta Identity of negócio without acoplar The platform ao formato of each canal.
|
|
|
|
```yaml
|
|
business_context:
|
|
customer_key: "11999999999"
|
|
contract_key: "3000131180"
|
|
interaction_key: "301953872"
|
|
account_key: null
|
|
resource_key: null
|
|
session_key: "session-001"
|
|
metadata:
|
|
source_channel: web
|
|
```
|
|
|
|
## 6.2. Mapeamento for MCP
|
|
|
|
```yaml
|
|
tools:
|
|
consultar_fatura:
|
|
map:
|
|
customer_key: msisdn
|
|
contract_key: invoice_id
|
|
interaction_key: ura_call_id
|
|
session_key: session_id
|
|
```
|
|
|
|
# 7. AgentState
|
|
|
|
```python
|
|
class AgentState(TypedDict, total=False):
|
|
user_text: str
|
|
sanitized_input: str
|
|
response_text: str
|
|
tenant_id: str
|
|
agent_id: str
|
|
channel: str
|
|
session_id: str
|
|
conversation_key: str
|
|
message_id: str
|
|
route: str
|
|
intent: str
|
|
business_context: dict
|
|
mcp_tools: list[str]
|
|
mcp_results: list[dict]
|
|
rag_context: str
|
|
guardrails: list[dict]
|
|
judges: list[dict]
|
|
```
|
|
|
|
# 8. ToolInvocation
|
|
|
|
```json
|
|
{
|
|
"tenant_id": "default",
|
|
"agent_id": "telecom_contas",
|
|
"tool_name": "consultar_fatura",
|
|
"arguments": {
|
|
"msisdn": "11999999999",
|
|
"invoice_id": "3000131180"
|
|
},
|
|
"business_context": {
|
|
"customer_key": "11999999999",
|
|
"contract_key": "3000131180"
|
|
},
|
|
"metadata": {
|
|
"request_id": "req-001",
|
|
"trace_id": "trace-001"
|
|
}
|
|
}
|
|
```
|
|
|
|
# 9. ToolResult
|
|
|
|
```json
|
|
{
|
|
"tool_name": "consultar_fatura",
|
|
"ok": true,
|
|
"data": {
|
|
"invoice_id": "3000131180",
|
|
"valor_total": 249.90,
|
|
"status": "ABERTA"
|
|
},
|
|
"cache": {
|
|
"hit": false,
|
|
"ttl_seconds": 300
|
|
},
|
|
"latency_ms": 140
|
|
}
|
|
```
|
|
|
|
# 10. LLMRequest
|
|
|
|
```json
|
|
{
|
|
"tenant_id": "default",
|
|
"agent_id": "telecom_contas",
|
|
"profile": "judge",
|
|
"operation": "judge.response_quality",
|
|
"messages": [
|
|
{"role": "system", "content": "Você é um avaliador."},
|
|
{"role": "user", "content": "Avalie a resposta."}
|
|
],
|
|
"metadata": {
|
|
"request_id": "req-001",
|
|
"trace_id": "trace-001"
|
|
}
|
|
}
|
|
```
|
|
|
|
# 11. LLMResponse
|
|
|
|
```json
|
|
{
|
|
"provider": "oci_openai",
|
|
"model": "openai.gpt-4.1",
|
|
"profile": "judge",
|
|
"content": "Resultado",
|
|
"usage": {
|
|
"input_tokens": 1200,
|
|
"output_tokens": 300,
|
|
"total_tokens": 1500
|
|
},
|
|
"latency_ms": 820
|
|
}
|
|
```
|
|
|
|
# 12. EvaluationRun
|
|
|
|
```json
|
|
{
|
|
"run_id": "eval-001",
|
|
"agent_id": "telecom_contas",
|
|
"source": "langfuse",
|
|
"period_start": "2026-06-18T00:00:00Z",
|
|
"period_end": "2026-06-19T00:00:00Z",
|
|
"status": "running"
|
|
}
|
|
```
|
|
|
|
# 13. EventEnvelope
|
|
|
|
```json
|
|
{
|
|
"event_type": "IC.AGENT_COMPLETED",
|
|
"timestamp": "2026-06-19T12:00:00Z",
|
|
"tenant_id": "default",
|
|
"agent_id": "telecom_contas",
|
|
"session_id": "session-001",
|
|
"trace_id": "trace-001",
|
|
"payload": {}
|
|
}
|
|
```
|
|
|
|
# 14. Rules of evolução
|
|
|
|
- fields new must be optional;
|
|
- fields required No Can be removidos inside of the mesma major;
|
|
- change semântica exige new Version;
|
|
- contracts are versionados independentemente.
|
|
|
|
# 15. Common errors
|
|
|
|
| Error | Impact | Correction |
|
|
| --- | --- | --- |
|
|
| Payload bruto in the runtime | Acopla canais ao core. | use GatewayRequest. |
|
|
| Tool recebendo BusinessContext bruto without mapping | Quebra Contract of the tool. | use mcp_parameter_mapping.yaml. |
|
|
| LLM direto no Agent | Quebra AI Gateway. | use LLMRequest/profile. |
|
|
| fields without Version | Dificulta migração. | Declarar contract_version. |
|
|
|
|
|
|
# 16. Acceptance criteria
|
|
|
|
- [ ] GatewayRequest documentado and versionado.
|
|
- [ ] ChannelResponse documentado and versionado.
|
|
- [ ] BusinessContext Used por canais and MCP.
|
|
- [ ] ToolInvocation and ToolResult padronizados.
|
|
- [ ] LLMRequest and LLMResponse padronizados.
|
|
- [ ] EvaluationRun and EvaluationResult padronizados.
|
|
- [ ] EventEnvelope Used for IC/NOC/GRL.
|
|
- [ ] contracts possuem Rules of evolução.
|