convez.ai
AgenteAutomaçãoAvançado
kontourai

Flow Agents - Disciplina de Processo para Agents IA

kontourai/flow-agents

Disciplina de workflow com estado durável e gates de evidência para agentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Camada de disciplina de processo portável que implementa políticas canônicas, evidência e telemetria para agentes IA em múltiplos ambientes (Claude Code, Codex, GitHub Actions). Mantém estado durável do workflow, aplica quality gates e requer verificação antes de liberação.

Instalação

$npx convez-ai kontourai/flow-agents

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
75%
Último commit
há 2 dias
Versão
v11.2.0
Issues abertas
479
Contribuidores
4

Casos de uso

  • Garantir consistência de workflow em múltiplos agentes e plataformas
  • Rastrear estado durável de trabalho através de compactações e handoffs
  • Aplicar gates de qualidade e verificação antes de liberação de código
  • Integrar telemetria e aprendizado contínuo em sistemas agentic

Veredito

Flow Agents é uma solução robusta para quem precisa de confiabilidade e rastreabilidade em workflows agentic. Bem documentada e com infraestrutura sólida (testes, evals, CI/CD), mas exige compreensão técnica profunda de orchestração de agents e políticas de processo.

README

A tradução para o português deste README ainda está na fila.

Kontour Flow Agents

A portable process-discipline layer for agentic work — canonical policies, evidence, and telemetry that compile to whatever hook surface a host exposes.

npm version CI License Node >= 22

Documentation · Workflow Guide · System Guidebook · Runtime Hook Spec · Kontour Flow


Agents are powerful and forgetful. They plan well, then drift. They skip verification when context gets crowded. They call partial work done, and after a compaction nobody — including the agent — can say where the work actually stands.

Flow Agents addresses this with a process-discipline layer that sits between the user and the agent: four canonical policy classes (workflow steering, quality gate, stop-goal-fit, config protection), durable sidecar state that survives compaction and handoff, evidence gates before release decisions, and telemetry that feeds corrections back into the system. Kontour Flow owns the gate semantics underneath; Flow Agents compiles those policies to whatever hook surface a host exposes — coding-agent harnesses today, agent frameworks next.

You ask for outcomes. The system supplies the path, the state, the checks, and the proof.

What you get

  • One workflow across runtimes — the same idea → backlog → plan → build → review → verify → evidence → release → learning path installs into Claude Code, Codex, Kiro, opencode, and pi without rewriting it per tool.
  • Workflow skills — idea-to-backlog, pull-work, plan-work, execute-plan, review-work, verify-work, evidence-gate, release-readiness, learning-review, and orchestrators like deliver and fix-bug that chain them.
  • Durable workflow state — schema-validated sidecars under .flow-agents/ record acceptance criteria, evidence, critique, handoff, and learning, so any session can resume from recorded state instead of chat memory.
  • Four canonical policies — workflow steering (phase reminders at each turn), quality gate (per-file checks after edits), stop-goal-fit (evidence check before the agent stops), and config protection (veto writes to linter/formatter configs). Each policy class has a canonical script under scripts/hooks/ and compiles to the host's native hook format.
  • Evidence over confidence — important work ends with tests, browser checks, CI results, review findings, governance reports, or an explicit NOT_VERIFIED gap. Optional Veritas integration attaches repo-governance evidence without making it mandatory.
  • Evals that keep the bundle honest — 77 integration and 36 static bundle assertions validate the skills, contracts, fixtures, and hook influence as the bundle evolves.

Flow Agents as a process-discipline layer

The four canonical policy classes are defined in the Runtime Hook Surface spec using a runtime-neutral vocabulary. Adapters translate them to whatever hook surface a host exposes:

Policy ClassWhat it doesHook trigger
Workflow steeringInjects phase-transition reminders so the agent does not lose track of where it is in the delivery pipelineuserPromptSubmit
Quality gateRuns format and lint checks immediately after edit tool callspostToolUse
Stop-goal-fitWarns (or blocks) when the agent is about to stop but required evidence is missingstop
Config protectionVetoes writes to linter and formatter configuration filespreToolUse

