De copilotos a agentes autónomos: arquitectura, implementação e governação de IA agéntica

A IA agentica empresarial vai além de conclusões de chat num único passo, em direção a sistemas que planificam, invocam ferramentas, recuperam contexto e coordenam aprovações humanas em fluxos de trabalho delimitados. Para CTOs e responsáveis de plataforma europeus, a questão de desenho deixa de ser se deve usar um modelo de linguagem de grande dimensão, mas como integrar agentes nas fronteiras existentes de identidade, dados e gestão de alterações sem criar automação não governada. Este guia explica arquiteturas de referência, padrões de orquestração, integração do Model Context Protocol (MCP), observabilidade e listas de verificação de implementação adequadas a ambientes regulados e multi-equipa. A Damascode, Digital Agency, Lda apoia clientes através de consultoria de TI e desenvolvimento de software nearshore quando capacidades agenticas têm de ser entregues em plataformas de nível de produção.

Índice

• Porque os sistemas agenticos diferem dos chatbots
• Níveis de capacidade e modelo de maturidade
• Arquitetura de referência (vista lógica)
• Plano de controlo vs plano de dados
• Padrões de orquestração
• Ferramentas e servidores MCP
• Memória, estado e fronteiras de recuperação
• Humano no circuito e portões de aprovação
• Identidade, autorização e multi-inquilino
• Observabilidade e avaliação
• Topologias de implementação em Kubernetes
• Esboços de implementação (Python e TypeScript)
• Ligações cruzadas de segurança e governação
• Lista de verificação de implementação
• FAQ
• Referências

Porque os sistemas agenticos diferem dos chatbots

Um chatbot optimiza a UX conversacional. Um sistema agentico optimiza a conclusão de tarefas sob política: decompõe objectivos, selecciona ferramentas, trata falhas parciais e deixa um rasto de auditoria. Essa mudança introduz novos modos de falha: ciclos de ferramentas ilimitados, fuga de credenciais através de prompts, recuperação obsoleta e responsabilidade ambígua quando vários agentes colaboram.

Equipas que tratam agentes como «LLM com plugins» frequentemente omitem contratos de orquestração (timeouts, orçamentos, chaves de idempotência) e descobrem problemas de custo e segurança em produção. Alinhe o desenho de agentes com segurança de IA empresarial e governação de dados prontos para IA desde o primeiro dia.

Níveis de capacidade e modelo de maturidade

Use um modelo por níveis para definir expectativas junto da administração e dos auditores.

A promoção entre níveis exige aprovação explícita: modelação de ameaças, revisão de classificação de dados e runbooks. A Damascode recomenda documentar o nível por caso de uso num registo interno de IA ligado à sua plataforma interna de programadores.

Arquitetura de referência (vista lógica)

                    +---------------------+
                    |   Identity / SSO    |
                    +----------+----------+
                               |
          +--------------------+--------------------+
          |                    |                    |
   +------v------+      +------v------+      +------v------+
   |  Web / API  |      | Agent       |      | Admin /     |
   |  Gateway    |      | Orchestrator|      | Policy UI   |
   +------+------+      +------+------+      +-------------+
          |                    |
          |             +--------v---------+
          |             | Planner / Router |
          |             +--------+---------+
          |                      |
          |        +-------------+-------------+
          |        |             |             |
          |   +----v----+   +----v----+   +----v----+
          |   | Worker  |   | Worker  |   | Worker  |
          |   | Agent A |   | Agent B |   | Agent C |
          |   +----+----+   +----+----+   +----+----+
          |        |             |             |
          +--------v-------------v-------------v--------+
                   |   Tool Gateway (MCP / HTTP)   |
                   +--------+------+------+--------+
                            |      |      |
                     +------v--+ +-v----+ +v------+
                     | Vector  | | SaaS | | K8s   |
                     | Store   | | APIs | | API   |
                     +---------+ +------+ +-------+

O orquestrador de agentes gere o ciclo de vida da sessão, aplicação de políticas e IDs de correlação. Workers são executores stateless que correm um passo delimitado. O gateway de ferramentas centraliza autenticação para servidores MCP e integrações REST para que os agentes nunca mantenham segredos de longa duração nos prompts.

Plano de controlo vs plano de dados

Separe preocupações cedo:

