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

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

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

Routing

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

Tool Mapping

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

Classe of Agent

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

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

Guardrails por Agent

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

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

Judges por Agent

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

Dataset of Eval

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:

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.

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.

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.