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

```text
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

```bash
cp -R templates/agent_template_backend financeiro_agent
cd financeiro_agent
```

## step 2 — Definir Scope

```text
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

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

## step 4 — Configurar rotas

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

## step 5 — Configurar tools

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

## step 6 — Mapear BusinessContext

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

## step 7 — create prompt

```text
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

```python
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

```yaml
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

```bash
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.