Output policy

Output policy changes which events and metadata Harnest publishes. It does not change prompts or model responses.

Choose SubAgent narration

Value	Behavior
`False`	Hide provisional SubAgent narration; the default
`True`	Publish that narration to neutral transports and the playground

from harnest import lifecycle
from harnest.output import AgentMetadataMode, OutputPolicy


@lifecycle.output_policy
def output_policy():
    return OutputPolicy(subagent_messages=True)

Choose provider reasoning

Provider-exposed reasoning is private by default. Opt in only when every caller may receive prompt-derived details and provisional internal narration:

@lifecycle.output_policy
def output_policy():
    return OutputPolicy(thinking=True)

This controls readable ADK thought parts and LangGraph reasoning content. It does not enable model reasoning or expose provider signatures.

Choose tool activity

Tool execution remains enabled even when its public progress is hidden. Use a suppressed tool-activity policy when callers should receive only agent lifecycle updates and the canonical answer or structured result:

@lifecycle.output_policy
def output_policy():
    return OutputPolicy(tool_activity=False)

The default True value publishes neutral tool_call and tool_result events. False removes both event types from JSON, SSE, WebSocket, local, and playground output. A2A already keeps tool arguments and results private.

Choose decision results

Results from context.decisions.evaluate(...) are private by default. Keep OutputPolicy(decision_results=False) to hide Jev or another decision provider’s judgments while still using them for routing, tools, and LLM input. To expose them separately from the final answer:

lifecycle/output.py

from harnest import lifecycle
from harnest.output import OutputPolicy


@lifecycle.output_policy
def output_policy():
    return OutputPolicy(decision_results=True)

Each completed evaluation adds a decision_result item to public output. Its value contains decision/provider versions, typed answers, the policy outcome, duration, and a safe error category when evaluation falls back. Request state, question instructions, and raw provider payloads are excluded. Private graph-to-model inputs are not presented as user turns when restoring conversation history in ADK or LangGraph. SSE and WebSocket use response.decision_result; streaming A2A tasks use metadata.harnest.type: decision_result. Playground displays an expandable Decision panel. Streamed results appear when the backend next yields an event. This controls decision events, not arbitrary data copied into a final response or tool result. Keep decision fields out of your final output schema if they should remain internal. It does not redact LLM text, remove internal graph state/checkpoints, or retroactively delete previously disclosed results. Opted-in decision events are retained in durable completion output when checkpoint storage is configured. Standalone Decisions.evaluate(...) calls outside the context facade do not emit public events. See the Jev example for a decision followed by an LLM reply.

Choose agent metadata

Harnest emits one centralized agent_metadata event for metadata reported by ADK or LangGraph. The default AgentMetadataMode.NORMALIZED mode exposes the portable fields that are present: model, provider, finish reason, and exact input, output, and total token counts. Counts are never estimated. Use AgentMetadataMode.SUPPRESS when callers must not receive any model/provider metadata:

@lifecycle.output_policy
def output_policy():
    return OutputPolicy(agent_metadata=AgentMetadataMode.SUPPRESS)

Suppression removes per-call agent_metadata events and the aggregate usage derived from them. Suppressed metadata is not added to durable completion snapshots. Use raw mode when an authorized caller needs the native framework payload:

from harnest import lifecycle
from harnest.output import AgentMetadataMode, OutputPolicy


@lifecycle.output_policy
def output_policy():
    return OutputPolicy(agent_metadata=AgentMetadataMode.RAW)

Raw mode keeps the normalized fields and adds raw. ADK uses its native LlmResponse metadata field names. LangGraph namespaces stream_metadata, response_metadata, usage_metadata, and additional_kwargs so fields do not collide. The primary message content and Harnest-owned event state are not copied. Native metadata can still contain provider-defined content-like values, including reasoning annotations in additional_kwargs.

Native metadata can contain provider identifiers, diagnostic details, and other sensitive or high-cardinality values. Raw values cross every enabled neutral transport and may be persisted by a remote A2A task store. Enable raw mode only for callers authorized to receive that provider payload. Harnest never copies raw metadata into its playground trace history.

When Harnest owns checkpoint storage, it durably retains the normalized completion snapshot so another replica can return the same per-call metadata, aggregate usage, caller metadata, and structured result. Raw metadata remains ephemeral by default, even when it is exposed live. Persist it only with the separate opt-in:

@lifecycle.output_policy
def output_policy():
    return OutputPolicy(
        agent_metadata=AgentMetadataMode.RAW,
        persist_raw_agent_metadata=True,
    )

Durable completion snapshots are JSON-validated and limited to 4 MiB. They use the configured checkpoint backend’s retention behavior. PostgreSQL retains the snapshot with the run; Redis applies the configured checkpoint TTL.

Persisted raw metadata remains available for the lifetime of the durable run. Enable persist_raw_agent_metadata only when storage, retention, and caller authorization are appropriate for the native provider payload.

What remains visible

Event	Default	Suppression control
Root-agent messages	Visible	Always visible
Tool calls and results	Visible	`tool_activity=False`
Final answer or structured result	Visible	Always visible
Intermediate SubAgent narration	Hidden	`subagent_messages=False`
Decision results	Hidden	`decision_results=False`
Provider-exposed reasoning	Hidden	`thinking=False`
Model/provider metadata and usage	Visible, normalized	`agent_metadata=AgentMetadataMode.SUPPRESS`

Intermediate narration may be provisional and later revised. Use True only when your product deliberately presents progress.

All arguments are keyword-only. Binary controls require True or False, and agent_metadata requires AgentMetadataMode; string policy values are not accepted. When moving an older project to this contract, run harnest upgrade AGENT_DIR --apply to rewrite released string and positional forms.

Scope

Property	Rule
Factory	Synchronous and zero-argument
Allowed	Zero or one per root agent
Frameworks	Managed and advanced roots through neutral routes
Native routes	Framework-owned
Tests	Does not change authored fixtures

Overview

Get started

Guides

Output policy

Choose SubAgent narration

Choose provider reasoning

Choose tool activity

Choose decision results

Choose agent metadata

What remains visible

Scope

​Choose SubAgent narration

​Choose provider reasoning

​Choose tool activity

​Choose decision results

​Choose agent metadata

​What remains visible

​Scope

Choose SubAgent narration

Choose provider reasoning

Choose tool activity

Choose decision results

Choose agent metadata

What remains visible

Scope