The spec defines three conformance levels: L0 (telemetry only), L1 (steering + stop-goal-fit warning), and L2 (all four policies with blocking). Claude Code and Codex are the current L2 reference implementations.

Runtime and support matrix

L2 means all four policy classes with blocking; L1 means steering and stop-goal-fit warning only (no quality gate or blocking config protection). The Runtime Hook Surface spec defines the levels and names every hook-surface gap explicitly.

Full support — L2 (all four policies, blocking)

RuntimeShipsTested
Claude Codeinstall + hooks + bundle77 integration + 36 static assertions — reference implementation
Codexinstall + hooks + bundle77 integration + 36 static assertions — reference implementation
Kiroinstall + hooks + bundleincluded in bundle assertions

Partial support — L1 (steering + stop-goal-fit warning)

RuntimeShipsGapTested
opencode.opencode/agents/, .opencode/skills/, .opencode/plugins/flow-agents.js, opencode.jsonNo prompt-submit hook; steering wired to session.created + tool.execute.beforeincluded in bundle assertions
pi.pi/extensions/flow-agents.ts, .pi/skills/, AGENTS.mdNo stop hook; stop-goal-fit unavailableincluded in bundle assertions

Other

TierRuntimeShipsTested
Official framework adapterAWS Strands (Python)integrations/strands/ — flow-agents-strands PyPI package50 unit tests (no Strands SDK required) — spike/preview, see integrations/strands/README.md
Conformance-certifiedCommunity / third-partySelf-certify using the conformance kitConformance kit in development; not yet shipped

Install

# guided install into your workspace (auto-detects runtime)
npx @kontourai/flow-agents init --dest /path/to/workspace

# headless, for CI or scripts
npx @kontourai/flow-agents init --dest /path/to/workspace --telemetry-sink local-files --yes

# runtime-specific wiring
npx @kontourai/flow-agents init --runtime claude-code --dest /path/to/workspace --yes
npx @kontourai/flow-agents init --runtime codex --dest /path/to/workspace --activate-kits --yes
npx @kontourai/flow-agents init --runtime opencode --dest /path/to/workspace --yes
npx @kontourai/flow-agents init --runtime pi --dest /path/to/workspace --yes

Working from a checkout (for contributors): npm install && npm run build, then node build/src/cli.js init --dest /path/to/workspace.

The installer copies the bundled agents, skills, context, scripts, evals, Flow Kit assets, and the Flow Agents-owned console.telemetry.json descriptor into the target workspace. Telemetry writes to local files by default; optional sinks mirror it to a local, hosted, or self-hosted Kontour Console (--telemetry-sink local-kontour-console | kontour-hosted-console | user-hosted-console --console-url …).

bash install.sh is the low-level option for CI pipelines or scripts that already have a generated bundle checkout (e.g. from a pinned git clone of this repo). Prefer npx @kontourai/flow-agents init for normal workspace setup — it fetches the latest published bundle and auto-detects the runtime:

bash install.sh /path/to/workspace --telemetry-sink local-kontour-console

Use it

After installing, ask the agent for the workflow you want — in plain language:

Use Builder Kit shape for this feature idea and create executable GitHub issues.
Use deliver for this issue. Plan it, execute it, verify it, and stop if evidence is missing.

The Workflow Usage Guide has example prompts and expected behavior for every stage — pull-work, plan-work, execute-plan, review-work, verify-work, fix-bug, release-readiness, and more. The Agent System Guidebook is the plain-language map of how the pieces fit.

Flow Kits

A Flow Kit is a portable workflow bundle: a kit.json manifest, one or more Flow Definitions, and optional skills, docs, adapters, evals, and assets — all validated and installed as a unit. Kits are the extension model for Flow Agents: they let you package a workflow once and deploy it into any workspace through the same path as the built-in workflows.

