Open Horizons · Deep dive técnico

Arquitetura e execução dos agentes.

Como o acelerador materializa Backstage OSS, Azure, GitHub, Azure AI Foundry, MCP, guardrails e observabilidade em uma plataforma operável.

AutoraPaula Silva

AudiênciaArquitetura, plataforma, SRE, segurança e AI engineering

Duração45 a 60 minutos

Data2026-06-18

Mapa do deep dive

Quatro atos. Um objetivo: sair sabendo como a plataforma funciona por dentro.

Ato 1

Modelo de referência

Horizons, camadas, fronteiras do sistema e diagramas oficiais de arquitetura.

Ato 2

Implementação da plataforma

Terraform, AKS, Backstage, ArgoCD, observabilidade, políticas e repo map.

Ato 3

Runtime agêntico

Agent API, roteamento, loop de tool calls, hooks, trajetórias, custos, MCP e Foundry.

Ato 4

Operação e revisão

Fluxo ponta a ponta, rollout H1/H2/H3, segurança, observabilidade e checklist de arquitetura.

Tese de arquitetura

Open Horizons é uma arquitetura para tornar agentes executáveis, governados e auditáveis.

01

Fundação segura

AKS, rede privada, identidade, Key Vault, políticas e observabilidade desde H1.

02

IDP operável

Backstage OSS como produto interno: catálogo, Golden Paths, TechDocs e status.

03

Contexto controlado

MCP, memória, cache, skills e RAG com budget de contexto e fronteiras claras.

04

Intenção explícita

SDD, CONSTITUTION.md, model routing e scope guard antes da implementação.

05

Execução rastreável

Trajetória, custos, hooks, telemetria GenAI e evidência para revisão.

Ato 1

I

Modelo de referência.

Horizons, camadas, atores e fronteiras do sistema antes de discutir qualquer implementação.

Horizons e camadas

Três horizontes de adoção. Seis responsabilidades operacionais.

L6

Harness

Gateway Foundry, cache semântico, A2A, telemetria, memória enterprise e controle de custo por chamada.

H3 · SRE/FinOps/Sec

L5

Agentic Execution

Agent API, agentes runtime, tool loop, trajetórias, cost tracker e hooks no choke point.

H3 · AI Platform

L4

Intent Engineering

CONSTITUTION.md, SDD, EARS, scope guard e model routing por fase do SDLC.

H3 · Product/Architecture

L3

Context Engineering

MCP servers, skills, memória, cache, RAG, Shared Context Store e curadoria de contexto.

H3 · AI Engineering

L2

Platform Engineering

Backstage, Golden Paths, ArgoCD, observabilidade, políticas, workflows e experiência do desenvolvedor.

H2 · Platform

L1

Cloud/Infrastructure

Terraform, AKS, rede, identidade, ACR, Key Vault, banco, storage, monitoramento e recovery.

H1 · Cloud

Diagrama 1 · Architecture Overview

A arquitetura separa fundação, plataforma, inovação agêntica e modelo operacional.

Open Horizons architecture overview diagram

Diagrama 2 · System Context

A fronteira do sistema inclui pessoas, agentes, sistemas de engenharia e runtime Azure.

Ato 2

II

Implementação da plataforma.

Como H1 e H2 saem do desenho para Terraform, Kubernetes, GitOps, Backstage e observabilidade.

Diagrama 3 · H1 Foundation

A fundação H1 entrega o runtime Azure seguro para o resto da plataforma.

H1 em código

Terraform e o contrato de infraestrutura reproduzível.

Runtime

AKS + ACR

`aks-cluster` e `container-registry` criam o plano de execução, identidade e imagens aprovadas.

Rede

Networking

VNet, subnets, NSGs, private endpoints e caminho de egress controlado.

Segurança

Key Vault + identity

Managed Identity e Workload Identity substituem segredo estático em pod.

Dados

PostgreSQL + Storage

Estado do Backstage, artefatos, catálogo e integrações persistentes.

aks-cluster · networking · container-registry · databases · security
ai-foundry · observability · argocd · backstage · cost-management
defender · disaster-recovery · external-secrets · github-runners · naming · purview

Diagrama 4 · H1 Network and Security Detail

Rede privada, identidade federada e política preventiva reduzem a superfície de ataque.

