mirror of
https://github.com/hoshikawa2/agent_platform_oci.git
synced 2026-11-06 11:24:13 +00:00
fix: Spec Agent Runtime
This commit is contained in:
312
specs/en/SPEC-012-Canonical-Contracts.md
Normal file
312
specs/en/SPEC-012-Canonical-Contracts.md
Normal file
@@ -0,0 +1,312 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user