agent_platform_oci/specs/SPEC-014-Templates-and-Agent-Creation-Model.md

SPEC-014 — Templates and Agent Creation Model

Agent Platform OCI

Version: 1.0.0

---

Padrão de leitura

Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.

A estrutura usada é:

1. Conceito.
2. Problema que resolve.
3. Quando usar.
4. Quando não usar.
5. Arquitetura.
6. Implementação.
7. Exemplos.
8. Erros comuns.
9. Critérios de aceite.

---

1. Conceito

Templates são scaffolds oficiais para criar agentes, MCP servers e backends compatíveis com a Agent Platform OCI.

Eles aceleram o início de um projeto, mas não substituem o framework. O template contém a estrutura mínima de aplicação e os pontos de extensão esperados.

2. Problema que resolve

Sem template:

• cada squad cria estrutura diferente;
• imports e configs variam;
• MCP mapping é esquecido;
• datasets não são criados;
• guardrails e judges ficam ausentes;
• deploy não segue padrão;
• onboarding demora.

3. Templates oficiais

Template	Uso
backend	Criação de agentes com runtime.
backend_day_zero	Bootstrap acelerado com exemplos.
mcp_server	Criação de MCP server.
channel_adapter	Adapter de canal quando aplicável.

4. Estrutura padrão de agente

my_agent/
├── app/
│   ├── main.py
│   ├── state.py
│   ├── workflows/
│   │   └── agent_graph.py
│   └── agents/
│       └── my_agent.py
├── config/
│   ├── agents.yaml
│   ├── routing.yaml
│   ├── tools.yaml
│   ├── mcp_servers.yaml
│   ├── mcp_parameter_mapping.yaml
│   ├── guardrails.yaml
│   ├── judges.yaml
│   └── llm_profiles.yaml
├── prompts/
├── datasets/
├── tests/
├── Dockerfile
└── README.md

5. O que fica no framework

• LangGraph runtime;
• sessão;
• memória;
• checkpoint;
• guardrails genéricos;
• judges genéricos;
• MCP client/router;
• RAG genérico;
• telemetry;
• providers;
• event bus.

6. O que fica no agente

• prompts;
• regras de negócio;
• intents;
• tools específicas;
• datasets;
• testes;
• guardrails de domínio;
• judges de domínio.

7. Passo a passo para criar agente do zero

Passo 1 — Copiar template

cp -R templates/backend financeiro_agent
cd financeiro_agent

Passo 2 — Definir escopo

Agente: financeiro_agent
Objetivo: responder dúvidas sobre faturas, pagamentos e cobranças.
Fora de escopo: vendas, cancelamento e suporte técnico.

Passo 3 — Registrar agente

agents:
  financeiro_agent:
    enabled: true
    description: "Agente financeiro"
    rag_namespace: financeiro
    allowed_tools:
      - consultar_fatura
      - consultar_pagamentos

Passo 4 — Configurar rotas

intents:
  financeiro_consulta_fatura:
    route: financeiro_agent
    keywords:
      - fatura
      - boleto
      - cobrança
    mcp_tools:
      - consultar_fatura

Passo 5 — Configurar tools

tools:
  consultar_fatura:
    server: telecom
    enabled: true
    idempotent: true
    cache_ttl_seconds: 300

Passo 6 — Mapear BusinessContext

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

Passo 7 — Criar prompt

Você é um agente financeiro.
Use MCP como fonte transacional.
Use RAG para políticas e procedimentos.
Não invente valores, datas ou status.

Passo 8 — Implementar agente

class FinanceiroAgent(AgentRuntimeMixin):
    name = "financeiro_agent"

    async def run(self, state):
        mcp = await self._collect_mcp_context(state)
        rag, rag_metadata = await self._retrieve_rag_context(state)
        answer = await self._invoke_llm_cached(
            state,
            "FinanceiroAgent",
            [
                {"role": "system", "content": "Você é um agente financeiro."},
                {"role": "user", "content": state.get("sanitized_input") or ""},
            ],
        )
        return {"response_text": answer, "mcp_results": mcp, "rag_metadata": rag_metadata}

Passo 9 — Criar dataset

dataset:
  name: financeiro_agent_regression
  version: 1.0.0
  items:
    - id: fin-001
      input: "Quero consultar minha fatura"
      expected:
        route: financeiro_agent
        tools:
          - consultar_fatura

Passo 10 — Testar

pytest
af-evaluator run --agent-id financeiro_agent
af-certification run --agent-id financeiro_agent

8. Erros comuns

Erro	Impacto	Correção
Alterar o core para regra de domínio	Dificulta reuso.	Criar agente/config.
Esquecer dataset	Sem regressão.	Criar dataset mínimo.
Tool sem mapping	Argumentos ausentes.	Configurar mcp_parameter_mapping.yaml.
Prompt hardcoded	Sem governança.	Usar prompt_policy/prompts.

9. Critérios de aceite

• Template usado como base.
• Agente registrado.
• Rotas configuradas.
• Tools configuradas.
• MCP mapping configurado.
• Prompt criado.
• Dataset criado.
• Testes executados.
• Evaluator executado.
• Certification aprovada.