Diagrama 5 · H2 Enhancement

H2 transforma infraestrutura em produto interno: portal, GitOps, Golden Paths e operação.

Diagrama 6 · H2 GitOps and Observability

A entrega é declarativa: source muda, CI valida, ArgoCD reconcilia, observabilidade fecha o loop.

H2 GitOps and observability detail diagram

Mapa de implementação

Cada responsabilidade arquitetural tem um endereço no repositório.

terraform/modules/                 # L1 Azure infrastructure modules
backstage/                         # L2 Backstage OSS portal, plugins, k8s manifests
argocd/                            # L2 GitOps apps, sync policies, app-of-apps
policies/                          # L2/L1 OPA, Gatekeeper, Terraform policy checks
golden-paths/                      # L2 software templates and SDD artefatos
mcp-servers/                       # L3 MCP ecosystem tools
.github/agents/ .github/skills/    # L3/L5 GitHub Copilot agents and skill knowledge
backstage/server/agent-api*/       # L5 Agent APIs and middleware
foundry/agents-service/            # L6 Foundry gateway harness
grafana/ prometheus/               # observability and alerting

Ato 3

III

Runtime dos agentes.

Do clique no portal até a chamada de modelo, tool call, governança, telemetria e resposta em streaming.

Entry points reais

O runtime agêntico é exposto por APIs especializadas e um gateway Foundry.

Superfície	Entrada	Porta / protocolo	Função
Backstage portal	backstage/packages/app/	7007	Experiência do usuário: catálogo, TechDocs, AI Chat, AI Impact e operação.
Agent API	backstage/server/agent-api/main.py	8008	Multi-agent chat, router, SSE, trajetória, custo e hooks.
Agent API Impact	backstage/server/agent-api-impact/main.py	8011	Análise de impacto e experiências AI Impact.
MAF / SK APIs	backstage/server/agent-api-maf/ · agent-api-sk/	8012 / 8013	Superfícies para Microsoft Agent Framework e Semantic Kernel.
MCP Ecosystem	mcp-servers/src/index.ts	stdio	Ferramentas de documentação, catálogo, Backstage, GitHub e referência.
Foundry gateway	foundry/agents-service/app/main.py	OpenAI-compatible API	Harness L6 para chamadas Foundry, cache, A2A, toolbox, memória e telemetria.

Fluxo real · Agent API

`POST /api/agents/chat` executa roteamento, loop agêntico, hooks e streaming SSE.

POST /api/agents/chat
  -> router.detect_agent(message)       # @mention > keyword > orchestrator
  -> TrajectoryMiddleware.before()      # intent + context snapshot
  -> CostTracker.start()                # begin token accounting
  -> BaseAgent.handle(message)          # agentic loop
      -> Azure OpenAI chat.completions
      -> tool_call? -> _execute_tool()
          -> tool_hooks.pre_tool_use()  # classify, block, audit
          -> tool_executor(name, args)
          -> tool_hooks.post_tool_use() # redact, truncate
      -> loop until no tool_calls
  -> CostTracker.finish()
  -> TrajectoryMiddleware.after()
  -> SSE stream to frontend             # agent | text | tool_use | tool_result | done

Roteamento

O router escolhe o agente antes do modelo receber o contexto.

01

Override explícito

Se a request traz `agent` válido, o backend usa esse agente.

→

02

@mention

`@pipeline`, `@security`, `@sre` e outros nomes direcionam a conversa.

→

03

Keyword match

O router detecta intenção por palavras-chave do `AgentConfig`.

→

04

Fallback

Sem match, o `orchestrator` assume a conversa.

pipeline

Diagnóstico de CI/CD via GitHub workflow runs e jobs.

sentinel

Quality gates, checks, cobertura e status de PR.

guardian

Segurança, advisories, Dependabot e postura.

forge

Infraestrutura, repositórios, branches e automação.

Loop agêntico

`BaseAgent.handle()` executa um ciclo: prompt, modelo, tools, resultado, repetição.

Sistema

System prompt

O `AgentConfig` injeta persona, limites e ferramentas.

→

Modelo

Chat completion

A chamada inclui histórico, temperatura, budget e tool definitions.

→

Tools

Tool calls

