harnest.http

All Python modules · Import and compatibility guidance

Exports

Name	Kind
`AgentInvoker`	Class
`AgentResponse`	Class
`HTTPCallRequest`	Class
`HTTPLifecycleContext`	Class
`HTTPLifecycleError`	Class
`HTTPResponseHead`	Class
`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.

Example

from harnest.http import AgentInvoker

invoker: AgentInvoker  # returned by Harnest, not constructed directly

AgentInvoker.invoke

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.

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`

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.

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`

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`

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.

Example

from harnest.http import AgentResponse

response: AgentResponse
value = response.approval_id

AgentResponse.as_dict

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

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

Example

from harnest.http import AgentResponse

response: AgentResponse
result = response.as_dict()

HTTPCallRequest

The routing fields a server interceptor may inspect or replace.

HTTPCallRequest(method: str, path: str) -> None

Fields (— means no declared default):

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

Parameters and example

Parameter	Type	Default
`method`	`str`	Required
`path`	`str`	Required

from harnest.http import HTTPCallRequest

request = HTTPCallRequest(method=..., path=...)

HTTPLifecycleContext

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

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`

Parameters and example

Parameter	Type	Default
`transport`	`str`	Required
`method`	`str`	Required
`path`	`str`	Required
`user_id`	`str \| None`	`None`

from harnest.http import HTTPLifecycleContext

context = HTTPLifecycleContext(transport=..., method=..., path=...)

HTTPLifecycleContext.next

HTTPLifecycleContext.next(replacement: Any = UNCHANGED) -> Next[Any]

Continue normally or pass a replacement to the next interceptor.

Parameters and example

Parameter	Type	Default
`replacement`	`Any`	`UNCHANGED`

from harnest.http import HTTPLifecycleContext

context: HTTPLifecycleContext
result = context.next()

HTTPLifecycleContext.finish

HTTPLifecycleContext.finish(result: ResultT) -> Finish[ResultT]

Return a final value without advancing to later execution.

Parameters and example

Parameter	Type	Default
`result`	`ResultT`	Required

from harnest.http import HTTPLifecycleContext

context: HTTPLifecycleContext
result = context.finish(result=...)

HTTPLifecycleError

An HTTP interceptor returned invalid or unsafe control flow.

Example

from harnest.http import HTTPLifecycleError

try:
    ...
except HTTPLifecycleError as error:
    ...

HTTPResponseHead

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

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], ...]`	`()`

Parameters and example

Parameter	Type	Default
`status_code`	`int`	Required
`headers`	`tuple[tuple[bytes, bytes], ...]`	`()`

from harnest.http import HTTPResponseHead

head = HTTPResponseHead(status_code=...)

HTTPRouteError

An authored HTTP route violates Harnest’s server contract.

Example

from harnest.http import HTTPRouteError

try:
    ...
except HTTPRouteError as error:
    ...

Overview

Get started

Harnest Studio

Guides

API reference

harnest.http

Exports

AgentInvoker

AgentInvoker.invoke

AgentResponse

AgentResponse.approval_id

AgentResponse.as_dict

HTTPCallRequest

HTTPLifecycleContext

HTTPLifecycleContext.next

HTTPLifecycleContext.finish

HTTPLifecycleError

HTTPResponseHead

HTTPRouteError

​Exports

​AgentInvoker

​AgentInvoker.invoke

​AgentResponse

​AgentResponse.approval_id

​AgentResponse.as_dict

​HTTPCallRequest

​HTTPLifecycleContext

​HTTPLifecycleContext.next

​HTTPLifecycleContext.finish

​HTTPLifecycleError

​HTTPResponseHead

​HTTPRouteError

Exports

AgentInvoker

AgentInvoker.invoke

AgentResponse

AgentResponse.approval_id

AgentResponse.as_dict

HTTPCallRequest

HTTPLifecycleContext

HTTPLifecycleContext.next

HTTPLifecycleContext.finish

HTTPLifecycleError

HTTPResponseHead

HTTPRouteError