Glossário

Termos específicos do projeto usados em toda a docs e source. Se um termo tem tratamento mais longo, a página dedicada está linkada.

A

Agent

No Ongrid, um agent é um worker LLM configurado com uma função específica (coordinator, incident investigator, network specialist, etc.). Cada agent tem uma persona descrevendo em qual modelo roda, quais tools pode chamar, e quantos turns ReAct ganha. Distinto de "edge agent" — veja Edge.

Agent kernel

O runtime que dirige o loop ReAct de um agent: montagem de prompt, resolução do tool registry, invocação do modelo, execução de tool, parsing de response. Dois kernels existem: graph (padrão; construído sobre eino) e legacy (for-loop). Toggle via ONGRID_AGENT_KERNEL.

Air-gapped

Um deployment sem egress de internet. O Ongrid roda totalmente offline dado um relay LLM local (ex.: vLLM, Ollama) e o modelo de embedding local bundled no tarball de release. Veja Air-gapped / on-prem.

B

Blast radius

O conjunto de serviços ou hosts afetados por uma mudança ou incident. O agent computa isso percorrendo o grafo de topologia (nós downstream) antes de recomendar qualquer ação destrutiva.

Bounded context (BC)

Um subdomínio do manager com seus próprios pacotes model, biz, data, e server. Exemplos: iam, edge, device, alert, aiops. Imports entre BCs são restritos a portas de interface; go-arch-lint impõe o limite.

Built-in vault

O conteúdo padrão de base de conhecimento bundled em github.com/ongridio/vault. O manager sincroniza no primeiro boot e re-sincroniza sob demanda. Repo público; cerca de 96 playbooks markdown.

C

Channel

Um alvo de entrega para notificações. Tipos: webhook, slack, feishu, dingtalk, wecom, telegram. Cada canal pode ser filtrado por severity e scope. Veja Channels.

Class (class de tool)

Classificação de blast-radius de uma tool: safe (read-only), mutating (write reversível), dangerous (irreversível). O campo permission_mode da persona gateia quais classes são callable. Veja Skill manifest.

Cmdpolicy

O sandbox do lado edge que gateia invocações de skill bash. Define whitelist de binário, matchers de argumento, allowlists de path, e allowlists de rede. Localizado sob internal/edgeagent/cmdpolicy. Read-only por padrão — virar para mutating exige edits de política explícitos.

Control plane

O tunnel geminio. Carrega ciclo de vida do edge, RPC, heartbeats, alert events, e (hoje) push de métrica. Veja Data plane.

Coordinator

O agent de topo que decompõe perguntas do usuário, despacha sub-agents specialist, e monta a resposta final. Nome de persona: coordinator. Veja Coordinator.

D

Data plane

O caminho HTTPS outbound independente que edges usam para enviar logs e traces diretamente aos endpoints de ingest público do manager — distinto do tunnel (control plane). Veja Data plane de telemetria.

Dedupe key

Chave por-rule, por-scope que o evaluator de alerta usa para colapsar disparos repetidos em um único incident aberto. Construída de rule_key + scope_type + identificador de scope + (dimensões opcionais específicas de rule). Índice único em alert_incidents.dedupe_key.

Device

Um host lógico. Distinto de edge, que é o processo agent conectado ao tunnel. Um device pode ter zero ou muitos edges (se reinstalado). O device_id é a chave canônica de join em labels PromQL e nós de topologia.

E

Edge

O processo agent conectado ao tunnel — ongrid-edge. Identificado por edge_id. Um edge por processo agent rodando; um device pode hospedar múltiplos edges ao longo de sua vida (após reinstalações). Regra de display: a página Edges lista agents; a página Devices lista hosts.

Edge bundle

O tarball que o manager envia a um edge para upgrade de whole-bundle (ADR-024). Contém o binário do agent mais cada binário de plugin, tudo para a arch alvo. Staged em /var/lib/ongrid-edge/.upgrade/ e trocado no próximo boot.

eino

A library de kernel de grafo que o Ongrid usa para o loop ReAct do agent (ONGRID_AGENT_KERNEL=graph). Fornece as primitivas de montagem de prompt, tool-call, e execução de grafo.

F

Frontier

