Client-hosted tools

Use @client_tool when the connected client—not the agent server—owns execution.

from harnest.tool import client_tool


@client_tool
def browser_open(url: str) -> dict[str, str]:
    """Open a URL and return visible page data."""
    ...

Harnest never executes the declaration body. It suspends the invocation and asks the client to run the tool.

Client-tool properties

Property	Rule
Declaration	Typed stub under `tools/`
Execution	Connected browser, desktop, or mobile host
Output	Validated before the agent resumes
Policy	Client owns local execution and sandboxing
Runtime requirement	Active managed Harnest invocation

Transport flow

Transport	Request	Resume
JSON	`requires_action`	`POST /client-tools/{requestId}`
SSE	`client_tool` required action	`POST /client-tools/{requestId}`
WebSocket	`client_tool.requested`	`client_tool.result`

The submitted result is identity-bound, one-time, and validated against the declared return type.

Combine with approval

@client_tool and @require_human_approval can appear in either decorator order. Approval runs first. After approval, the host receives the client-tool request.

Human approvals

Bind approval to the exact user, session, invocation, action, and arguments.

Serving agents

Implement approval and client-tool responses over each transport.

Overview

Get started

Guides

Client-hosted tools

Client-tool properties

Transport flow

Combine with approval

Human approvals

Serving agents

​Client-tool properties

​Transport flow

​Combine with approval

Human approvals

Serving agents

Client-tool properties

Transport flow

Combine with approval