O plano de controlo deve ser compatível com GitOps: listas de permissão de ferramentas, versões de modelos e gasto máximo por inquilino versionados como código de aplicação. O plano de dados deve respeitar limites de retenção alinhados com o RGPD e regras sectoriais.

Padrões de orquestração

Orquestrador único, vários workers

Um orquestrador delega a workers especializados (investigação, código, embalagem de aprovação). Prós: raiz de auditoria clara. Contras: o orquestrador pode tornar-se gargalo; mitigue com escalonamento horizontal e passos com fila.

Supervisor com crítico

Um agente supervisor atribui tarefas; um crítico leve valida outputs contra esquema JSON ou regras de negócio antes do commit. Útil para escritas T2 onde a criatividade do LLM não deve contornar validação.

Agentes orientados a eventos

Mensagens num barramento (Kafka, SNS, CloudEvents) disparam agentes. Encaixa em ITSM e automação FinOps. Requer consumidores idempotentes e filas dead-letter.

Checkpoints humano-no-circuito

Obrigatório para aprovações financeiras, alterações de produção e exportação de dados pessoais. Modele o checkpoint como estado de fluxo de trabalho, não como mensagem de chat informal.

  START --> PLAN --> [policy check] --> EXECUTE_TOOL
                          |
                     fail v
                    ESCALATE --> HUMAN_APPROVAL --> RESUME

Ferramentas e servidores MCP

O Model Context Protocol normaliza como as aplicações expõem ferramentas, recursos e prompts aos modelos. Em contexto empresarial, execute servidores MCP como sidecars ou serviços de cluster atrás do gateway de ferramentas, não apenas em portáteis de programadores.

Registe cada ferramenta com: equipa proprietária, classificação de dados, limites de taxa e scopes necessários. Negar por defeito; os agentes recebem tokens de capacidade com scope de sessão e inquilino.

Exemplo de entrada no registo de ferramentas (YAML ilustrativo):

tools:
  - id: jira.create_issue
    mcp_server: mcp-jira-prod
    classification: internal
    allowed_tiers: [T2]
    scopes: [jira:issue:create]
    rate_limit_rpm: 30
    requires_hitl: true
  - id: metrics.query
    mcp_server: mcp-observability
    classification: operational
    allowed_tiers: [T1, T2]
    scopes: [prometheus:query:read]
    rate_limit_rpm: 120
    requires_hitl: false

Memória, estado e fronteiras de recuperação

Os agentes precisam de três tipos de memória com diferentes durações:

1. Memória de trabalho: plano actual, resultados de ferramentas (TTL de sessão, horas).
2. Memória organizacional: embeddings em vector stores com ACL a espelhar sistemas de origem.
3. Memória de preferências do utilizador: opt-in, eliminável, minimizada.

Nunca passe todo o histórico de conversa a cada chamada de ferramenta. Resuma com objectos de estado estruturados:

from dataclasses import dataclass, field
from typing import Any
import json

@dataclass
class AgentSessionState:
    goal: str
    plan_steps: list[str] = field(default_factory=list)
    completed: list[str] = field(default_factory=list)
    artifacts: dict[str, Any] = field(default_factory=dict)
    token_budget_remaining: int = 8000

    def to_context_block(self) -> str:
        return json.dumps(
            {
                "goal": self.goal,
                "plan": self.plan_steps,
                "done": self.completed,
                "artifact_keys": list(self.artifacts.keys()),
            },
            ensure_ascii=False,
        )

A recuperação deve aplicar ACLs ao nível do documento no momento da query, não pós-filtro no modelo. Consulte governação de dados empresarial para dados prontos para IA para padrões de catálogo e linhagem.

Humano no circuito e portões de aprovação

Defina tipos de aprovação:

Guarde identidade do aprovador, timestamp e hash de input com o trace do agente. Reguladores e clientes pedem cada vez mais proveniência da decisão, não apenas a versão do modelo.

Identidade, autorização e multi-inquilino

Os agentes actuam em nome de um utilizador ou principal de serviço. Padrões:

• On-behalf-of (OBO): propagar token OAuth do utilizador com scopes reduzidos.
• Identidade de workload: o agente usa identidade federada; aprovação humana liga a acção ao utilizador.
• Break-glass: papéis de emergência com logging reforçado.