O broker geminio upstream (github.com/singchia/frontier, ADR-007). Edge disca porta 40012; manager disca porta 40011 pela rede docker. Distribui como uma imagem docker bundled no tarball de release.

G

geminio

O protocolo de tunnel multi-stream baseado em TLS (github.com/singchia/geminio) que o broker frontier do Ongrid implementa. Suporta RPC request/response + streams brutos sobre uma conexão TLS persistente.

Grafana embed

A página Monitor renderiza painéis Grafana via iframe (URLs solo-mode) sob /grafana/.... nginx frenteia tanto a API do manager quanto o embed Grafana na mesma origem; o iframe é permitido via GF_SECURITY_ALLOW_EMBEDDING=true.

H

Health (plugin)

O estado de runtime reportado pelo supervisor de um plugin de edge: running, crashed, starting, stopping. Exposto via GET /v1/edges/{id}/plugins e na página Edges ao lado de cada toggle de plugin.

I

IM bridge

O bounded context que conecta chat Ongrid a plataformas IM externas (Slack, Telegram, Lark, DingTalk, WeCom). Uma linha em im_apps por app registrado. Eventos incoming em /v1/im/<provider>/events são convertidos em sessões de chat.

Incident

Um alerta disparando. Um incident por tupla (rule, scope), deduped via dedupe key. Tem um ciclo de vida (open → acknowledged → resolved), uma timeline de event, e opcionalmente um report de investigação gerado por IA.

J

join_mode

Campo de rule: all ou any. Determina se cada entrada em conditions[] precisa casar para a rule disparar (padrão all) ou qualquer uma (any).

K

Kind (kind de rule)

O discriminador que dirige qual sub-evaluator roda sobre as conditions de uma rule. Phase-A: metric_raw, metric_anomaly, metric_forecast, metric_burn_rate. Phase-B: log_match, log_volume, trace_latency, trace_error_rate. Mais o kind de input só-UI metric_threshold. Veja Schema de alert rule.

L

Loki

Store de log do Grafana (ADR-012). Bundled na stack compose como loki:3.4.0. Edges fazem push pelo data plane; o manager consulta via /v1/logs/query_range.

M

Marketplace

O sistema de distribuição de skill-pack (ADR-017). Um pack é um diretório de skills + agents + um manifesto. Instale via POST /v1/marketplace/install. Registries apontam para índices hospedados em HTTPS.

Mention

A sintaxe de autocomplete @edge, @device, @dashboard, @incident no chat box. O manager as resolve em contexto estruturado antes de enviar a mensagem ao LLM.

N

NotifyWindowSeconds / NotifyMinFires

Par de dampening de notificação por-rule. Uma rule disparando menos que NotifyMinFires vezes dentro do trailing NotifyWindowSeconds escreve um event repeat_suppressed mas não envia uma notificação. Veja Schema de alert rule.

O

OTLP

OpenTelemetry Protocol — o formato wire que edges usam para enviar traces (via otelcol-contrib) ao endpoint /v1/traces do manager.

otelcol-contrib

A distribuição contrib do OpenTelemetry Collector. Bundled no tarball de release como o plugin de traces. Subprocesso gerenciado pelo supervisor de plugin do agent.

P

Persona

Uma definição de comportamento de agent — um arquivo markdown com YAML frontmatter (name, description, when_to_use, tools, model, permission_mode, system prompt). Veja Formato de persona de agent.

Pluggable embedding

O pipeline RAG suporta três providers de embedding: zhipu (padrão, API de embedding GLM), openai, e local (modelo bge em disco). Troque via ONGRID_EMBEDDING_PROVIDER.

Plugin (plugin de edge)

Um subprocesso gerenciado pelo supervisor do edge agent: promtail (logs), node_exporter (host metrics), process_exporter (proc metrics), otelcol-contrib (traces). Configurado via PUT /v1/edges/{id}/plugins/{name}.

promtail

Shipper de log do Grafana. Bundled no tarball de release como o plugin de logs. Subprocesso do edge agent.

push_prom_samples

O RPC tunnel-side de push de métrica. Carrega samples de métrica do edge ao Prom cloud do manager. Hoje no control plane; potencialmente migra para data plane — veja triggers de migração em Data plane de telemetria.

