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

SPEC-014 — Templates and Agent Creation Model

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

Templates are scaffolds oficiais for create Agents, MCP servers and backends compatíveis with a Agent Platform OCI.

Eles aceleram o início of a projeto, mas No substituem o framework. O template contains a structure mínima of aplicação and os pontos of extensão esperados.

2. Problem addressed

without template:

• each squad cria structure diferente;
• imports and configs variam;
• MCP mapping is esquecido;
• datasets No are criados;
• guardrails and judges ficam ausentes;
• deploy No segue Standard;
• onboarding demora.

3. Templates oficiais

Template	Uso
backend	Creation of Agents with runtime.
agent_template_backend_day_zero	Bootstrap acelerado with Examples.
mcp_server	Creation of MCP server.
channel_adapter	Adapter of canal when aplicável.

4. structure Standard of Agent

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 that fica in the framework

• LangGraph runtime;
• Session;
• Memory;
• checkpoint;
• guardrails genéricos;
• judges genéricos;
• MCP client/router;
• RAG genérico;
• telemetry;
• providers;
• event bus.

6. O that fica no Agent

• prompts;
• Rules of negócio;
• intents;
• tools específicas;
• datasets;
• Tests;
• guardrails of Domain;
• judges of Domain.

7. step a step for create Agent of the zero

step 1 — Copiar template

cp -R templates/agent_template_backend financeiro_agent
cd financeiro_agent

step 2 — Definir Scope

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

step 3 — Registrar Agent

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

step 4 — Configurar rotas

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

step 5 — Configurar tools

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

step 6 — Mapear BusinessContext

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

step 7 — create prompt

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

step 8 — implement Agent

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}

step 9 — create 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

step 10 — Testar

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

8. Common errors

Error	Impact	Correction
Alterar o core for regra of Domain	Dificulta reuso.	create Agent/config.
Esquecer dataset	without regressão.	create dataset minimum.
Tool without mapping	Argumentos ausentes.	Configurar mcp_parameter_mapping.yaml.
Prompt hardcoded	without Governance.	use prompt_policy/prompts.

9. Acceptance criteria

• Template Used como base.
• Agent registrado.
• Rotas configuradas.
• Tools configuradas.
• MCP mapping configured.
• Prompt criado.
• Dataset criado.
• Tests executados.
• Evaluator executado.
• Certification aprovada.