> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquena.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Runtime
> Arquitetura de agentes, ferramentas, Mastra, modelos, memória, políticas, tracing e avaliações da Orquena.
# AI Runtime
O AI Runtime será um processo separado responsável por executar agentes, workflows e ferramentas de inteligência artificial.
A implementação inicial utilizará **Mastra** atrás de contratos próprios da Orquena.
## Por que Mastra
O framework oferece primitives TypeScript para:
* Agentes.
* Ferramentas tipadas.
* Workflows duráveis.
* Suspend e resume com participação humana.
* Memória e contexto.
* Model providers.
* MCP.
* Observabilidade e avaliações.
A Orquena não entregará ao Mastra a propriedade das regras de negócio ou do modelo de dados.
## Contratos próprios
```text theme={null}
AgentTemplateRegistry
AgentInstanceRepository
ToolRegistry
ModelRouter
PolicyEngine
MemoryPolicy
AgentRunStore
EvaluationService
```
Plugins de domínio registram descriptors e endpoints seguros. Eles não precisam conhecer a instância interna de um agent do framework.
## Template e instância
A plataforma define um **Agent Template** versionado com papel, objetivo, ferramentas, políticas e limites.
Cada organização cria uma **Agent Instance** configurando somente variáveis permitidas:
* Nome da assistente.
* Tom de comunicação.
* Identidade pública do negócio.
* Preferências de atendimento.
* Políticas escolhidas dentro dos limites do template.
O cliente não altera livremente system prompts, providers ou ferramentas privilegiadas.
## Contexto em camadas
```text theme={null}
Platform policy
+
Vertical policy
+
Agent template version
+
Organization settings
+
Operating-location settings
+
Contact summary
+
Conversation state
+
Relevant knowledge
+
Available tools
```
## Isolamento do banco
```text theme={null}
AI Runtime
↓ internal authenticated tool call
Orquena API
↓ permission and domain validation
Domain plugin
↓ repository
PostgreSQL
```
O runtime não acessa Prisma nem tabelas de domínio diretamente.
## Ferramentas controladas
Exemplos:
* `listServices`
* `checkAvailability`
* `createAppointmentHold`
* `confirmAppointment`
* `rescheduleAppointment`
* `cancelAppointment`
* `createLead`
* `createFollowUpTask`
* `requestHumanHandoff`
Cada chamada recebe tenant confiável, identidade do agente, capability, schema, timeout, correlation ID, auditoria e idempotência quando aplicável.
## Dados estruturados e conhecimento
Serviços, preços, profissionais, disponibilidade e appointments vêm de ferramentas estruturadas.
Busca semântica poderá ser usada para:
* FAQs.
* Políticas gerais.
* Documentos.
* Descrições extensas.
Embeddings e memória do modelo não são fontes da verdade para preço, agenda, desconto ou estado transacional.
## Model Router
A Orquena controlará:
* Catálogo de modelos permitidos.
* Modelo por tipo de tarefa.
* Provider e fallback.
* Budget de custo e latência.
* Limites de contexto e output.
* Requisitos de privacidade e região.
* Suporte a ferramentas.
O cliente não escolherá um modelo arbitrário na primeira versão.
## Guardrails
* Least privilege por ferramenta.
* Separação entre leitura e escrita.
* Aprovação humana para ações sensíveis.
* Validação de input e output.
* Revalidação de política dentro da API.
* Bloqueio de SQL e URLs arbitrárias.
* Kill switch global, por organização e por conversa.
* Conteúdo do cliente não pode conceder capabilities.
## Memória
A memória será dividida em:
* Contexto recente.
* Fatos estruturados do contato.
* Estado da tarefa atual.
* Conhecimento recuperado.
* Resumo de execuções.
Todas as camadas respeitam retenção, exclusão e isolamento de organização.
## Tracing e avaliações
Cada run registra:
* Template e prompt versions.
* Modelo e provider.
* Tool calls.
* Tokens, custo e latência.
* Erros e policy decisions.
* Aprovação ou handoff.
* Resultado e evaluators.
Logs e traces não armazenam secrets e reduzem dados pessoais ao mínimo necessário.
## Política de upgrade
Mastra evolui rapidamente. Versões serão fixadas e atualizadas somente após testes de agentes, ferramentas, workflows, memória e persistência.
## Links oficiais
Agentes, tools, workflows e observabilidade.
Código e releases.
Execuções duráveis e controle de fluxo.
Suspend, resume e aprovação humana.