Q

query_promql / query_traceql / search_logs

Três das tools de observabilidade core que o agent pode chamar. Elas proxiam pelo manager para Prom / Tempo / Loki respectivamente, retornando resultados estruturados sobre os quais o LLM pode raciocinar.

R

RAG

Retrieval-Augmented Generation. A base de conhecimento do Ongrid (vault + repos + docs uploaded) é indexada em Qdrant; queries ao agent automaticamente retrieve top-k chunks. Veja Capacidades → Base de conhecimento.

RCA

Root Cause Analysis (Análise de Causa Raiz). O pipeline de investigação do agent que percorre do sintoma de alerta por topologia + métricas + logs + traces + source até uma declaração de causa verificável.

ReAct

O loop "Reason + Act": o agent pensa (monta um plano de tool), age (chama uma tool), observa (lê o resultado), então loopa. Limitado por max_turns na persona.

Rule key

Identificador estável lower_snake para uma alert rule. Usado em dedupe keys e incident.rule. Único entre linhas não-soft-deleted.

S

Scope type

Campo de rule: host, global, ou monitoring_pipeline. Determina a dimensão de agrupamento do evaluator. host produz um incident por device_id; global produz um incident system-wide; monitoring_pipeline é para rules internas de pipeline-health.

Severity

Floor de severity de alerta / canal: info, warning, critical. O match_severity_min=warning de um canal aceita warning + critical; critical aceita só critical.

Skill

Uma tool que o agent pode chamar. Ou built-in (compilada no binário) ou externa (subprocesso com um manifesto skill.json). Ambas vivem no mesmo registry; o LLM não distingue. Veja Skill manifest.

SOP (dual-sign)

O fluxo de confirmação de dois passos para chamadas de tool dangerous. A persona precisa ter permission_mode: dual-sign-required; o runtime apresenta a chamada planejada para review, então executa só após confirmação explícita.

Specialist

Uma persona de agent não-coordinator — incident investigator, network, compute, disk, SRE. O coordinator escolhe um casando a query do usuário contra o campo when_to_use de cada persona. Veja Specialists.

T

Tempo

Store de trace do Grafana (ADR-013). Bundled como tempo:2.5.0. Edges fazem push via OTLP; manager consulta via TraceQL.

Tenant

Um limite lógico de isolamento (org + members). Single-tenant no MVP open-source — lógica de tenant existe no schema mas avalia para "todo mundo no mesmo tenant" até que features multi-tenant entrem.

Tool

O handle voltado ao LLM para uma skill. Uma skill pode declarar múltiplas tools (via a lista tools: do SKILL.md). Em runtime, cada tool tem um name, description, JSON Schema, class, e dica when_to_use.

ToolBag deferral

Otimização para registries de skill grandes. Quando a contagem de tool ultrapassa ONGRID_TOOLBAG_DEFERRAL_THRESHOLD (padrão 30), tools de specialty-tier ganham schemas redacted no prompt. O LLM precisa chamar ToolSearch para expandir uma tool redacted antes de usar. Economiza tokens de prompt.

Topology

O CMDB tipado (nós + relations) sob internal/manager/server/topology. Nós têm um type (service, host, database, queue, ...) com um schema; relations têm um type (depends_on, runs_on, served_by). O agent percorre a topologia para computar blast radius.

Tunnel

A conexão TLS geminio do edge ao broker (frontier). Veja Control plane e geminio.

V

Vault

O repositório built-in de base de conhecimento (github.com/ongridio/vault). Sincronizado ao store RAG do manager no primeiro boot. Veja Built-in vault.

W

WebSSH

Shell baseado em browser sobre o tunnel. O edge port-forwarda bytes ao sshd local; o client SSH vive inteiramente no manager. Veja Capacidades → WebShell.

when_to_use

Um campo de frontmatter de persona / skill / tool que dá ao coordinator (ou ao LLM) uma dica de decisão "quando isso deve ser escolhido" de uma linha. Distinto de description que é "o que é".

Z

Zhipu / GLM

Provider LLM padrão em deployments de rede chinesa. Modelos incluem glm-4.7, glm-5, glm-5.1. Configurado via env vars ONGRID_ZHIPU_*.