first_contas/README_MIGRACAO_CONTAS_FIRST.md

Agent Contas FIRST migrado para agent_framework_oci

Este backend foi gerado a partir do agent_template_backend e remodelado para executar o agent_contas_first com máximo uso das capacidades nativas do agent_framework_oci.

Decisões principais

• Não foi portada a camada própria de workflow/guardrails/judges/RAG do legado para evitar duplicação e regras paralelas.
• O agente específico ficou concentrado em app/agents/contas_agent.py.
• O fluxo LangGraph fica em app/workflows/agent_graph.py e usa componentes do framework para input guardrails, router, agente, output supervisor, output guardrails, judges, supervisor review e persistência.
• O MCP é chamado somente via agent_framework.mcp.tool_router através do AgentRuntimeMixin.execute_tools_for_intent().
• Identity e BusinessContext são resolvidos em app/main.py com IdentityResolver e BusinessContext do framework.
• RAG é consumido via RagService do framework usando namespace contas_first.
• Eventos IC/NOC/GRL são emitidos no workflow e no agente, sem criar uma camada de observabilidade paralela.

Arquivos principais

• app/agents/contas_agent.py: comportamento de domínio, seleção declarativa de intents/tools, uso de memória, RAG, MCP e LLM cache do framework.
• app/workflows/agent_graph.py: pipeline LangGraph corporativo.
• config/agents.yaml: registra somente contas_first.
• config/routing.yaml: intents de fatura, pagamento, segunda via, contestação, plano e VAS.
• config/agents/contas_first/guardrails.yaml: ativa MSK, VLOOP, PINJ, DLEX_IN, REVPREC, DLEX_OUT e RAGSEC no framework.
• config/tools.yaml: catálogo MCP telecom com cache por args_schema.
• config/mcp_parameter_mapping.yaml: mapeamento canônico BusinessContext -> argumentos MCP.
• config/identity.yaml: aliases de msisdn, invoice_id, asset_id, ura_call_id e session.
• legacy_reference/: workflows originais guardados apenas como referência de rastreabilidade.

Como rodar

cd agent_contas_migrated
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Exemplo:

curl -X POST http://localhost:8000/gateway/message \
  -H 'Content-Type: application/json' \
  -d '{
    "channel":"web",
    "agent_id":"contas_first",
    "tenant_id":"default",
    "payload":{
      "text":"quero entender minha fatura",
      "session_id":"sess-contas-001",
      "user_id":"11999999999",
      "msisdn":"11999999999",
      "invoice_id":"INV-EXEMPLO-001",
      "ura_call_id":"URA-001"
    }
  }'

Observações

O pacote não altera o agent_framework_oci; ele consome suas APIs nativas. Caso o framework esteja instalado em modo editable, rode com PYTHONPATH apontando para o src do framework ou instale o pacote via pip install -e ../agent_framework_oci.