Cada chamada passa por `_execute_tool()` antes de chegar no executor.

→

Final

No more tools

Quando não há tool calls, a resposta final é enviada ao frontend.

A propriedade arquitetural importante: o loop é comum para a frota. Isso permite hooks, auditoria e sanitização uniformes.

Governança de tool use

Todo tool call passa pelo mesmo choke point: `BaseAgent._execute_tool()`.

preToolUse

Antes de executar

Classifica tool como read-only, mutating ou unknown.
Bloqueia padrões perigosos: path traversal, `rm -rf`, force push, `terraform destroy`, `kubectl delete --all`, SQL destrutivo.
Audita mutações e decisões de risco.
`AGENT_HOOKS_ENFORCE=false` permite rollout em modo warning.

postToolUse

Depois de executar

Redige tokens, chaves, JWTs, private keys e connection strings.
Trunca payloads grandes antes de voltarem ao modelo.
Registra eventos de sanitização.
Espelha a política do gateway Foundry.

Trajetória, custo e SSE

A resposta do agente é também um registro operacional.

Trajectory

O que aconteceu

`trajectory_logger.start`, tool calls, tool results, outcome e snapshot de contexto.

Cost tracker

Quanto custou

Tokens de entrada e saída por agente, modelo e trajectory id.

SSE

Como chega no portal

Chunks `agent`, `text`, `tool_use`, `tool_result`, `done` e `error` via `text/event-stream`.

GET /api/agents/trajectories
GET /api/agents/trajectories/{agent_name}
GET /api/agents/costs
GET /api/agents/costs/{agent_name}
GET /api/agents/context
GET /api/agents/hooks
GET /api/agents/hooks/audit

Ato 4

IV

Contexto, MCP e Foundry.

Como a plataforma controla o que o agente pode saber, chamar, lembrar e gastar.

Context engineering

O agente não recebe contexto infinito. Ele recebe contexto curado.

Hot

Instruções sempre carregadas

GitHub Copilot instructions, AGENTS.md, CODEMAP e contratos de execução.

Warm

Skill e memória de sessão

Skills carregadas sob demanda e Shared Context Store com TTL.

Cold

RAG e memória durável

AI Search, Redis, Cosmos memory e stores classificados.

Bounded

Budget de janela

Recupera, ranqueia, compacta e evita tool/context sprawl.

MCP e Toolbox

Ferramentas são catalogadas, categorizadas e governadas antes de chegar ao agente.

mcp

Servidores MCP

Azure, AKS, Foundry, Backstage, GitHub, Terraform, Playwright, filesystem e outros.

builtin

Foundry built-ins

Web Search, File Search, Azure AI Search e Code Interpreter.

openapi

Wrappers OpenAPI

Categoria pronta para contratos de API descritos e versionados.

a2a

Agent-to-Agent

Especialistas acessíveis por protocolo A2A v1.0 com contexto de trace.

Cada tool carrega `require_approval` e `auth`: managed identity, OAuth passthrough, key ou local. Key-based auth exige dono de rotação.

Diagrama 7 · H3 Innovation

H3 adiciona runtime agêntico, contexto, governança e Azure AI Foundry.

Diagrama 8 · H3 Agent Flow Detail

Uma request agêntica passa por roteamento, cache, memória, RAG, tools, guardrails, inferência e telemetria.

L6 Harness

O `foundry-agents` gateway é o controle operacional das chamadas Foundry.

API

OpenAI-compatible

`/v1/chat/completions`, `/v1/agents/{agent_id}/chat`, `/v1/models`, `/v1/agents`.

Cache

Hierarchical cache

Cache exato e semântico com escopo por tenant, projeto, sessão e modelo.

A2A

Agent handoff

Headers de trace, cadeia de agentes, lineage Purview e profundidade do hop.

Tool hooks

pre/postToolUse

Aprovação humana, budget gate, validação de argumentos, cache hit e audit.

Telemetry

llm.call.completed

Atributos GenAI para App Insights, incluindo token usage, latência, agent id e tool calls.

Memory

Enterprise memory

Cosmos memory, AAD-only, probe operacional e auditoria de acesso classificado.

ADR-0002: o harness standalone escala, é auditado e pode ser protegido por NetworkPolicy separada do backend de agente.

Model routing por SDLC

