agent_platform_oci/specs/en/SPEC-012-Canonical-Contracts.md

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:

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.

{
  "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

{
  "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.

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

tools:
  consultar_fatura:
    map:
      customer_key: msisdn
      contract_key: invoice_id
      interaction_key: ura_call_id
      session_key: session_id

7. AgentState

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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.