@t4h/agent-runtime 0.0.0-stage → 0.1.0

package/schema/agent.schema.json

@@ -0,0 +1,236 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://tech4h.com.br/schemas/agent.schema.json",
+  "title": "agent.yaml (schema v1)",
+  "description": "Manifesto de um colaborador digital. Chaves em inglês camelCase, como o catalog.yaml do t4h-mcp-services; textos em português. O manifesto NÃO concede acesso: o acesso do agente é pedido por chamado, como o de uma pessoa, e liberado no gateway.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "name", "description", "owner", "team", "identity", "model", "gateway", "routines"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,39}$",
+      "description": "Igual ao nome da pasta em agents/."
+    },
+    "name": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "stage": {
+      "enum": ["shadow", "live"],
+      "default": "shadow",
+      "description": "shadow: só lê e registra o que faria, em qualquer rotina. live: cada rotina age no próprio nível."
+    },
+    "owner": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dri"],
+      "properties": {
+        "dri": { "type": "string", "minLength": 1, "description": "Pessoa responsável pelo agente." },
+        "securityCoOwner": {
+          "type": "boolean",
+          "default": false,
+          "description": "Segurança divide a responsabilidade. Obrigatório quando alguma rotina chega a autonomous."
+        }
+      }
+    },
+    "team": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["area", "team"],
+      "properties": {
+        "area": { "type": "string" },
+        "team": { "type": "string" },
+        "leader": { "type": "string", "description": "Quem define a prioridade e recebe as escalações. Se ausente, o DRI." },
+        "channel": { "type": "string" }
+      }
+    },
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["email"],
+      "properties": {
+        "email": { "type": "string", "pattern": "^[^@\\s]+@[^@\\s]+$" },
+        "clientId": { "type": "string", "description": "Client do Keycloak usado no client_credentials. Padrão: agent-<id>." }
+      }
+    },
+    "model": { "type": "string", "pattern": "^claude-" },
+    "effort": { "enum": ["low", "medium", "high", "xhigh", "max"], "default": "medium" },
+    "gateway": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["subservices"],
+      "properties": {
+        "subservices": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}$" },
+          "uniqueItems": true,
+          "description": "Conectores do gateway que o agente usa. O que ele pode dentro de cada um é decidido pelos grants do gateway."
+        }
+      }
+    },
+    "reads": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/toolName" },
+      "uniqueItems": true,
+      "default": [],
+      "description": "Ferramentas só de leitura, liberadas em qualquer nível, inclusive no shadow."
+    },
+    "triggers": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "schedule": { "type": "string", "description": "Cron do despertar: a cada tique roda uma rodada." },
+        "timezone": { "type": "string", "default": "America/Sao_Paulo" },
+        "events": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "type": "string" },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["type", "kind"],
+                "properties": {
+                  "type": { "type": "string" },
+                  "kind": { "$ref": "#/definitions/eventKind" }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "limits": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "itemsPerRound": { "type": "integer", "minimum": 1, "default": 10 },
+        "roundTimeoutSec": { "type": "integer", "minimum": 10, "default": 240 },
+        "maxTurnsPerItem": { "type": "integer", "minimum": 1, "default": 25 },
+        "budgetUsdPerItem": { "type": "number", "exclusiveMinimum": 0 },
+        "maxAttempts": { "type": "integer", "minimum": 1, "default": 3 }
+      }
+    },
+    "breaker": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Disjuntor: se a taxa de erro ou correção passa do limite, a rotina desce um nível sozinha.",
+      "properties": {
+        "window": { "type": "integer", "minimum": 5, "default": 50 },
+        "minSample": { "type": "integer", "minimum": 1, "default": 10 },
+        "maxErrorRate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.1 }
+      }
+    },
+    "routines": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": { "pattern": "^[a-z][a-zA-Z0-9]{1,39}$" },
+      "additionalProperties": { "$ref": "#/definitions/routine" }
+    },
+    "guardrails": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "forbiddenTools": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/toolName" },
+          "default": [],
+          "description": "Nunca, em nenhum nível. Segregação de funções (aprovar, concluir, cancelar)."
+        },
+        "untrustedInputs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Campos de evento que chegam ao modelo marcados como dado não confiável."
+        }
+      }
+    },
+    "conversation": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Conversa direta (pelo Claude ou por outro agente). O agente só lê, com o próprio acesso, como um colega; quem pode conversar é o grant do conector agents_<círculo>.",
+      "properties": {
+        "enabled": { "type": "boolean", "default": true },
+        "maxTurns": { "type": "integer", "minimum": 1, "default": 12 },
+        "maxHops": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 2,
+          "description": "Limite de idas e voltas entre agentes numa mesma conversa."
+        }
+      }
+    },
+    "plugins": {
+      "type": "array",
+      "description": "Plugins do marketplace de skills da organização (plugins do Claude Code), na versão declarada. Baixados no build.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "version"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]+$" },
+          "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" }
+        }
+      },
+      "default": []
+    },
+    "skills": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Skills dos plugins a ligar. O resto do plugin fica desligado. As skills da pasta skills/ do agente ficam sempre ligadas."
+    },
+    "handoffTo": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,39}$" },
+      "default": [],
+      "description": "Agentes com quem ele pode conversar."
+    },
+    "memory": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "shortTerm": { "const": "sqlite", "default": "sqlite" },
+        "longTerm": { "const": "postgres", "default": "postgres" }
+      }
+    }
+  },
+  "definitions": {
+    "toolName": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}\\.[a-z][a-z0-9_]{0,63}$", "description": "<subservice>.<tool>, como no catálogo do gateway." },
+    "level": { "enum": ["copilot", "agent", "autonomous"] },
+    "eventKind": { "enum": ["conversation", "critical", "new", "update", "hygiene"] },
+    "routine": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["level", "does"],
+      "properties": {
+        "level": { "$ref": "#/definitions/level" },
+        "target": { "$ref": "#/definitions/level", "description": "Onde a rotina quer chegar. Só documenta a meta; subir é um PR." },
+        "does": { "type": "string", "minLength": 1 },
+        "on": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Eventos que acionam a rotina." },
+        "schedule": { "type": "string", "description": "Cron próprio da rotina (agenda com o time)." },
+        "actions": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/toolName" },
+          "uniqueItems": true,
+          "default": [],
+          "description": "Ferramentas com efeito que esta rotina pode usar. Cada ferramenta pertence a uma rotina só."
+        },
+        "scope": { "type": "object", "description": "Onde a rotina pode agir. Repassado ao modelo e conferido nos evals." },
+        "limits": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "perHour": { "type": "integer", "minimum": 1 },
+            "window": {
+              "type": "string",
+              "pattern": "^(Mon|Tue|Wed|Thu|Fri|Sat|Sun)-(Mon|Tue|Wed|Thu|Fri|Sat|Sun) \\d{2}:\\d{2}-\\d{2}:\\d{2}$",
+              "description": "Fora da janela, a ação vira proposta."
+            }
+          }
+        },
+        "undo": { "type": "string", "description": "Como desfazer (ferramenta ou procedimento). Obrigatório para autonomous." }
+      }
+    }
+  }
+}