harnest.output

All Python modules · Import and compatibility guidance

Decision events

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.

Raw metadata

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.

Exports

Name	Kind
`AgentMetadata`	Class
`AgentMetadataMode`	Class
`OutputPolicy`	Class
`TokenUsage`	Class

AgentMetadata

One framework-neutral view of model and provider response metadata. raw is populated only when OutputPolicy explicitly selects :attr:AgentMetadataMode.RAW. The normalized fields remain available in normalized and raw modes so consumers do not need framework-specific keys.

AgentMetadata(
    framework: str,
    usage: TokenUsage | None = None,
    model: str | None = None,
    provider: str | None = None,
    finish_reason: str | None = None,
    raw: Mapping[str, Any] | None = None,
) -> None

Fields (— means no declared default):

Field	Type	Default
`framework`	`str`	`—`
`usage`	`TokenUsage \| None`	`None`
`model`	`str \| None`	`None`
`provider`	`str \| None`	`None`
`finish_reason`	`str \| None`	`None`
`raw`	`Mapping[str, Any] \| None`	`None`

Parameters and example

Parameter	Type	Default
`framework`	`str`	Required
`usage`	`TokenUsage \| None`	`None`
`model`	`str \| None`	`None`
`provider`	`str \| None`	`None`
`finish_reason`	`str \| None`	`None`
`raw`	`Mapping[str, Any] \| None`	`None`

from harnest.output import AgentMetadata

metadata = AgentMetadata(framework=...)

AgentMetadata.as_dict

AgentMetadata.as_dict() -> dict[str, Any]

Return the stable public representation without empty optional fields.

Example

from harnest.output import AgentMetadata

metadata: AgentMetadata
result = metadata.as_dict()

AgentMetadataMode

Select how much model and provider metadata callers receive.

AgentMetadataMode(*values)

Member	Value
`SUPPRESS`	`'suppress'`
`NORMALIZED`	`'normalized'`
`RAW`	`'raw'`

Example

from harnest.output import AgentMetadataMode

value = AgentMetadataMode.SUPPRESS

OutputPolicy

Control narration, tool activity, decisions, reasoning, and public metadata.

OutputPolicy(
    *,
    subagent_messages: bool = False,
    tool_activity: bool = True,
    thinking: bool = False,
    decision_results: bool = False,
    agent_metadata: AgentMetadataMode = <AgentMetadataMode.NORMALIZED: 'normalized'>,
    persist_raw_agent_metadata: bool = False,
) -> None

Fields (— means no declared default):

Field	Type	Default
`subagent_messages`	`bool`	`False`
`tool_activity`	`bool`	`True`
`thinking`	`bool`	`False`
`decision_results`	`bool`	`False`
`agent_metadata`	`AgentMetadataMode`	`<AgentMetadataMode.NORMALIZED: 'normalized'>`
`persist_raw_agent_metadata`	`bool`	`False`

Parameters and example

Parameter	Type	Default
`subagent_messages`	`bool`	`False`
`tool_activity`	`bool`	`True`
`thinking`	`bool`	`False`
`decision_results`	`bool`	`False`
`agent_metadata`	`AgentMetadataMode`	`<AgentMetadataMode.NORMALIZED: 'normalized'>`
`persist_raw_agent_metadata`	`bool`	`False`

from harnest.output import OutputPolicy

policy = OutputPolicy()

OutputPolicy.includes_intermediate_message

OutputPolicy.includes_intermediate_message(*, has_tool_calls: bool) -> bool

Return whether narration attached to an intermediate tool call is public.

Parameters and example

Parameter	Type	Default
`has_tool_calls`	`bool`	Required

from harnest.output import OutputPolicy

policy: OutputPolicy
result = policy.includes_intermediate_message(has_tool_calls=...)

OutputPolicy.includes_event

OutputPolicy.includes_event(event_type: str) -> bool

Return whether a policy-controlled event may cross public boundaries.

Parameters and example

Parameter	Type	Default
`event_type`	`str`	Required

from harnest.output import OutputPolicy

policy: OutputPolicy
result = policy.includes_event(event_type=...)

TokenUsage

Provider-reported token counts normalized across ADK and LangGraph.

TokenUsage(input_tokens: int, output_tokens: int, total_tokens: int) -> None

Fields (— means no declared default):

Field	Type	Default
`input_tokens`	`int`	`—`
`output_tokens`	`int`	`—`
`total_tokens`	`int`	`—`

Parameters and example

Parameter	Type	Default
`input_tokens`	`int`	Required
`output_tokens`	`int`	Required
`total_tokens`	`int`	Required

from harnest.output import TokenUsage

usage = TokenUsage(input_tokens=..., output_tokens=..., total_tokens=...)

TokenUsage.as_dict

TokenUsage.as_dict() -> dict[str, int]

Return the camel-case representation used by public transports.

Example

from harnest.output import TokenUsage

usage: TokenUsage
result = usage.as_dict()

TokenUsage.from_dict

TokenUsage.from_dict(value: Mapping[str, Any]) -> 'TokenUsage'

Parse either public camel-case or internal snake-case count names.

Parameters and example

Parameter	Type	Default
`value`	`Mapping[str, Any]`	Required

from harnest.output import TokenUsage

usage = TokenUsage.from_dict(value=...)

Overview

Get started

Harnest Studio

Guides

API reference

harnest.output

Decision events

Raw metadata

Exports

AgentMetadata

AgentMetadata.as_dict

AgentMetadataMode

OutputPolicy

OutputPolicy.includes_intermediate_message

OutputPolicy.includes_event

TokenUsage

TokenUsage.as_dict

TokenUsage.from_dict

​Decision events

​Raw metadata

​Exports

​AgentMetadata

​AgentMetadata.as_dict

​AgentMetadataMode

​OutputPolicy

​OutputPolicy.includes_intermediate_message

​OutputPolicy.includes_event

​TokenUsage

​TokenUsage.as_dict

​TokenUsage.from_dict

Decision events

Raw metadata

Exports

AgentMetadata

AgentMetadata.as_dict

AgentMetadataMode

OutputPolicy

OutputPolicy.includes_intermediate_message

OutputPolicy.includes_event

TokenUsage

TokenUsage.as_dict

TokenUsage.from_dict