Builder Kit is the first Kontour-authored kit. It ships with builder.shape (shape a problem into slices and fileable work items) and builder.build (pull ready work through design probing, planning, execution, verification, PR readiness, merge readiness, and learning). Builder Kit is installed automatically by npx @kontourai/flow-agents init.

Install a local kit:

npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to/workspace
  • Kit Authoring Guide — build your own kit from scratch: directory layout, kit.json, a flow file, validation, install, and activation.
  • Flow Kit Repository Contract — the full validation rules, registry schema, and activation diagnostics.

Framework adapters

The same canonical policies that wire into coding-agent harnesses via file-based hook scripts can also wire into agent frameworks as in-process language-native packages.

integrations/strands/ contains flow-agents-strands, a Python package implementing a Strands HookProvider that:

  • emits the canonical telemetry taxonomy (agentSpawn, preToolUse, postToolUse, stop, etc.) to the same JSONL format as the harness adapters
  • enforces config protection via BeforeToolCallEvent cancellation (the Strands equivalent of a blocking preToolUse hook)
  • injects workflow steering context at agent construction via steering_context()

This is a spike/preview — 50 unit tests pass without requiring the Strands SDK, and the README documents 7 limitations honestly. It demonstrates that the policy engine is not harness-specific.

The Runtime Hook Surface spec documents the full framework adapter mapping, including VoltAgent, LangGraph, and OpenAI Agents SDK hook surfaces, and the minimum viable adapter pseudocode.

Where Flow Agents fits

Kontour AI shows the work behind AI. Each product stands alone; together they cohere:

ProductOwns
SurveyProducer evidence: source → extraction → candidate → review → claim
SurfacePortable trust state: claims, evidence, policies, trust snapshots
FlowProcess transparency: steps, gates, transitions, runs, exceptions, reports
VeritasCode/change transparency: repo standards, merge readiness
Flow AgentsAgent-facing distribution: skills, kits, runtime adapters, hooks, telemetry

Flow Agents owns the glue — discovery, just-in-time guidance, scoped delegation, Flow-backed state inside harnesses, evidence-backed completion, and feedback loops. It deliberately does not own the model, the runtime, the workflow engine, or repo governance. The North Star records the direction and design principles.

Developer commands

npm run setup:repo-hooks        # enable the tracked .githooks pre-push lane
npm run validate:source --      # source-tree and contract validation
bash evals/run.sh static        # static eval suite

For release-readiness or repo-shape changes, run the split CI baseline locally:

bash evals/ci/run-baseline.sh --lane source-and-static
bash evals/ci/run-baseline.sh --lane workflow-contracts
bash evals/ci/run-baseline.sh --lane runtime-and-kit

setup:repo-hooks is a repo Git hook for local developer checks, not a Flow Agents runtime hook — runtime hooks live under scripts/hooks/; see docs/developer-hook-setup.md for the boundary.

Repository layout

See Repository Structure for the canonical map. In short:

  • agents/, agent-cards/, skills/, context/, powers/, and prompts/ are canonical bundle source.
  • src/ and scripts/ are product, tooling, validation, installer, hook, telemetry, and compatibility source; see scripts/README.md.
  • kits/, schemas/, packaging/, evals/, docs/, and integrations/ hold Flow Kit assets, contracts, package metadata, evals, durable docs, and optional integrations.
  • dist/, build/, and _site/ are generated output. Local .flow-agents/, .codex/, .claude/, telemetry, promptfoo, Veritas, and cache directories are runtime state and stay ignored; durable outcomes belong in docs, source, schemas, or provider records.

Documentation

The GitHub Pages site is the product overview and quickstart. The repository docs are the developer reference for contracts, workflow behavior, evals, and integration boundaries. For the gate semantics underneath — definitions, runs, evidence, route-back — read the Kontour Flow documentation.

License

Apache-2.0 © Kontour AI

Ver o original no GitHub

Bom para

Relacionados