agent_framework_oci/specs/en/SPEC-010-Agent-Development.md

# SPEC-010 — Agent Development

## Scope

Esta SPEC Defines o Standard for Creation of Agents usando templates, Configuration YAML, BusinessContext, MCP, guardrails, judges, RAG, Memory, Observability and evals.

## structure of the Template

```text
templates/agent_template_backend/
├── app/
│   ├── main.py
│   ├── state.py
│   ├── workflows/
│   │   └── agent_graph.py
│   ├── agents/
│   │   ├── runtime.py
│   │   └── domain_agent.py
│   └── examples/
├── config/
│   ├── agents.yaml
│   ├── routing.yaml
│   ├── tools.yaml
│   ├── mcp_servers.yaml
│   ├── mcp_parameter_mapping.yaml
│   ├── identity.yaml
│   ├── guardrails.yaml
│   ├── judges.yaml
│   ├── prompt_policy.yaml
│   └── agents/<agent_id>/
├── Dockerfile
├── requirements.txt
└── .env.example
```

## Responsibilities of the Framework

- LangGraph;
- Memory;
- checkpoint;
- Session;
- router;
- supervisor;
- guardrails;
- judges;
- telemetry;
- MCP integration;
- RAG genérico;
- cache;
- providers LLM;
- event bus.

## Responsibilities of the Agent

- prompts of Domain;
- Rules of negócio;
- schemas específicos;
- Decision of uso of evidências;
- handling of fields required;
- Messages of Domain;
- ICs of jornada;
- datasets of eval específicos.

## Registration of the Agent

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

## Routing

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

## Tool Mapping

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

## Classe of Agent

```python
class FinanceiroAgent(AgentRuntimeMixin):
    name = "financeiro_agent"

    def __init__(
        self,
        llm,
        telemetry=None,
        tool_router=None,
        rag_service=None,
        cache=None,
        settings=None,
        observer=None,
        memory=None,
        summary_memory=None,
    ):
        self.llm = llm
        self.telemetry = telemetry
        self.tool_router = tool_router
        self.rag_service = rag_service
        self.cache = cache
        self.settings = settings
        self.observer = observer
        self.memory = memory
        self.summary_memory = summary_memory

    async def run(self, state):
        await self._emit_ic("IC.FINANCEIRO_AGENT_STARTED", state, {})
        tool_context = await self._collect_mcp_context(state)
        rag_context, rag_metadata = await self._retrieve_rag_context(state)
        response = await self._invoke_llm_cached(
            state,
            "FinanceiroAgent",
            [
                {"role": "system", "content": "Você é um agente financeiro."},
                {"role": "user", "content": state.get("sanitized_input") or state.get("user_text", "")},
            ],
        )
        await self._emit_ic("IC.FINANCEIRO_AGENT_COMPLETED", state, {})
        return {
            "response_text": response,
            "mcp_results": tool_context,
            "rag_metadata": rag_metadata,
        }
```

## Ordem of Confiança of the Data

1. `tool_arguments`
2. `business_context`
3. `context`
4. `session.metadata`
5. `state`
6. extração complementar of the texto

## Prompt Policy

```yaml
prompt_policy:
  system_prompt_path: prompts/system.md
  response_style: concise
  require_evidence: true
  allow_tool_usage: true
```

## Guardrails por Agent

```yaml
input:
  - code: FIN_INPUT_POLICY
    enabled: true
    mode: observe

output:
  - code: FIN_OUTPUT_COMPLIANCE
    enabled: true
    mode: enforce
```

## Judges por Agent

```yaml
judges:
  - name: response_quality
    enabled: true
    threshold: 0.75
  - name: groundedness
    enabled: true
    threshold: 0.70
```

## Dataset of Eval

```yaml
dataset:
  name: financeiro_agent_regression
  version: 1.0.0
  items:
    - id: fin-001
      input: "Quero consultar minha fatura"
      business_context:
        customer_key: "11999999999"
        contract_key: "3000131180"
      expected:
        route: financeiro_agent
        tools:
          - consultar_fatura
        min_scores:
          quality: 0.75
          groundedness: 0.70
```


## Contract Required for Agents transacionais

