agent-devkit 0.1.5 → 0.2.0

package/runtime/agents/agent-devkit-agent-builder/templates/validation-report-output.md

@@ -0,0 +1,13 @@
+# Agent Validation Report
+
+## Result
+
+-
+
+## Errors
+
+-
+
+## Warnings
+
+-

package/runtime/agents/agent-devkit-agent-builder/tests/test_runners.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Tests for the Agent DevKit Agent Builder runners."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[3]
+AGENT = ROOT / "agent"
+AGENT_DIR = ROOT / "agents" / "agent-devkit-agent-builder"
+REPOSITORY_PATH = AGENT_DIR / "infra" / "integrations" / "agent-devkit" / "agent_builder_repository.py"
+
+
+def load_repository_module():
+    spec = importlib.util.spec_from_file_location("agent_builder_repository", REPOSITORY_PATH)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot load repository from {REPOSITORY_PATH}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class AgentBuilderRunnersTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.repository_module = load_repository_module()
+
+    def write_spec(self, root: Path, *, agent_id: str = "sample-builder-agent") -> Path:
+        path = root / "agent-spec.yaml"
+        path.write_text(
+            f"""
+agent_id: {agent_id}
+name: Sample Builder Agent
+purpose: >
+  Criar artefatos de exemplo para validar o builder interno do Agent DevKit.
+domain: internal tooling
+capabilities:
+  - id: inspect-sample
+    purpose: Inspecionar uma fonte local em modo read-only.
+    write_policy: read_only
+providers: []
+risk_profile: low
+""".lstrip(),
+            encoding="utf-8",
+        )
+        return path
+
+    def test_plan_agent_returns_planned_files_without_writing(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.AgentBuilderRepository(root=root)
+
+            result = repository.plan_agent(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["agent"]["id"], "sample-builder-agent")
+            planned_paths = {item["path"] for item in result["planned_files"]}
+            self.assertGreaterEqual(
+                planned_paths,
+                {
+                    "agents/sample-builder-agent/agent.yaml",
+                    "agents/sample-builder-agent/AGENTS.md",
+                    "agents/sample-builder-agent/README.md",
+                    "agents/sample-builder-agent/capabilities/inspect-sample/capability.yaml",
+                    "agents/sample-builder-agent/capabilities/inspect-sample/workflow.md",
+                    "agents/sample-builder-agent/capabilities/inspect-sample/decision-rules.md",
+                },
+            )
+            self.assertFalse((root / "agents" / "sample-builder-agent").exists())
+
+    def test_plan_agent_reports_needs_input_for_incomplete_spec(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = root / "agent-spec.yaml"
+            spec_path.write_text("agent_id: incomplete-agent\n", encoding="utf-8")
+            repository = self.repository_module.AgentBuilderRepository(root=root)
+
+            result = repository.plan_agent(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "needs-input")
+            self.assertGreaterEqual(set(result["missing_fields"]), {"name", "purpose", "domain", "capabilities"})
+
+    def test_scaffold_agent_dry_run_does_not_write_files(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.AgentBuilderRepository(root=root)
+
+            result = repository.scaffold_agent(spec_path=spec_path, execute=False)
+
+            self.assertEqual(result["status"], "planned")
+            self.assertTrue(result["dry_run"])
+            self.assertFalse((root / "agents" / "sample-builder-agent").exists())
+
+    def test_scaffold_agent_execute_writes_only_inside_agent_directory(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.AgentBuilderRepository(root=root)
+
+            result = repository.scaffold_agent(spec_path=spec_path, execute=True)
+
+            self.assertEqual(result["status"], "written")
+            agent_root = root / "agents" / "sample-builder-agent"
+            self.assertTrue((agent_root / "agent.yaml").exists())
+            self.assertTrue((agent_root / "AGENTS.md").exists())
+            self.assertTrue((agent_root / "README.md").exists())
+            self.assertTrue((agent_root / "knowledge" / "system.md").exists())
+            self.assertTrue((agent_root / "templates" / "README.md").exists())
+            self.assertTrue((agent_root / "infra" / "README.md").exists())
+            for item in result["written_files"]:
+                path = (root / item["path"]).resolve()
+                self.assertTrue(path.is_relative_to(agent_root.resolve()), item["path"])
+
+    def test_scaffold_agent_blocks_overwrite_without_explicit_permission(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.AgentBuilderRepository(root=root)
+            repository.scaffold_agent(spec_path=spec_path, execute=True)
+
+            result = repository.scaffold_agent(spec_path=spec_path, execute=True)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "agent_exists")
+
+    def test_plan_agent_blocks_path_traversal_agent_id(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root, agent_id="../bad-agent")
+            repository = self.repository_module.AgentBuilderRepository(root=root)
+
+            result = repository.plan_agent(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "invalid_agent_id")
+
+    def test_validate_agent_contract_accepts_generated_agent(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.AgentBuilderRepository(root=root)
+            repository.scaffold_agent(spec_path=spec_path, execute=True)
+
+            result = repository.validate_agent_contract(agent_id="sample-builder-agent")
+
+            self.assertTrue(result["valid"])
+            self.assertEqual(result["errors"], [])
+
+    def test_plan_agent_runner_is_executable_through_agent_cli(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            spec_path = self.write_spec(Path(tmpdir))
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(AGENT),
+                    "--json",
+                    "run",
+                    "agent-devkit-agent-builder",
+                    "plan-agent",
+                    "--spec",
+                    str(spec_path),
+                ],
+                cwd=ROOT,
+                check=False,
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=60,
+            )
+
+        self.assertEqual(result.returncode, 0, result.stderr or result.stdout)
+        payload = json.loads(result.stdout)
+        runner_payload = json.loads(payload["stdout"])
+        self.assertEqual(runner_payload["status"], "ok")
+        self.assertEqual(runner_payload["agent"]["id"], "sample-builder-agent")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runtime/agents/automation-architect/AGENTS.md

@@ -0,0 +1,11 @@
+# Automation Architect
+
+Instrucoes locais para trabalhar no agente `automation-architect`.
+
+- Mantenha o agente como arquiteto de automacoes, nao como executor universal.
+- Prefira classificacao deterministica e explicavel antes de qualquer uso de LLM.
+- Nao replique geradores especializados existentes; delegue por contrato para o
+  agente mais especifico.
+- Bloqueie escrita externa e execucao real por padrao.
+- Justifique qualquer recomendacao de browser ou desktop automation quando API,
+  CLI ou repository forem alternativas plausiveis.

package/runtime/agents/automation-architect/README.md

@@ -0,0 +1,27 @@
+# Automation Architect
+
+Agente especialista para classificar pedidos de automacao, escolher a tecnologia
+adequada, planejar a solucao e indicar delegacao para builders especificos do
+Agent DevKit.
+
+## Capabilities
+
+- `classify-automation-request`: classifica um pedido de automacao e recomenda
+  abordagem, riscos e agente especializado.
+- `plan-automation-solution`: gera plano de arquitetura da automacao, incluindo
+  contrato, guardrails, alternativa e proximo passo.
+- `delegate-automation-build`: retorna um contrato de delegacao manual para o
+  builder adequado, sem executar o agente delegado.
+- `review-automation-solution`: revisa plano ou solucao de automacao contra os
+  guardrails do arquiteto.
+
+## Exemplo
+
+```bash
+agent run automation-architect classify-automation-request \
+  --request "automatize a coleta diaria de relatorios via API e salve CSV"
+```
+
+O agente deve escolher o caminho mais simples e robusto: API/CLI/repository antes
+de browser, browser antes de desktop visual, e cloud/serverless apenas quando o
+problema realmente pedir execucao event-driven ou gerenciada.

package/runtime/agents/automation-architect/agent.yaml

@@ -0,0 +1,57 @@
+id: automation-architect
+kind: specialist-agent
+name: Automation Architect
+version: 0.1.0
+status: draft
+owner: agent-devkit
+purpose: >
+  Classificar pedidos de automacao, escolher a abordagem correta, planejar a
+  solucao e delegar por contrato para builders especializados sem duplicar os
+  geradores de Python, Selenium, PyAutoGUI, Lambda, Docker ou loops.
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+  - knowledge/policies.yaml
+env:
+  required: []
+  optional: []
+capabilities:
+  - classify-automation-request
+  - plan-automation-solution
+  - delegate-automation-build
+  - review-automation-solution
+agent_surface:
+  repositories:
+    - infra/integrations/automation-architecture/automation_architecture_repository.py
+  policies:
+    - knowledge/policies.yaml
+write_policy:
+  classification: read_only
+  planning: read_only
+  delegation: delegated
+  review: read_only
+  external_side_effects: blocked_by_default
+routing:
+  anchors:
+    - automation-architect
+    - automation-architecture
+    - arquiteto-automacao
+    - automatize
+    - automacao
+  keywords:
+    - automation
+    - automacao
+    - automatizar
+    - automatize
+    - robotizar
+    - workflow
+  intents:
+    - automation.classify
+    - automation.plan
+    - automation.delegate
+    - automation.review
+  examples:
+    - automatize esta tarefa
+    - escolha a melhor forma de automatizar
+    - que tipo de automacao devo usar
+  priority: 80

package/runtime/agents/automation-architect/capabilities/classify-automation-request/capability.yaml

@@ -0,0 +1,35 @@
+id: automation-architect.classify-automation-request
+kind: capability
+name: Classify Automation Request
+version: 0.1.0
+status: draft
+purpose: Classificar pedido de automacao e recomendar tecnologia, agente e riscos sem escrever arquivos.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/automation-classification.md
+inputs:
+  required: []
+  optional:
+    - request
+    - spec
+outputs:
+  artifacts:
+    - automation-classification.json
+write_policy: read_only
+routing:
+  anchors:
+    - classificar-automacao
+    - classify-automation
+    - automation-request
+  keywords:
+    - automatize
+    - automatizar
+    - automacao
+    - automation
+  intents:
+    - automation.classify
+  examples:
+    - escolha o tipo correto de automacao
+    - classifique esta automacao
+  priority: 80

package/runtime/agents/automation-architect/capabilities/classify-automation-request/decision-rules.md

@@ -0,0 +1,10 @@
+# Regras De Decisao
+
+- Prefira API/CLI/repository a browser automation.
+- Prefira Python deterministico para automacoes locais e APIs simples.
+- Use Selenium somente com requisito WebDriver/Grid/legado.
+- Use PyAutoGUI apenas quando nao houver API, CLI, arquivo ou automacao web.
+- Use Lambda para evento cloud/serverless.
+- Use Docker para empacotamento, isolamento e reprodutibilidade.
+- Use loop engineering para retry, budget, criterio de parada ou agenda local.
+- Nao declarar delegacao disponivel quando o builder correspondente nao existe.

package/runtime/agents/automation-architect/capabilities/classify-automation-request/runner.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Runner for automation-architect/classify-automation-request."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "automation-architecture"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from automation_architecture_repository import AutomationArchitectureError, AutomationArchitectureRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Classify an automation request")
+    parser.add_argument("--request")
+    parser.add_argument("--spec")
+    args = parser.parse_args()
+
+    try:
+        result = AutomationArchitectureRepository().classify_automation_request(
+            request=args.request,
+            spec_path=Path(args.spec) if args.spec else None,
+        )
+    except AutomationArchitectureError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/automation-architect/capabilities/classify-automation-request/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Ler `--request` ou `--spec`.
+2. Extrair sinais de ambiente, alvo, side effects e periodicidade.
+3. Escolher o tipo de automacao mais simples e robusto.
+4. Indicar agente/capability recomendado quando existir.
+5. Marcar baixa confianca quando faltar contexto essencial.

package/runtime/agents/automation-architect/capabilities/delegate-automation-build/capability.yaml

@@ -0,0 +1,34 @@
+id: automation-architect.delegate-automation-build
+kind: capability
+name: Delegate Automation Build
+version: 0.1.0
+status: draft
+purpose: Gerar contrato de delegacao manual para o builder especializado adequado, sem executar automaticamente.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+inputs:
+  required: []
+  optional:
+    - request
+    - spec
+outputs:
+  artifacts:
+    - automation-delegation.json
+write_policy: delegated
+routing:
+  anchors:
+    - delegar-automacao
+    - automation-delegation
+    - delegate-automation
+  keywords:
+    - delegar
+    - encaminhar
+    - builder
+    - automacao
+  intents:
+    - automation.delegate
+  examples:
+    - encaminhe para o builder correto
+    - delegue a construcao da automacao
+  priority: 70

package/runtime/agents/automation-architect/capabilities/delegate-automation-build/decision-rules.md

@@ -0,0 +1,7 @@
+# Regras De Decisao
+
+- Nao chamar outro agente automaticamente.
+- Nao delegar para builder inexistente.
+- Marcar Playwright como `available_delegate: false` ate existir builder.
+- Preservar baixa confianca e perguntas pendentes no contrato de delegacao.
+- Informar policy de escrita esperada antes de qualquer geracao.

package/runtime/agents/automation-architect/capabilities/delegate-automation-build/runner.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Runner for automation-architect/delegate-automation-build."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "automation-architecture"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from automation_architecture_repository import AutomationArchitectureError, AutomationArchitectureRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Build a manual automation delegation contract")
+    parser.add_argument("--request")
+    parser.add_argument("--spec")
+    args = parser.parse_args()
+
+    try:
+        result = AutomationArchitectureRepository().delegate_automation_build(
+            request=args.request,
+            spec_path=Path(args.spec) if args.spec else None,
+        )
+    except AutomationArchitectureError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/automation-architect/capabilities/delegate-automation-build/workflow.md

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Classificar e planejar o pedido.
+2. Verificar se existe builder especializado versionado.
+3. Retornar `agent_id`, `capability_id`, argumentos esperados e policy.
+4. Bloquear execucao automatica; a delegacao e manual nesta fase.

package/runtime/agents/automation-architect/capabilities/plan-automation-solution/capability.yaml

@@ -0,0 +1,35 @@
+id: automation-architect.plan-automation-solution
+kind: capability
+name: Plan Automation Solution
+version: 0.1.0
+status: draft
+purpose: Gerar plano de arquitetura de automacao com contrato, guardrails, alternativas e delegacao sugerida.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/automation-plan.md
+inputs:
+  required: []
+  optional:
+    - request
+    - spec
+outputs:
+  artifacts:
+    - automation-plan.json
+write_policy: read_only
+routing:
+  anchors:
+    - planejar-automacao
+    - automation-plan
+    - plan-automation
+  keywords:
+    - plano
+    - planeje
+    - arquitetura
+    - automacao
+  intents:
+    - automation.plan
+  examples:
+    - planeje a melhor automacao
+    - crie um plano para automatizar
+  priority: 80

package/runtime/agents/automation-architect/capabilities/plan-automation-solution/decision-rules.md

@@ -0,0 +1,7 @@
+# Regras De Decisao
+
+- Plano read-only nao escreve artefatos finais.
+- Plano deve conter alternativa mais simples e tecnologia evitada.
+- Plano deve explicitar quando Playwright e recomendado mas ainda sem builder.
+- Plano deve preservar policy do builder delegado.
+- Plano deve pedir confirmacao para escrita externa, desktop visual ou baixa confianca.

package/runtime/agents/automation-architect/capabilities/plan-automation-solution/runner.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Runner for automation-architect/plan-automation-solution."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "automation-architecture"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from automation_architecture_repository import AutomationArchitectureError, AutomationArchitectureRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Plan an automation solution")
+    parser.add_argument("--request")
+    parser.add_argument("--spec")
+    args = parser.parse_args()
+
+    try:
+        result = AutomationArchitectureRepository().plan_automation_solution(
+            request=args.request,
+            spec_path=Path(args.spec) if args.spec else None,
+        )
+    except AutomationArchitectureError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/automation-architect/capabilities/plan-automation-solution/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Classificar o pedido.
+2. Montar contrato de entradas, saidas, alvo, side effects e execucao.
+3. Listar riscos e guardrails.
+4. Indicar delegacao manual para builder especifico quando aplicavel.
+5. Expor perguntas pendentes quando a confianca for baixa.

package/runtime/agents/automation-architect/capabilities/review-automation-solution/capability.yaml

@@ -0,0 +1,36 @@
+id: automation-architect.review-automation-solution
+kind: capability
+name: Review Automation Solution
+version: 0.1.0
+status: draft
+purpose: Revisar plano ou solucao de automacao contra escolha tecnologica, riscos, secrets e policies.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+inputs:
+  required: []
+  optional:
+    - request
+    - spec
+    - solution
+outputs:
+  artifacts:
+    - automation-review.json
+write_policy: read_only
+routing:
+  anchors:
+    - revisar-automacao
+    - automation-review
+    - review-automation
+  keywords:
+    - revisar
+    - review
+    - risco
+    - guardrails
+    - automacao
+  intents:
+    - automation.review
+  examples:
+    - revise esta solucao de automacao
+    - avalie riscos da automacao
+  priority: 70

package/runtime/agents/automation-architect/capabilities/review-automation-solution/decision-rules.md

@@ -0,0 +1,7 @@
+# Regras De Decisao
+
+- Falhar quando houver segredo hardcoded.
+- Falhar quando PyAutoGUI for escolhido sem justificativa de ultimo recurso.
+- Falhar quando browser/desktop automation substituir API/CLI disponivel.
+- Exigir confirmacao para escrita externa, destructive side effects e desktop visual.
+- Aceitar planos read-only com riscos e perguntas explicitas.

package/runtime/agents/automation-architect/capabilities/review-automation-solution/runner.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Runner for automation-architect/review-automation-solution."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "automation-architecture"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from automation_architecture_repository import AutomationArchitectureError, AutomationArchitectureRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Review an automation solution")
+    parser.add_argument("--request")
+    parser.add_argument("--spec")
+    parser.add_argument("--solution")
+    args = parser.parse_args()
+
+    try:
+        result = AutomationArchitectureRepository().review_automation_solution(
+            request=args.request,
+            spec_path=Path(args.spec) if args.spec else None,
+            solution=args.solution,
+        )
+    except AutomationArchitectureError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/automation-architect/capabilities/review-automation-solution/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Ler pedido/spec e opcionalmente a solucao proposta.
+2. Reclassificar o pedido como baseline.
+3. Verificar se a tecnologia escolhida e adequada.
+4. Procurar riscos de secrets, escrita externa e automacao visual fragil.
+5. Retornar achados e recomendacao de aprovacao.