> ## 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.runtime

> 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)

## Exports

| Name | Kind |
| - | - |
| [`AgentExecutionTimeout`](#agentexecutiontimeout) | Class |
| [`AgentInfo`](#agentinfo) | Class |
| [`AgentRuntimeError`](#agentruntimeerror) | Class |
| [`InvocationRequest`](#invocationrequest) | Class |
| [`InvocationResult`](#invocationresult) | Class |
| [`NoCustomerFacingOutputError`](#nocustomerfacingoutputerror) | Class |
| [`ResponseRequest`](#responserequest) | Class |
| [`RuntimeDriver`](#runtimedriver) | Class |
| [`RuntimeEvent`](#runtimeevent) | Value or type alias |
| [`SessionConflictError`](#sessionconflicterror) | Class |
| [`SessionMessage`](#sessionmessage) | Class |
| [`SessionRecord`](#sessionrecord) | Class |
| [`create_fastapi_app`](#create_fastapi_app) | Function |
| [`load_agent_card`](#load_agent_card) | Function |
| [`load_compiled_agent`](#load_compiled_agent) | Function |
| [`load_compiled_app`](#load_compiled_app) | Function |
| [`load_compiled_application`](#load_compiled_application) | Function |
| [`run_agent_message`](#run_agent_message) | Function |

## AgentExecutionTimeout

An invocation exceeded its configured deadline.

> [accordion] Example
>
> ```python theme={null}
> from harnest.runtime import AgentExecutionTimeout
>
> try:
>     ...
> except AgentExecutionTimeout as error:
>     ...
> ```

## AgentInfo

Portable metadata needed by every Harnest transport.

```python theme={null}
AgentInfo(
    id: str,
    name: str,
    description: str,
    card: Mapping[str, Any],
    framework: str | None = None,
    mode: str | None = None,
    extra_endpoints: Mapping[str, str] = ...,
    input_schema: Any = None,
    output_schema: Any = None,
    lifecycle_coverage: Mapping[str, str] = ...,
    agent_principal_projection_complete: bool = False,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `id` | `str` | `—` |
| `name` | `str` | `—` |
| `description` | `str` | `—` |
| `card` | `Mapping[str, Any]` | `—` |
| `framework` | `str \| None` | `None` |
| `mode` | `str \| None` | `None` |
| `extra_endpoints` | `Mapping[str, str]` | `dict()` |
| `input_schema` | `Any` | `None` |
| `output_schema` | `Any` | `None` |
| `lifecycle_coverage` | `Mapping[str, str]` | `dict()` |
| `agent_principal_projection_complete` | `bool` | `False` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `id` | `str` | Required |
> | `name` | `str` | Required |
> | `description` | `str` | Required |
> | `card` | `Mapping[str, Any]` | Required |
> | `framework` | `str \| None` | `None` |
> | `mode` | `str \| None` | `None` |
> | `extra_endpoints` | `Mapping[str, str]` | `...` |
> | `input_schema` | `Any` | `None` |
> | `output_schema` | `Any` | `None` |
> | `lifecycle_coverage` | `Mapping[str, str]` | `...` |
> | `agent_principal_projection_complete` | `bool` | `False` |
>
> ```python theme={null}
> from harnest.runtime import AgentInfo
>
> info = AgentInfo(id=..., name=..., description=..., card=...)
> ```

## AgentRuntimeError

A compiled artifact cannot be loaded or served safely.

> [accordion] Example
>
> ```python theme={null}
> from harnest.runtime import AgentRuntimeError
>
> try:
>     ...
> except AgentRuntimeError as error:
>     ...
> ```

## InvocationRequest

The complete input passed from a transport to a runtime driver.

```python theme={null}
InvocationRequest(
    input: Any,
    user_id: str,
    session_id: str,
    invocation_id: str,
    metadata: Mapping[str, Any],
    state_delta: Mapping[str, Any],
    transport: str | None = None,
    agent_principal: AgentRuntimePrincipal | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `input` | `Any` | `—` |
| `user_id` | `str` | `—` |
| `session_id` | `str` | `—` |
| `invocation_id` | `str` | `—` |
| `metadata` | `Mapping[str, Any]` | `—` |
| `state_delta` | `Mapping[str, Any]` | `—` |
| `transport` | `str \| None` | `None` |
| `agent_principal` | `AgentRuntimePrincipal \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `input` | `Any` | Required |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `invocation_id` | `str` | Required |
> | `metadata` | `Mapping[str, Any]` | Required |
> | `state_delta` | `Mapping[str, Any]` | Required |
> | `transport` | `str \| None` | `None` |
> | `agent_principal` | `AgentRuntimePrincipal \| None` | `None` |
>
> ```python theme={null}
> from harnest.runtime import InvocationRequest
>
> request = InvocationRequest(
>     input=...,
>     user_id=...,
>     session_id=...,
>     invocation_id=...,
>     metadata=...,
>     state_delta=...,
> )
> ```

## InvocationResult

The normalized result of a non-streaming invocation.

```python theme={null}
InvocationResult(
    text: str,
    events: Sequence[RuntimeEvent],
    result: Any,
    session_id: str,
    metadata: Mapping[str, Any],
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `text` | `str` | `—` |
| `events` | `Sequence[RuntimeEvent]` | `—` |
| `result` | `Any` | `—` |
| `session_id` | `str` | `—` |
| `metadata` | `Mapping[str, Any]` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `text` | `str` | Required |
> | `events` | `Sequence[RuntimeEvent]` | Required |
> | `result` | `Any` | Required |
> | `session_id` | `str` | Required |
> | `metadata` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.runtime import InvocationResult
>
> result = InvocationResult(
>     text=...,
>     events=...,
>     result=...,
>     session_id=...,
>     metadata=...,
> )
> ```

## NoCustomerFacingOutputError

Raised when a completed invocation contains no public answer or result.

> [accordion] Example
>
> ```python theme={null}
> from harnest.runtime import NoCustomerFacingOutputError
>
> try:
>     ...
> except NoCustomerFacingOutputError as error:
>     ...
> ```

## ResponseRequest

Strict Pydantic body accepted by default by `POST /responses`.

```python theme={null}
ResponseRequest(
    *,
    sessionId: str | None = None,
    stream: bool = False,
    metadata: dict[str, Any] = ...,
    input: str,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `session_id` | `str \| None` | `None` |
| `stream` | `bool` | `False` |
| `metadata` | `dict[str, Any]` | `dict()` |
| `input` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `sessionId` | `str \| None` | `None` | — |
> | `stream` | `bool` | `False` | Set true for text/event-stream (SSE); false returns one JSON response. |
> | `metadata` | `dict[str, Any]` | `...` | Optional caller metadata. Does not set authentication or user identity. |
> | `input` | `str` | Required | Non-empty message to send to the agent. |
>
> ```python theme={null}
> from harnest.runtime import ResponseRequest
>
> request = ResponseRequest(input=...)
> ```

## RuntimeDriver

The only interface transports require from a framework runtime.

```python theme={null}
RuntimeDriver(*args, **kwargs)
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.runtime import RuntimeDriver
>
> class MyRuntimeDriver(RuntimeDriver):
>     ...
> ```

### RuntimeDriver.info

Return immutable metadata and structured input/output contracts.

> [accordion] Example
>
> ```python theme={null}
> from harnest.runtime import RuntimeDriver
>
> driver: RuntimeDriver
> value = driver.info
> ```

### RuntimeDriver.create\_session

```python theme={null}
async RuntimeDriver.create_session(*, session_id: str, user_id: str, state: Mapping[str, Any]) -> SessionRecord
```

Create one identity-scoped session or report a conflict.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `session_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `state` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.runtime import RuntimeDriver
>
> driver: RuntimeDriver
> record = await driver.create_session(session_id=..., user_id=..., state=...)
> ```

### RuntimeDriver.get\_session

```python theme={null}
async RuntimeDriver.get_session(*, session_id: str, user_id: str) -> SessionRecord | None
```

Resolve one session without revealing another identity's records.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `session_id` | `str` | Required |
> | `user_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.runtime import RuntimeDriver
>
> driver: RuntimeDriver
> record = await driver.get_session(session_id=..., user_id=...)
> ```

### RuntimeDriver.list\_sessions

```python theme={null}
async RuntimeDriver.list_sessions(*, user_id: str, after: str | None = None, limit: int | None = None) -> Sequence[SessionRecord]
```

List a bounded identity-scoped page after an optional key.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `after` | `str \| None` | `None` |
> | `limit` | `int \| None` | `None` |
>
> ```python theme={null}
> from harnest.runtime import RuntimeDriver
>
> driver: RuntimeDriver
> result = await driver.list_sessions(user_id=...)
> ```

### RuntimeDriver.get\_session\_messages

```python theme={null}
async RuntimeDriver.get_session_messages(*, session_id: str, user_id: str) -> Sequence[SessionMessage] | None
```

Return an owned transcript while preserving native metadata.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `session_id` | `str` | Required |
> | `user_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.runtime import RuntimeDriver
>
> driver: RuntimeDriver
> result = await driver.get_session_messages(session_id=..., user_id=...)
> ```

### RuntimeDriver.update\_session

```python theme={null}
async RuntimeDriver.update_session(*, session_id: str, user_id: str, state_delta: Mapping[str, Any]) -> SessionRecord | None
```

Apply one state delta inside the session ownership boundary.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `session_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `state_delta` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.runtime import RuntimeDriver
>
> driver: RuntimeDriver
> record = await driver.update_session(session_id=..., user_id=..., state_delta=...)
> ```

### RuntimeDriver.delete\_session

```python theme={null}
async RuntimeDriver.delete_session(*, session_id: str, user_id: str) -> bool
```

Delete one owned session and report whether it existed.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `session_id` | `str` | Required |
> | `user_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.runtime import RuntimeDriver
>
> driver: RuntimeDriver
> result = await driver.delete_session(session_id=..., user_id=...)
> ```

### RuntimeDriver.invoke

```python theme={null}
async RuntimeDriver.invoke(request: InvocationRequest) -> InvocationResult
```

Run one complete non-streaming portable invocation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `request` | `InvocationRequest` | Required |
>
> ```python theme={null}
> from harnest.runtime import RuntimeDriver
>
> driver: RuntimeDriver
> result = await driver.invoke(request=...)
> ```

### RuntimeDriver.stream

```python theme={null}
RuntimeDriver.stream(request: InvocationRequest) -> AsyncIterator[RuntimeEvent]
```

Yield normalized events for one portable invocation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `request` | `InvocationRequest` | Required |
>
> ```python theme={null}
> from harnest.runtime import RuntimeDriver
>
> driver: RuntimeDriver
> result = driver.stream(request=...)
> ```

### RuntimeDriver.close

```python theme={null}
async RuntimeDriver.close() -> None
```

Release framework and application resources idempotently.

> [accordion] Example
>
> ```python theme={null}
> from harnest.runtime import RuntimeDriver
>
> driver: RuntimeDriver
> await driver.close()
> ```

## RuntimeEvent

```python theme={null}
RuntimeEvent = dict[str, Any]
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.runtime import RuntimeEvent
> ```

## SessionConflictError

Raised by a driver when a requested session id already exists.

> [accordion] Example
>
> ```python theme={null}
> from harnest.runtime import SessionConflictError
>
> try:
>     ...
> except SessionConflictError as error:
>     ...
> ```

## SessionMessage

One portable transcript item with lossless framework-owned metadata.

```python theme={null}
SessionMessage(
    id: str,
    role: str,
    content: Any,
    created_at: str | None = None,
    metadata: Mapping[str, Any] = ...,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `id` | `str` | `—` |
| `role` | `str` | `—` |
| `content` | `Any` | `—` |
| `created_at` | `str \| None` | `None` |
| `metadata` | `Mapping[str, Any]` | `dict()` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `id` | `str` | Required |
> | `role` | `str` | Required |
> | `content` | `Any` | Required |
> | `created_at` | `str \| None` | `None` |
> | `metadata` | `Mapping[str, Any]` | `...` |
>
> ```python theme={null}
> from harnest.runtime import SessionMessage
>
> message = SessionMessage(id=..., role=..., content=...)
> ```

## SessionRecord

A backend-independent view of a persisted agent session.

```python theme={null}
SessionRecord(
    id: str,
    user_id: str,
    state: Mapping[str, Any],
    created_at: str | None = None,
    updated_at: str | None = None,
    metadata: Mapping[str, Any] = ...,
    application_data: Mapping[str, Any] = ...,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `id` | `str` | `—` |
| `user_id` | `str` | `—` |
| `state` | `Mapping[str, Any]` | `—` |
| `created_at` | `str \| None` | `None` |
| `updated_at` | `str \| None` | `None` |
| `metadata` | `Mapping[str, Any]` | `dict()` |
| `application_data` | `Mapping[str, Any]` | `dict()` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `state` | `Mapping[str, Any]` | Required |
> | `created_at` | `str \| None` | `None` |
> | `updated_at` | `str \| None` | `None` |
> | `metadata` | `Mapping[str, Any]` | `...` |
> | `application_data` | `Mapping[str, Any]` | `...` |
>
> ```python theme={null}
> from harnest.runtime import SessionRecord
>
> record = SessionRecord(id=..., user_id=..., state=...)
> ```

## create\_fastapi\_app

Build a server with explicit policy and no UI when production assets are absent.

```python theme={null}
create_fastapi_app(
    artifact: str | Path,
    *,
    bind_host: str = '127.0.0.1',
    request_timeout: float = 300,
    max_concurrency: int = 8,
    max_request_bytes: int = 1048576,
    playground_enabled: bool = True,
    openapi_enabled: bool = True,
    live_enabled: bool = True,
    agui_enabled: bool = True,
    agent_principal_required: bool = False,
    adk_session_storage: ADKSessionStorage | None = None,
    langgraph_session_store: SessionStore | None = None,
    authenticator: Authenticator | None = None,
) -> Any
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `artifact` | `str \| Path` | Required |
> | `bind_host` | `str` | `'127.0.0.1'` |
> | `request_timeout` | `float` | `300` |
> | `max_concurrency` | `int` | `8` |
> | `max_request_bytes` | `int` | `1048576` |
> | `playground_enabled` | `bool` | `True` |
> | `openapi_enabled` | `bool` | `True` |
> | `live_enabled` | `bool` | `True` |
> | `agui_enabled` | `bool` | `True` |
> | `agent_principal_required` | `bool` | `False` |
> | `adk_session_storage` | `ADKSessionStorage \| None` | `None` |
> | `langgraph_session_store` | `SessionStore \| None` | `None` |
> | `authenticator` | `Authenticator \| None` | `None` |
>
> ```python theme={null}
> from harnest.runtime import create_fastapi_app
>
> result = create_fastapi_app(artifact=...)
> ```

## load\_agent\_card

Load the compiled YAML or JSON Agent Card.

```python theme={null}
load_agent_card(artifact: str | Path) -> dict[str, Any]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `artifact` | `str \| Path` | Required |
>
> ```python theme={null}
> from harnest.runtime import load_agent_card
>
> result = load_agent_card(artifact=...)
> ```

## load\_compiled\_agent

Load the selected framework's managed or advanced target.

```python theme={null}
load_compiled_agent(artifact: str | Path) -> Any
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `artifact` | `str \| Path` | Required |
>
> ```python theme={null}
> from harnest.runtime import load_compiled_agent
>
> result = load_compiled_agent(artifact=...)
> ```

## load\_compiled\_app

Load the native ADK App from an ADK compiled artifact.

```python theme={null}
load_compiled_app(artifact: str | Path) -> Any
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `artifact` | `str \| Path` | Required |
>
> ```python theme={null}
> from harnest.runtime import load_compiled_app
>
> result = load_compiled_app(artifact=...)
> ```

## load\_compiled\_application

Load the application and retain authored namespaces for lazy imports.

```python theme={null}
load_compiled_application(artifact: str | Path) -> Any
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `artifact` | `str \| Path` | Required |
>
> ```python theme={null}
> from harnest.runtime import load_compiled_application
>
> result = load_compiled_application(artifact=...)
> ```

## run\_agent\_message

Run one request through the same driver used by the HTTP server.

```python theme={null}
async run_agent_message(
    artifact: str | Path,
    message: str,
    *,
    request_timeout: float = 300,
    agent_principal: AgentRuntimePrincipal | None = None,
) -> dict[str, Any]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `artifact` | `str \| Path` | Required |
> | `message` | `str` | Required |
> | `request_timeout` | `float` | `300` |
> | `agent_principal` | `AgentRuntimePrincipal \| None` | `None` |
>
> ```python theme={null}
> from harnest.runtime import run_agent_message
>
> result = await run_agent_message(artifact=..., message=...)
> ```


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