Ao create a Agent that Uses tools transacionais of the framework, o desenvolvedor No must create a motor paralelo of coleta/confirmação. must reutilizar `AgentRuntime` and garantir that o `AgentState` of the host mantenha o latch durável:

```python
active_transaction: dict[str, Any]
last_transaction: dict[str, Any]
```

during a transação ativa, parâmetros já coletados are preservados and new values are mesclados incrementalmente. Em `COLLECTING_PARAMETERS`, a Response that satisfaz a Parameter pendente tem precedência sobre keywords genéricas. changes of intent explícitas and inequívocas continuam permitidas.

before publicar a new template/host, execute os cenários multi-turno descritos no [`Transaction State Developer Guide`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).


## Contract MCP Multi-item

for a intent that opere sobre múltiplos itens homogêneos, o Agent **No must implement fan-out/loop of Calls MCP por conta própria**. must reutilizar The runtime and declarar o Contract natural of the tool. A Input Can be escalar or coleção; `type: array/list` No is Requirement for suporte multi-item.

Rules:

1. canonicalização of itens pertence ao MCP/pre-validation and can use `transaction_decision.resolved_arguments`;
2. confirmação transacional must representar o conjunto efetivo of itens;
3. a tool primária Must return `results[]` with dois or mais itens containing `success` or `ok` booleano por item;
4. for workflow-backed tools, a source preferencial is `workflow.output[tool_name].results`;
5. The runtime normaliza o agregado for `SUCCESS`, `PARTIAL_SUCCESS` or `FAILED`;
6. Failure em stage auxiliar posterior No can apagar evidência terminal of itens concluídos;
7. a `eligible=false` global em pre-validation encerra toda transação; for processing parcial, mantenha `eligible=true` when houver ao menos a item acionável and deixe a tool primária materializar o result por item.

Referência of Implementation: [`MCP Multi-item — Guia do Desenvolvedor`](../docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE.md).


## Tests

| Test | Scope |
|---|---|
| Unitário | Classe of the Agent. |
| Routing | Intent and rota. |
| MCP Mapping | BusinessContext for argumentos. |
| Guardrails | Input and Output. |
| Judges | Scores minimum. |
| Runtime | Execution completa. |
| Memory | continuity of conversation. |
| Checkpoint | Resume/replay. |
| Observability | Trace and Events. |
| Certification | Evidências finais. |

## Definition of Done

- Agent registrado;
- rota configured;
- tools declaradas;
- mapping definido;
- prompts versionados;
- guardrails configurados;
- judges configurados;
- dataset criado;
- Tests executados;
- traces gerados;
- certification suite aprovada;
- documentation of the Agent atualizada.

## Anti-patterns

- Agent criando Session;
- Agent abrindo SSE;
- Agent compilando LangGraph;
- Agent chamando system External diretamente;
- prompt hardcoded without Policy;
- lógica genérica duplicada no Agent;
- payload bruto of canal inside of the Agent;
- ausência of dataset of eval.


## Requirements No Funcionais

| Categoria | Requirement |
|---|---|
| Availability | Components deployáveis expõem `/health` and `/ready`. |
| Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
| Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
| Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
| Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
| Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
| Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |


## Acceptance criteria

- [ ] new Agent is criado without alterar core of the framework.
- [ ] if houver transações multi-turno, `AgentState` declara `active_transaction` and `last_transaction`.
- [ ] Configuration ocorre por YAML and `.env`.
- [ ] Agent Uses BusinessContext.
- [ ] Agent acessa MCP por router/gateway.
- [ ] Casos multi-item usam o Contract natural of the Operations (escalar or coleção) + result por item, without loop MCP of negócio inside of the Agent.
- [ ] Agent No conhece payload bruto of canal.
- [ ] Guardrails and judges are configurados.
- [ ] Dataset of eval existe.
- [ ] Tests minimum executam.
- [ ] Trace completo is gerado.
- [ ] Definition of Done is atendida.


## Glossário

| Termo | Definição |
|---|---|
| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
| Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
| Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
| Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
| Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
| AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
| MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
| Evaluator | layer of Evaluation online/offline, regressão and Certification. |
| Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |