Flow Agents Console Integration

Status: integration guidance draft

Flow Agents can emit local and hosted Console records without making Console the authority for Flow-owned workflow semantics. Flow continues to own Flow Definition gates, route-back behavior, typed expects, provider policy, skill execution, and workflow-learning source records. Console displays, correlates, and routes through those records.

Local Emission

For local development, Flow Agents should keep using local file emission:

• emit control-plane Console handoff records through the Console emitter
• write local JSONL event streams and projections with LocalFileSink
• keep stable event ids across retry and fanout
• store task/session artifacts under .flow-agents
• expose display metadata through console.telemetry.json

Local output must remain useful when hosted Console is unavailable.

Hosted Emission

For hosted deployments, Flow Agents should add an authenticated hosted sink when configured. The hosted sink is a transport adapter; it does not rewrite Flow semantics.

Recommended headers for hosted emission:

Authorization: Bearer ${CONSOLE_AUTH_TOKEN}
X-Console-Tenant-Id: ${CONSOLE_TENANT_ID}
X-Console-Producer: flow-agents
X-Console-Producer-Instance: ${FLOW_AGENTS_INSTANCE_ID}

The bearer token identifies a trusted producer. The tenant header scopes the write. The producer headers are operational identity for audit, dedupe, correlation, and support; they do not grant product authority by themselves.

Descriptor Location

Console descriptor metadata should live in a product-owned console.telemetry.json file in the Flow Agents repo or package bundle. Configure Console with a generic product root rather than a Flow Agents-specific path:

CONSOLE_TELEMETRY_PRODUCT_ROOTS=flow-agents:/path/to/flow-agents

Console then discovers console.telemetry.json and .kontour/console.telemetry.json below that product root. A hosted deployment may mount descriptors and point Console at them with CONSOLE_TELEMETRY_DESCRIPTOR_PATHS, including product-qualified entries such as product:flow-agents:console.telemetry.json. The descriptor maps product-owned fields into generic Console display attributes. It must not redefine Flow Definition gates, typed expects, route-control semantics, or learning authority.

The older Console server option telemetryFlowAgentsRoot is a compatibility alias for local callers that only know the .flow-agents artifact directory. New local, hosted, and user-hosted configurations should use telemetryProductRoots or CONSOLE_TELEMETRY_PRODUCT_ROOTS so multiple products can publish descriptors side by side.

Control Plane Versus Telemetry Plane

Flow Agents should emit control-plane records for workflow state that Console needs to display or route:

• task/session state
• handoff and acceptance artifacts
• gate-opened, gate-passed, gate-failed, and route-back records produced under Flow authority
• workflow-learning source refs or summaries
• inert action descriptors that route back to Flow-owned adapters

Flow Agents may emit telemetry-plane records for operation:

• emission latency
• sink delivery result
• retry count
• queue depth
• tool/runtime observation
• cost and usage observations
• health and readiness diagnostics

Telemetry records can reference control-plane ids for correlation. They must not be treated as proof that a claim is true, a gate passed, or an action executed.

Trusted Producer Identity

A hosted Console deployment should configure Flow Agents as a trusted producer with:

• a producer id, usually flow-agents
• one or more bearer tokens from the secret manager
• an allowed tenant list
• optional instance ids for runtime-specific audit
• descriptor path or mounted descriptor content

Token rotation should allow overlap between old and new tokens. Revoking a token should stop future hosted writes from that producer without rewriting historical records.

Sink Selection

Flow Agents should select sinks by config:

Each sink returns its own delivery result. A hosted failure must not erase a successful local write, and a local failure must not be hidden by hosted success.

Boundary Rules

• Keep Flow Definition gate semantics and typed expects in Flow.
• Keep workflow-learning source schemas in Flow Agents.
• Keep Console descriptors focused on display grouping, facets, and generic attributes.
• Keep hosted tenant and token headers in deployment/runtime config.
• Keep action descriptors inert in generic sinks.
• Do not use Console telemetry as authority for Surface claims, Flow gates, Survey reviews, Veritas checks, product decisions, or action execution.

See also Emitter, Sink, And Plane Contract and Console Telemetry Descriptor.