SaaS multi-inquilino deve isolar: namespaces vectoriais, credenciais de ferramentas, templates de prompt e quotas de gasto por inquilino.

Observabilidade e avaliação

Stack mínima de observabilidade:

Registe hashes de prompts e IDs de documentos recuperados, não segredos em bruto. Avalie com trajectórias douradas: dado objectivo G e ferramentas mock, espere sequência de ferramentas S dentro da tolerância.

Exemplo de atributos de span OpenTelemetry (conceptual):

span.setAttributes({
  "ai.agent.id": "ops-runbook-v2",
  "ai.session.id": sessionId,
  "ai.model": "gpt-4.1-mini",
  "ai.tier": "T2",
  "ai.tool.calls": toolCallCount,
  "ai.cost.usd_estimate": costUsd,
});

Topologias de implementação em Kubernetes

Layout comum de produção:

 Namespace: ai-platform
 +--------------------------------------------------+
 | Ingress (WAF) --> API Gateway --> Orchestrator    |
 |                      |                            |
 |            +---------v----------+                 |
 |            | Agent Worker HPA   |                 |
 |            +---------+----------+                 |
 |                      |                            |
 |            +---------v----------+                 |
 |            | MCP Tool Gateway   |                 |
 |            +----+-----------+---+                 |
 |                 |           |                     |
 |            mcp-jira    mcp-k8s   mcp-git           |
 +--------------------------------------------------+
 | GPU node pool (optional, inference)               |
 +--------------------------------------------------+

Use node pools dedicados para inferência quando SLOs de latência o exigirem; coordene capacidade com FinOps. NetworkPolicy: workers falam apenas com gateway e hosts MCP aprovados.

Fragmento de valores Helm (ilustrativo):

orchestrator:
  replicas: 3
  resources:
    requests: { cpu: "500m", memory: 1Gi }
  env:
    MAX_STEPS_PER_RUN: "12"
    SESSION_TTL_MINUTES: "60"
toolGateway:
  mtls:
    enabled: true
  allowedServers:
    - mcp-jira.ai-platform.svc
    - mcp-kubernetes.ai-platform.svc

Esboços de implementação (Python e TypeScript)

Ciclo de ferramentas delimitado (Python)

import time
from typing import Callable

ToolFn = Callable[[dict], dict]

def run_agent_loop(
    goal: str,
    tools: dict[str, ToolFn],
    planner,
    *,
    max_steps: int = 10,
    deadline_sec: float = 120.0,
) -> dict:
    state = {"goal": goal, "steps": []}
    start = time.monotonic()
    for step in range(max_steps):
        if time.monotonic() - start > deadline_sec:
            raise TimeoutError("agent deadline exceeded")
        action = planner(state)  # returns {"tool": name, "input": {...}}
        tool_name = action.get("tool")
        if tool_name == "finish":
            return action.get("result", state)
        if tool_name not in tools:
            raise ValueError(f"tool not allowed: {tool_name}")
        output = tools[tool_name](action["input"])
        state["steps"].append({"tool": tool_name, "output": output})
    raise RuntimeError("max steps exceeded")

Guardrails de cliente MCP (TypeScript)

type ToolCall = { name: string; arguments: Record<string, unknown> };

export async function invokeTool(
  registry: Set<string>,
  call: ToolCall,
  client: { callTool: (n: string, a: Record<string, unknown>) => Promise<unknown> },
): Promise<unknown> {
  if (!registry.has(call.name)) {
    throw new Error(`Tool ${call.name} is not registered for this agent tier`);
  }
  const argsJson = JSON.stringify(call.arguments);
  if (argsJson.length > 32_000) {
    throw new Error("Tool arguments exceed size limit");
  }
  return client.callTool(call.name, call.arguments);
}

Estes esboços omitem detalhes de SDK de fornecedor; ligue-os às políticas de retry, idempotência e circuit breaker do seu orquestrador.

Ligações cruzadas de segurança e governação

Arquitecturas agenticas amplificam riscos clássicos de IA: injecção de prompt via conteúdo recuperado, uso indevido de ferramentas e agência excessiva. Implemente controlo defensivo apenas: sanitização de input, listas de permissão de ferramentas, filtragem de output e separação de canais de instrução vs dados. Mitigações detalhadas estão em segurança de IA empresarial e injecção de prompt.

