> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# harnest.output

> Public Python signatures, fields, and methods.

[All Python modules](https://usefused.com/docs/harnest/reference/api/overview.md) · [Import and compatibility guidance](https://usefused.com/docs/harnest/build/python-imports.md)

## 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`](#agentmetadata) | Class |
| [`AgentMetadataMode`](#agentmetadatamode) | Class |
| [`OutputPolicy`](#outputpolicy) | Class |
| [`TokenUsage`](#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.

```python theme={null}
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` |

> [accordion] 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` |
>
> ```python theme={null}
> from harnest.output import AgentMetadata
>
> metadata = AgentMetadata(framework=...)
> ```

### AgentMetadata.as\_dict

```python theme={null}
AgentMetadata.as_dict() -> dict[str, Any]
```

Return the stable public representation without empty optional fields.

> [accordion] Example
>
> ```python theme={null}
> from harnest.output import AgentMetadata
>
> metadata: AgentMetadata
> result = metadata.as_dict()
> ```

## AgentMetadataMode

Select how much model and provider metadata callers receive.

```python theme={null}
AgentMetadataMode(*values)
```

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

> [accordion] Example
>
> ```python theme={null}
> from harnest.output import AgentMetadataMode
>
> value = AgentMetadataMode.SUPPRESS
> ```

## OutputPolicy

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

```python theme={null}
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` |

> [accordion] 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` |
>
> ```python theme={null}
> from harnest.output import OutputPolicy
>
> policy = OutputPolicy()
> ```

### OutputPolicy.includes\_intermediate\_message

```python theme={null}
OutputPolicy.includes_intermediate_message(*, has_tool_calls: bool) -> bool
```

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

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `has_tool_calls` | `bool` | Required |
>
> ```python theme={null}
> from harnest.output import OutputPolicy
>
> policy: OutputPolicy
> result = policy.includes_intermediate_message(has_tool_calls=...)
> ```

### OutputPolicy.includes\_event

```python theme={null}
OutputPolicy.includes_event(event_type: str) -> bool
```

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

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `event_type` | `str` | Required |
>
> ```python theme={null}
> from harnest.output import OutputPolicy
>
> policy: OutputPolicy
> result = policy.includes_event(event_type=...)
> ```

## TokenUsage

Provider-reported token counts normalized across ADK and LangGraph.

```python theme={null}
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` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `input_tokens` | `int` | Required |
> | `output_tokens` | `int` | Required |
> | `total_tokens` | `int` | Required |
>
> ```python theme={null}
> from harnest.output import TokenUsage
>
> usage = TokenUsage(input_tokens=..., output_tokens=..., total_tokens=...)
> ```

### TokenUsage.as\_dict

```python theme={null}
TokenUsage.as_dict() -> dict[str, int]
```

Return the camel-case representation used by public transports.

> [accordion] Example
>
> ```python theme={null}
> from harnest.output import TokenUsage
>
> usage: TokenUsage
> result = usage.as_dict()
> ```

### TokenUsage.from\_dict

```python theme={null}
TokenUsage.from_dict(value: Mapping[str, Any]) -> 'TokenUsage'
```

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

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `value` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.output import TokenUsage
>
> usage = TokenUsage.from_dict(value=...)
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.