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

> 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 |
| - | - |
| [`AgentInvoker`](#agentinvoker) | Class |
| [`AgentResponse`](#agentresponse) | Class |
| [`HTTPCallRequest`](#httpcallrequest) | Class |
| [`HTTPLifecycleContext`](#httplifecyclecontext) | Class |
| [`HTTPLifecycleError`](#httplifecycleerror) | Class |
| [`HTTPResponseHead`](#httpresponsehead) | Class |
| [`HTTPRouteError`](#httprouteerror) | Class |

## AgentInvoker

Server-bound capability for invoking the compiled root agent.

Obtain this object from the owning Harnest API; its constructor includes runtime bindings.

> [accordion] Example
>
> ```python theme={null}
> from harnest.http import AgentInvoker
>
> invoker: AgentInvoker  # returned by Harnest, not constructed directly
> ```

### AgentInvoker.invoke

```python theme={null}
async AgentInvoker.invoke(
    *,
    connection: Any,
    input: Any,
    session_id: str | None = None,
    metadata: Mapping[str, Any] | None = None,
    agent_principal: AgentRuntimePrincipal | None = None,
) -> AgentResponse
```

Invoke with an optional application-authorized runtime principal.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `connection` | `Any` | Required |
> | `input` | `Any` | Required |
> | `session_id` | `str \| None` | `None` |
> | `metadata` | `Mapping[str, Any] \| None` | `None` |
> | `agent_principal` | `AgentRuntimePrincipal \| None` | `None` |
>
> ```python theme={null}
> from harnest.http import AgentInvoker
>
> invoker: AgentInvoker
> response = await invoker.invoke(connection=..., input=...)
> ```

## AgentResponse

Typed outcome returned when a custom endpoint invokes the root agent.

```python theme={null}
AgentResponse(
    id: str,
    session_id: str,
    status: str,
    output_text: str,
    output: tuple[Mapping[str, Any], ...],
    metadata: Mapping[str, Any],
    result: Any = None,
    required_action: Mapping[str, Any] | None = None,
    usage: TokenUsage | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `id` | `str` | `—` |
| `session_id` | `str` | `—` |
| `status` | `str` | `—` |
| `output_text` | `str` | `—` |
| `output` | `tuple[Mapping[str, Any], ...]` | `—` |
| `metadata` | `Mapping[str, Any]` | `—` |
| `result` | `Any` | `None` |
| `required_action` | `Mapping[str, Any] \| None` | `None` |
| `usage` | `TokenUsage \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `status` | `str` | Required |
> | `output_text` | `str` | Required |
> | `output` | `tuple[Mapping[str, Any], ...]` | Required |
> | `metadata` | `Mapping[str, Any]` | Required |
> | `result` | `Any` | `None` |
> | `required_action` | `Mapping[str, Any] \| None` | `None` |
> | `usage` | `TokenUsage \| None` | `None` |
>
> ```python theme={null}
> from harnest.http import AgentResponse
>
> response = AgentResponse(
>     id=...,
>     session_id=...,
>     status=...,
>     output_text=...,
>     output=...,
>     metadata=...,
> )
> ```

### AgentResponse.approval\_id

Return the pending human-approval ID when this response requires it.

> [accordion] Example
>
> ```python theme={null}
> from harnest.http import AgentResponse
>
> response: AgentResponse
> value = response.approval_id
> ```

### AgentResponse.as\_dict

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

Render the same JSON contract returned by Harnest's response endpoint.

> [accordion] Example
>
> ```python theme={null}
> from harnest.http import AgentResponse
>
> response: AgentResponse
> result = response.as_dict()
> ```

## HTTPCallRequest

The routing fields a server interceptor may inspect or replace.

```python theme={null}
HTTPCallRequest(method: str, path: str) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `method` | `str` | `—` |
| `path` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `method` | `str` | Required |
> | `path` | `str` | Required |
>
> ```python theme={null}
> from harnest.http import HTTPCallRequest
>
> request = HTTPCallRequest(method=..., path=...)
> ```

## HTTPLifecycleContext

Stable request identity without headers, cookies, bodies, or credentials.

```python theme={null}
HTTPLifecycleContext(transport: str, method: str, path: str, user_id: str | None = None) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `transport` | `str` | `—` |
| `method` | `str` | `—` |
| `path` | `str` | `—` |
| `user_id` | `str \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `transport` | `str` | Required |
> | `method` | `str` | Required |
> | `path` | `str` | Required |
> | `user_id` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.http import HTTPLifecycleContext
>
> context = HTTPLifecycleContext(transport=..., method=..., path=...)
> ```

### HTTPLifecycleContext.next

```python theme={null}
HTTPLifecycleContext.next(replacement: Any = UNCHANGED) -> Next[Any]
```

Continue normally or pass a replacement to the next interceptor.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `replacement` | `Any` | `UNCHANGED` |
>
> ```python theme={null}
> from harnest.http import HTTPLifecycleContext
>
> context: HTTPLifecycleContext
> result = context.next()
> ```

### HTTPLifecycleContext.finish

```python theme={null}
HTTPLifecycleContext.finish(result: ResultT) -> Finish[ResultT]
```

Return a final value without advancing to later execution.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `result` | `ResultT` | Required |
>
> ```python theme={null}
> from harnest.http import HTTPLifecycleContext
>
> context: HTTPLifecycleContext
> result = context.finish(result=...)
> ```

## HTTPLifecycleError

An HTTP interceptor returned invalid or unsafe control flow.

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

## HTTPResponseHead

A response status and opaque raw headers available before body emission.

```python theme={null}
HTTPResponseHead(status_code: int, headers: tuple[tuple[bytes, bytes], ...] = ()) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `status_code` | `int` | `—` |
| `headers` | `tuple[tuple[bytes, bytes], ...]` | `()` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `status_code` | `int` | Required |
> | `headers` | `tuple[tuple[bytes, bytes], ...]` | `()` |
>
> ```python theme={null}
> from harnest.http import HTTPResponseHead
>
> head = HTTPResponseHead(status_code=...)
> ```

## HTTPRouteError

An authored HTTP route violates Harnest's server contract.

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


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