Alinhe gestão de alterações: o comportamento do agente muda quando modelos, ferramentas ou prompts são actualizados. Trate alterações a prompts e registo de ferramentas como artefactos de release com rollback.

Multi-região e residência

Implementações europeias frequentemente exigem dados e inferência dentro de regiões específicas. Sistemas agenticos complicam a residência porque uma execução pode tocar endpoint de modelo, índice vectorial, sistema de tickets e backend de logging em jurisdições diferentes. Documente um mapa de fluxo de dados por nível de agente e bloqueie chamadas de ferramentas que moveriam dados pessoais para fora de fronteiras não aprovadas.

Use geo-DNS ou load balancing global apenas para orquestradores stateless; fixe afinidade de sessão quando o estado de conversa deve permanecer local. Falhe fechado se uma ferramenta devolver dados de região fora da lista de permissão do inquilino.

Encaminhamento de modelos e fallback

Plataformas agenticas de produção raramente dependem de um único modelo. Implemente uma tabela de encaminhamento por tipo de tarefa, idioma e sensibilidade:

routing:
  plan_step:
    primary: { provider: azure, model: gpt-4.1-mini, region: westeurope }
    fallback: { provider: azure, model: gpt-4o-mini, region: northeurope }
  synthesis:
    primary: { provider: azure, model: gpt-4.1, region: westeurope }
    fallback: { provider: none }  # queue for human rather than cross-border fallback
  embedding:
    primary: { provider: internal, model: bge-m3, region: onprem-gpu-1 }

A lógica de fallback deve ser código determinístico, não escolha do modelo. Quando o primário falha (429, timeout), retry com backoff exponencial, depois degrade para respostas só de recuperação em cache para T0/T1, nunca mude silenciosamente para região não conforme.

Testar trajectórias de agentes

Testes unitários sozinhos são insuficientes. Mantenha uma suite de trajectórias:

Ferramentas mock registam chamadas sem efeitos secundários. Execute a suite em cada alteração a prompts do planner, registo de ferramentas ou versão de modelo. Guarde traces de execuções falhadas para comparação de regressão.

def test_support_agent_escalates_on_unknown_refund(mock_tools):
    mock_tools.register("crm.lookup", lambda _: {"status": "unknown"})
    result = run_agent("process refund for order 991", tools=mock_tools, user_role="support")
    assert "escalate" in result["steps"][-1]["tool"]

Runbooks operacionais

O on-call de plataforma precisa de runbooks distintos dos microserviços clássicos:

1. Indisponibilidade do fornecedor de modelos: mudar para tabela de fallback, activar banner só leitura na UI, pausar agentes T2.
2. Degradação do gateway de ferramentas: circuit-breaker por servidor MCP; enfileirar escritas.
3. Anomalia de custo: identificar label de inquilino, desactivar feature flag do nível de agente, notificar FinOps.
4. Atraso de recuperação: mudar para modo só keyword se vector DB unhealthy.

Ligue runbooks ao catálogo da plataforma interna de programadores para que equipas de aplicação conheçam caminhos de escalada.

Considerações de fornecedor e contrato

Acordos empresariais devem cobrir: subcontratantes, opt-out de treino, retenção de logs, SLOs de disponibilidade e notificação de incidentes de segurança. Para agentes, clarifique se outputs de ferramentas enviados de volta ao modelo passam a logging do lado do fornecedor. Revisão legal alinha-se com minimização técnica (remover PII antes da chamada ao modelo quando possível).

Ao combinar entrega Damascode com a sua plataforma interna, defina responsabilidade partilhada: o cliente gere identidade e classificação de dados; a squad de entrega gere código de aplicação e políticas de agentes; a equipa de plataforma gere SLOs de cluster e gateway. Consulte outsourcing de desenvolvimento de software para modelos de engagement.

Lista de verificação de implementação

Fundação

• Registo de casos de uso de IA com nível (T0-T3) e classificação de dados
• Gateway de ferramentas com OAuth/mTLS e segredos centralizados
• Padrão de identidade escolhido (OBO vs workload) documentado
• Testes de ACL de recuperação automatizados

Engenharia