O modelo certo depende da fase, do risco e da clareza do escopo.

Fase	Modo	Tier	Quando usar
specification	ask	high-capability	Requisitos ambíguos, incompletos ou contraditórios.
architecture	ask	high-capability	Planejamento multi-arquivo, desenho de sistema e ADR.
tdd_spec	edit	mid-tier	Casos de teste a partir de especificação clara.
implementation	agent	mid-tier	Feature code com plano aprovado e escopo claro.
docstrings / summarization	ask	cost-optimized	Tarefas pequenas, repetitivas e bem definidas.
code_review	ask	high-capability	Revisão de qualidade e segurança em PR pronto.

Fonte local: `.github/model-routing.yaml`. A política registra fase, modo, modelos candidatos, tier, custo relativo e critério de uso.

Ato 5

V

Execução ponta a ponta.

Do Golden Path ao deploy, do deploy ao AI Chat, do AI Chat a telemetria e governança.

Diagrama 9 · Critical Path Sequence

O caminho crítico conecta scaffold, CI/CD, GitOps, runtime e resposta agêntica.

Diagrama 10 · Hybrid Azure DevOps + GitHub

A arquitetura suporta coexistência GitHub + Azure DevOps sem quebrar catálogo e operação.

Entrega e rollback

A execução de deploy é controlada por desired state, health checks e evidências.

01

Change

Código, chart, manifesto, plugin ou template muda via PR.

→

02

Validate

CI executa build, testes, scans e policy gates.

→

03

Desired state

Imagem imutável e manifests versionados entram no GitOps repo.

→

04

Reconcile

ArgoCD aplica sync waves, health checks, drift e rollback operacional.

A decisão arquitetural: laptops não aplicam `kubectl` em produção. O cluster converge para o estado desejado revisado.

Gates de rollout

H3 só deve ser habilitado quando H1 e H2 conseguem sustentar agentes em produção.

H1 gate

Fundação pronta

Private endpoints e DNS validados.
Workload Identity sem segredo estático.
ACR, Key Vault, banco e Storage protegidos.
Logs, alerts e recovery configurados.

H2 gate

Plataforma pronta

Backstage autenticado e persistente.
ArgoCD com sync policies por ambiente.
Golden Paths gerando catalog-info e SDD.
Dashboards e alertas com dono.

H3 gate

Agentes prontos

Model routing aprovado.
Tool approvals e hooks ativos.
Budget e cost endpoints visíveis.
Trajetórias, evals e incident runbooks definidos.

Checklist de revisão arquitetural

Perguntas que a arquitetura precisa responder antes de operar agentes.

Runtime

Qual SLO vale para portal, Agent API e Foundry gateway?
Quais workloads escalam de forma independente?
Qual trace id correlaciona portal, CI/CD, ArgoCD, Agent API e Foundry?

Segurança

Existe algum caminho público para dados ou dependências stateful?
Quais tools exigem aprovação humana?
Como auditoria prova quem mudou o que, por que e com qual agente?

Custo

Quais budgets existem por agente, equipe e rota?
Quando cache e routing são obrigatórios?
Como alertas de custo chegam ao owner correto?

Operação

Quem é dono de dashboard, alerta e runbook?
Qual rollback existe para cada serviço crítico?
Quais evidências ficam retidas para revisão?

Referências

Fontes usadas para o deck.

Open Horizons local: docs/architecture/ARCHITECTURE_REVIEW.md.
Open Horizons local: CODEMAP.md.
Open Horizons ADR: ADR-0002 · Foundry agents gateway L6 harness.
Microsoft Azure Well-Architected Framework: https://learn.microsoft.com/azure/well-architected/.
Azure AI Foundry documentation: https://learn.microsoft.com/azure/ai-foundry/.
Backstage architecture overview: https://backstage.io/docs/overview/architecture-overview.
Model Context Protocol: https://modelcontextprotocol.io/.
OpenTelemetry GenAI semantic conventions: https://opentelemetry.io/docs/specs/semconv/gen-ai/.
Azure architecture icons: https://learn.microsoft.com/azure/architecture/icons/.
GitHub Octicons: https://primer.style/octicons/.

Contato: Paula Silva · AI-Native Software Engineer · linkedin.com/in/paulanunes