Workflow (Agent DAG/State Machine) — foundations RFC

Status

*ccepted*— 20260509. Sector bootstrap (skeleton + 5 impl tickets) landed as part of /k-go services/ai audit wave (Modo C). Q1 resolved: YAML is the wire format (declarative graphs, lintfriendly, difffriendly), Go SDK engines/sdk/go/workflow provides typed step authoring (PythonDart bindings follow as needed). Q2 resolved: separate sectors with explicit boundary — `servicesfoundationbpm` handles BPMN-style humanformdriven business process; services/ai/workflow handles agentheavy execution; cross-sector calls allowed (subflow/subprocess).

Summary

DAGstate machine pra agents complexos — análogo LangGraphInngestTemporal AIRestate.

Motivation

agents/ é orquestração de agents singulares. Workflows multiagent / multistep com retry/state ainda não tem foundation. Bloqueia produção.

Scope

In

• DAG definition (YAML/code)
• State persistence
• Retry policies
• Branching
• Humaninthe-loop steps

Out (yet)

• Full BPMN (escopo services/foundation/bpm)
• Pipeline ETL

Initial design

Surfaces

• backend/ — Go API + state machine engine
• app/web — UI minimal de runs (futuro)

Key APIs

• POST /v1/workflows — registrar
• POST /v1/workflows/{id}/runs — disparar run
• GET /v1/workflows/{id}/runs/{run_id} — fetch state

Dependencies

• services/ai/agents — actors
• services/ai/trace — observability
• infra/data/kdb-doc — state
• services/ai/sandbox — steps que rodam código

Relation to existing sectors

• Camada acima de agents
• Cooperativo com sandbox e trace

Selfhostedfirst analysis (5 gates)

• *1 Feature parity* zero
• *2 Performance* N/A
• *3 Stability* N/A
• *4 Capability* Temporal-style viável
• *5 Critical-path readiness* destrava complex agents

Open questions

• Q1: DSL — YAML, código, ou ambos?
• Q2: Reuso de services/foundation/bpm se existir?

Next steps

1. Ratificar esta RFC (1 round de comments).
2. Criar sector dir services/ai/workflow/ com koder.toml, README.md, skeleton.
3. Abrir tickets de implementação em services/ai/workflow/backlog/pending/.
4. Registrar em meta/docs/stack/registries/self-hosted-pairs.md se substituir externo.