• Máximo de passos, deadlines e orçamentos de tokens aplicados em código
• Logging estruturado e tracing distribuído activados
• Testes de trajectória dourada em CI
• Fluxos HITL para todas as escritas T2+

Operações

• Runbook de on-call para plataforma de agentes
• Dashboards e alertas de custo (guia FinOps)
• Resposta a incidentes inclui rollback de prompt/ferramentas
• DPAs de fornecedor e subcontratantes revistos para APIs de modelos

Organização

• Formação para product owners sobre limites de agentes
• Revisão legal/privacidade para novas fontes de dados
• Modelo de parceiro definido se alargar equipa via outsourcing de desenvolvimento de software

Quando a capacidade da plataforma interna estiver limitada, contacte a Damascode ou leia sobre o nosso modelo de entrega para revisões de arquitectura e reforço de squads.

FAQ

Devemos construir um super-agente ou muitos agentes pequenos?
Prefira agentes pequenos com ferramentas estreitas. Componha com um orquestrador. Super-agentes são mais difíceis de testar e proteger.

Precisamos de MCP se já temos integrações REST?
O MCP reduz deriva de integração para ferramentas AI-native mas não é obrigatório. Um gateway com auth uniforme e validação de esquema importa mais que o formato de fio.

Como evitamos custos descontrolados?
Limites de tokens por sessão, encaminhamento de modelos (modelo pequeno para planear, grande para síntese), cache de recuperação e paragem rígida na contagem de passos. Atribua custo por label de equipa em Kubernetes e facturação cloud.

Os agentes podem correr totalmente autónomos em produção?
Apenas para acções de baixo nível, só leitura ou reversíveis com monitorização forte. Alterações de produção e compromissos face ao cliente exigem HITL ou automação determinística fora do LLM.

Como se relaciona isto com RAG?
A recuperação alimenta contexto; os agentes decidem acções. A governação de embeddings e documentos é partilhada. Consulte o artigo de governação de dados.

E multi-cloud?
Mantenha orquestração portável (Kubernetes, OpenTelemetry). Fixe inferência de modelos a regiões com requisitos de residência de dados. Abstraia endpoints do gateway de ferramentas por ambiente.

Como versionamos comportamento de agentes para auditores?
Entregue bundles imutáveis: {planner_prompt_hash, tool_registry_version, model_id}. Registe essa tupla em cada execução concluída. Avance e recue como unidade.

Planners e executores devem usar modelos diferentes?
Muitas vezes sim. Modelos menores tratam encaminhamento e selecção de ferramentas; modelos maiores tratam síntese face ao cliente. Meça qualidade e custo por nível antes de standardizar.

Qual a equipa mínima para operar plataforma de agentes v1?
Tipicamente um engenheiro de plataforma mais um engenheiro de produto a tempo parcial, com horas de revisão de segurança reservadas mensalmente. Escale com número de ferramentas e níveis, não só com número de utilizadores de chat.

Como interagem os agentes com change control ITSM existente?
Acções T2+ devem abrir ou referenciar tickets de alteração. O gateway de ferramentas valida estado do ticket (janela aprovada) antes de executar chamadas mutáveis.

Padrões de adopção por sector

Comece com padrões só leitura em sectores regulados; promova a T2 apenas após aprovação legal e período de avaliação bem-sucedido.

Referências

• Documentação do Model Context Protocol: https://modelcontextprotocol.io/
• NIST AI Risk Management Framework: https://www.nist.gov/itl/ai-risk-management-framework
• OWASP Top 10 for LLM Applications: https://owasp.org/www-project-top-10-for-large-language-model-applications/
• Documentação Kubernetes (workloads, NetworkPolicy): https://kubernetes.io/docs/home/
• Convenções semânticas OpenTelemetry para IA generativa (em evolução): https://opentelemetry.io/docs/specs/semconv/gen-ai/
• Google Cloud Architecture Center (padrões MLOps): https://cloud.google.com/architecture
• Guias Azure OpenAI / arquitectura de IA: https://learn.microsoft.com/en-us/azure/architecture/ai-ml/
• CNCF Cloud Native AI Whitepaper: https://www.cncf.io/reports/
• Insights Damascode relacionados: segurança de IA, governação de dados, FinOps para IA em Kubernetes, IDP de platform engineering