harnest.agent

All Python modules · Import and compatibility guidance

Tool declaration

Property	Rule
File	`tools/lookup_order.py`
Export	`lookup_order`
Description	Docstring or `@tool(description="...")`; distinguish similar parameters explicitly
Output validation	Pydantic return annotation or `output_schema`
Runtime permission	`@tool(permission="tickets.read")`; required when the tool must be available under an Agent Runtime Principal
Unit testing	Call the decorated function directly

Private client input contract

Contract	Behavior
Consumer	Async application handler; must return `None`
Model response	Required JSON object in `response`, frozen when the decorator is applied
Accidental return or exception	Fail with a generic error; no returned value or original exception chain reaches the framework
Storage	Process-local, one-time delivery; no automatic asset staging, history, checkpoint, or telemetry projection of the input
Lifetime	Cleared on consumption or cancellation; expired, cancelled, and consumed requests reject subsequent submissions
Timeout	`timeout_seconds`, default `300`
Durable tools	Rejected; private input cannot use a persisted tool continuation

Exports

Name	Kind
`Agent`	Class
`AgentDefinition`	Class
`AgentRuntimePermissionError`	Class
`AgentRuntimePrincipal`	Class
`ClientToolError`	Class
`ClientToolExecution`	Class
`InMemoryClientToolStore`	Class
`PendingClientTool`	Class
`ToolCallRequest`	Class
`ToolLifecycleContext`	Class
`ToolLifecycleError`	Class
`approval`	Module
`client_input`	Function
`client_tool`	Function
`client_tool_execution`	Function
`current_transient_media`	Function
`instruction_file`	Function
`tool`	Function

Agent

Managed agent definition lowered by the selected Harnest backend.

Agent(
    name: str,
    model: ModelInput,
    instruction: str | None = None,
    description: str = '',
    tools: Sequence[Tool] = ...,
    subagents: Sequence['AgentDefinition | _AdvancedAgentDefinition | Any'] = ...,
    mcp: Sequence[MCPClient] = ...,
    input_schema: PydanticModel | None = None,
    output_key: str | None = None,
    output_schema: PydanticModel | None = None,
    generate_content_config: Mapping[str, Any] | Any | None = None,
    history: Literal['session', 'turn'] = 'session',
    sandboxes: Sequence[str] = ...,
    *,
    token_policy: TokenPolicy | None = None,
    skill_selection: DecisionSkillSelector | None = None,
) -> None

Fields (— means no declared default):

Field	Type	Default
`name`	`str`	`—`
`model`	`ModelInput`	`—`
`instruction`	`str \| None`	`None`
`description`	`str`	`''`
`tools`	`Sequence[Tool]`	`tuple()`
`subagents`	`Sequence['AgentDefinition \| _AdvancedAgentDefinition \| Any']`	`tuple()`
`mcp`	`Sequence[MCPClient]`	`tuple()`
`input_schema`	`PydanticModel \| None`	`None`
`output_key`	`str \| None`	`None`
`output_schema`	`PydanticModel \| None`	`None`
`generate_content_config`	`Mapping[str, Any] \| Any \| None`	`None`
`history`	`Literal['session', 'turn']`	`'session'`
`token_policy`	`TokenPolicy \| None`	`None`
`skill_selection`	`DecisionSkillSelector \| None`	`None`
`sandboxes`	`Sequence[str]`	`tuple()`

Parameters and example

Parameter	Type	Default	Description
`name`	`str`	Required	Name of the agent.
`model`	`ModelInput`	Required	Model the agent calls, for example `LiteLLMModel("openai/your-model")`.
`instruction`	`str \| None`	`None`	System instruction. Use `instruction_file(__file__)` to load it from a file.
`description`	`str`	`''`	Short description of what the agent does.
`tools`	`Sequence[Tool]`	`...`	Agent Tools. Usually discovered from `tools/`, so you rarely set this.
`subagents`	`Sequence['AgentDefinition \| _AdvancedAgentDefinition \| Any']`	`...`	SubAgents. Usually discovered from the filesystem.
`mcp`	`Sequence[MCPClient]`	`...`	MCP clients whose tools the agent can use.
`input_schema`	`PydanticModel \| None`	`None`	Pydantic model that validates request `input`.
`output_key`	`str \| None`	`None`	—
`output_schema`	`PydanticModel \| None`	`None`	Pydantic model for structured output, returned as `result`.
`generate_content_config`	`Mapping[str, Any] \| Any \| None`	`None`	—
`history`	`Literal['session', 'turn']`	`'session'`	`"session"` (default) keeps earlier turns; `"turn"` isolates each invocation.
`sandboxes`	`Sequence[str]`	`...`	—
`token_policy`	`TokenPolicy \| None`	`None`	—
`skill_selection`	`DecisionSkillSelector \| None`	`None`	—

from harnest.agent import Agent
from harnest.model import LiteLLMModel

root_agent = Agent(name="support", model=LiteLLMModel("openai/your-model"))

Agent.advanced

Agent.advanced(
    target: Any,
    *,
    name: str | None = None,
    input_adapter: Callable[[str, Mapping[str, Any]], Any] | None = None,
    output_adapter: Callable[[Any], Any] | None = None,
) -> '_AdvancedAgentDefinition'

Wrap a framework-native root, subagent, or graph node. Export the wrapper as the root in advanced mode, or embed it in a managed agent/graph when only one component needs native behavior.

Parameters and example

Parameter	Type	Default
`target`	`Any`	Required
`name`	`str \| None`	`None`
`input_adapter`	`Callable[[str, Mapping[str, Any]], Any] \| None`	`None`
`output_adapter`	`Callable[[Any], Any] \| None`	`None`

from harnest.agent import Agent

definition = Agent.advanced(target=...)

Agent.build

Agent.build() -> Any

Build the underlying ADK agent. ADK is imported lazily so config generation and validation do not need model/runtime dependencies loaded. Sandbox agents retain native flows with a scoped consumed-code continuation compatibility adapter.

Example

from harnest.agent import Agent

agent: Agent
result = agent.build()

AgentDefinition

Managed agent definition lowered by the selected Harnest backend.

AgentDefinition(
    name: str,
    model: ModelInput,
    instruction: str | None = None,
    description: str = '',
    tools: Sequence[Tool] = ...,
    subagents: Sequence['AgentDefinition | _AdvancedAgentDefinition | Any'] = ...,
    mcp: Sequence[MCPClient] = ...,
    input_schema: PydanticModel | None = None,
    output_key: str | None = None,
    output_schema: PydanticModel | None = None,
    generate_content_config: Mapping[str, Any] | Any | None = None,
    history: Literal['session', 'turn'] = 'session',
    sandboxes: Sequence[str] = ...,
    *,
    token_policy: TokenPolicy | None = None,
    skill_selection: DecisionSkillSelector | None = None,
) -> None

Fields (— means no declared default):

Field	Type	Default
`name`	`str`	`—`
`model`	`ModelInput`	`—`
`instruction`	`str \| None`	`None`
`description`	`str`	`''`
`tools`	`Sequence[Tool]`	`tuple()`
`subagents`	`Sequence['AgentDefinition \| _AdvancedAgentDefinition \| Any']`	`tuple()`
`mcp`	`Sequence[MCPClient]`	`tuple()`
`input_schema`	`PydanticModel \| None`	`None`
`output_key`	`str \| None`	`None`
`output_schema`	`PydanticModel \| None`	`None`
`generate_content_config`	`Mapping[str, Any] \| Any \| None`	`None`
`history`	`Literal['session', 'turn']`	`'session'`
`token_policy`	`TokenPolicy \| None`	`None`
`skill_selection`	`DecisionSkillSelector \| None`	`None`
`sandboxes`	`Sequence[str]`	`tuple()`

Parameters and example

Parameter	Type	Default	Description
`name`	`str`	Required	Name of the agent.
`model`	`ModelInput`	Required	Model the agent calls, for example `LiteLLMModel("openai/your-model")`.
`instruction`	`str \| None`	`None`	System instruction. Use `instruction_file(__file__)` to load it from a file.
`description`	`str`	`''`	Short description of what the agent does.
`tools`	`Sequence[Tool]`	`...`	Agent Tools. Usually discovered from `tools/`, so you rarely set this.
`subagents`	`Sequence['AgentDefinition \| _AdvancedAgentDefinition \| Any']`	`...`	SubAgents. Usually discovered from the filesystem.
`mcp`	`Sequence[MCPClient]`	`...`	MCP clients whose tools the agent can use.
`input_schema`	`PydanticModel \| None`	`None`	Pydantic model that validates request `input`.
`output_key`	`str \| None`	`None`	—
`output_schema`	`PydanticModel \| None`	`None`	Pydantic model for structured output, returned as `result`.
`generate_content_config`	`Mapping[str, Any] \| Any \| None`	`None`	—
`history`	`Literal['session', 'turn']`	`'session'`	`"session"` (default) keeps earlier turns; `"turn"` isolates each invocation.
`sandboxes`	`Sequence[str]`	`...`	—
`token_policy`	`TokenPolicy \| None`	`None`	—
`skill_selection`	`DecisionSkillSelector \| None`	`None`	—

from harnest.agent import Agent
from harnest.model import LiteLLMModel

root_agent = Agent(name="support", model=LiteLLMModel("openai/your-model"))

AgentDefinition.advanced

AgentDefinition.advanced(
    target: Any,
    *,
    name: str | None = None,
    input_adapter: Callable[[str, Mapping[str, Any]], Any] | None = None,
    output_adapter: Callable[[Any], Any] | None = None,
) -> '_AdvancedAgentDefinition'

Wrap a framework-native root, subagent, or graph node. Export the wrapper as the root in advanced mode, or embed it in a managed agent/graph when only one component needs native behavior.

Parameters and example

Parameter	Type	Default
`target`	`Any`	Required
`name`	`str \| None`	`None`
`input_adapter`	`Callable[[str, Mapping[str, Any]], Any] \| None`	`None`
`output_adapter`	`Callable[[Any], Any] \| None`	`None`

from harnest.agent import AgentDefinition

definition = AgentDefinition.advanced(target=...)

AgentDefinition.build

AgentDefinition.build() -> Any

Example

from harnest.agent import AgentDefinition

definition: AgentDefinition
result = definition.build()

AgentRuntimePermissionError

A capability is unavailable to the active Agent Runtime Principal.

Example

from harnest.agent import AgentRuntimePermissionError

try:
    ...
except AgentRuntimePermissionError as error:
    ...

AgentRuntimePrincipal

Identify one default-deny invocation and its permission grants.

AgentRuntimePrincipal(permissions: frozenset[str] = ...) -> None

Fields (— means no declared default):

Field	Type	Default
`permissions`	`frozenset[str]`	`frozenset()`
`id`	`str`	`<lambda>()`

Parameters and example

Parameter	Type	Default	Description
`permissions`	`frozenset[str]`	`...`	Permission names granted to this invocation.

from harnest.agent import AgentRuntimePrincipal

principal = AgentRuntimePrincipal.create(permissions={"tickets.read"})

AgentRuntimePrincipal.create

AgentRuntimePrincipal.create(*, permissions: Sequence[str] | set[str] | frozenset[str] = ()) -> AgentRuntimePrincipal

Create an opaque runtime identity from application-authorized grants.

Parameters and example

Parameter	Type	Default	Description
`permissions`	`Sequence[str] \| set[str] \| frozenset[str]`	`()`	Permission names your application authorizes.

from harnest.agent import AgentRuntimePrincipal

principal = AgentRuntimePrincipal.create(permissions={"tickets.read"})

AgentRuntimePrincipal.restrict

AgentRuntimePrincipal.restrict(permissions: Sequence[str] | set[str] | frozenset[str]) -> AgentRuntimePrincipal

Create a fresh principal without permitting authority amplification.

Parameters and example

Parameter	Type	Default	Description
`permissions`	`Sequence[str] \| set[str] \| frozenset[str]`	Required	Subset of the current grants. Adding a new name raises `AgentRuntimePermissionError`.

from harnest.agent import AgentRuntimePrincipal

principal: AgentRuntimePrincipal
read_only = principal.restrict({"tickets.read"})

ClientToolError

A client tool request could not be completed safely.

Example

from harnest.agent import ClientToolError

try:
    ...
except ClientToolError as error:
    ...

ClientToolExecution

Runtime capability visible only while Harnest owns an invocation.

ClientToolExecution(store: InMemoryClientToolStore, run: ApprovalRun) -> None

Fields (— means no declared default):

Field	Type	Default
`store`	`InMemoryClientToolStore`	`—`
`run`	`ApprovalRun`	`—`

Parameters and example

Parameter	Type	Default
`store`	`InMemoryClientToolStore`	Required
`run`	`ApprovalRun`	Required

from harnest.agent import ClientToolExecution

execution = ClientToolExecution(store=..., run=...)

ClientToolExecution.execute

async ClientToolExecution.execute(
    *,
    name: str,
    arguments: dict[str, Any],
    output_schema: PydanticModel | None,
    timeout_seconds: int,
    private_input: bool = False,
) -> Any

Request one client-hosted tool call and await its validated result.

Parameters and example

Parameter	Type	Default
`name`	`str`	Required
`arguments`	`dict[str, Any]`	Required
`output_schema`	`PydanticModel \| None`	Required
`timeout_seconds`	`int`	Required
`private_input`	`bool`	`False`

from harnest.agent import ClientToolExecution

execution: ClientToolExecution
result = await execution.execute(
    name=...,
    arguments=...,
    output_schema=...,
    timeout_seconds=...,
)

ClientToolExecution.transient_media

Return private media access already scoped to this invocation.

Example

from harnest.agent import ClientToolExecution

execution: ClientToolExecution
value = execution.transient_media

InMemoryClientToolStore

Development store for one-time client tool result delivery.

InMemoryClientToolStore(
    *,
    clock: Callable[[], float] = time,
    transient_media: TransientMediaLeaseStore | None = None,
    asset_stores: Mapping[str, AssetStorage] | None = None,
) -> None

Parameters and example

Parameter	Type	Default
`clock`	`Callable[[], float]`	`time`
`transient_media`	`TransientMediaLeaseStore \| None`	`None`
`asset_stores`	`Mapping[str, AssetStorage] \| None`	`None`

from harnest.agent import InMemoryClientToolStore

store = InMemoryClientToolStore()

InMemoryClientToolStore.transient_media

Expose the lease boundary to framework adapters, never to clients.

Example

from harnest.agent import InMemoryClientToolStore

store: InMemoryClientToolStore
value = store.transient_media

InMemoryClientToolStore.suspend

async InMemoryClientToolStore.suspend(
    run: ApprovalRun,
    *,
    name: str,
    arguments: dict[str, Any],
    output_schema: PydanticModel | None,
    timeout_seconds: int,
    private_input: bool = False,
) -> Any

Suspend for one result, transferring private values without retention.

Parameters and example

Parameter	Type	Default
`run`	`ApprovalRun`	Required
`name`	`str`	Required
`arguments`	`dict[str, Any]`	Required
`output_schema`	`PydanticModel \| None`	Required
`timeout_seconds`	`int`	Required
`private_input`	`bool`	`False`

from harnest.agent import InMemoryClientToolStore

store: InMemoryClientToolStore
result = await store.suspend(
    run=...,
    name=...,
    arguments=...,
    output_schema=...,
    timeout_seconds=...,
)

InMemoryClientToolStore.submit

async InMemoryClientToolStore.submit(request_id: str, *, user_id: str, output: Any) -> PendingClientTool

Validate and sanitize a client result before its framework resumes.

Parameters and example

Parameter	Type	Default
`request_id`	`str`	Required
`user_id`	`str`	Required
`output`	`Any`	Required

from harnest.agent import InMemoryClientToolStore

store: InMemoryClientToolStore
tool = await store.submit(request_id=..., user_id=..., output=...)

InMemoryClientToolStore.run_for

InMemoryClientToolStore.run_for(pending: PendingClientTool) -> ApprovalRun

Return the live invocation waiting for a client tool result.

Parameters and example

Parameter	Type	Default
`pending`	`PendingClientTool`	Required

from harnest.agent import InMemoryClientToolStore

store: InMemoryClientToolStore
result = store.run_for(pending=...)

InMemoryClientToolStore.pending_for

InMemoryClientToolStore.pending_for(*, user_id: str, session_id: str) -> list[PendingClientTool]

Resolve live client calls without revealing another session’s work.

Parameters and example

Parameter	Type	Default
`user_id`	`str`	Required
`session_id`	`str`	Required

from harnest.agent import InMemoryClientToolStore

store: InMemoryClientToolStore
result = store.pending_for(user_id=..., session_id=...)

InMemoryClientToolStore.cancel

InMemoryClientToolStore.cancel(request_id: str, *, user_id: str) -> PendingClientTool

Deliver a caller cancellation through the same one-time authority gate.

Parameters and example

Parameter	Type	Default
`request_id`	`str`	Required
`user_id`	`str`	Required

from harnest.agent import InMemoryClientToolStore

store: InMemoryClientToolStore
tool = store.cancel(request_id=..., user_id=...)

PendingClientTool

One principal-scoped client tool call awaiting its result.

PendingClientTool(
    id: str,
    user_id: str,
    session_id: str,
    call_id: str,
    name: str,
    arguments: dict[str, Any],
    output_schema: PydanticModel | None,
    expires_at: float,
    run: ApprovalRun,
    future: asyncio.Future[Any],
    submitting: bool = False,
    agui_tool_call_id: str | None = None,
    private_input: bool = False,
) -> None

Fields (— means no declared default):

Field	Type	Default
`id`	`str`	`—`
`user_id`	`str`	`—`
`session_id`	`str`	`—`
`call_id`	`str`	`—`
`name`	`str`	`—`
`arguments`	`dict[str, Any]`	`—`
`output_schema`	`PydanticModel \| None`	`—`
`expires_at`	`float`	`—`
`run`	`ApprovalRun`	`—`
`future`	`asyncio.Future[Any]`	`—`
`submitting`	`bool`	`False`
`agui_tool_call_id`	`str \| None`	`None`
`private_input`	`bool`	`False`

Parameters and example

Parameter	Type	Default
`id`	`str`	Required
`user_id`	`str`	Required
`session_id`	`str`	Required
`call_id`	`str`	Required
`name`	`str`	Required
`arguments`	`dict[str, Any]`	Required
`output_schema`	`PydanticModel \| None`	Required
`expires_at`	`float`	Required
`run`	`ApprovalRun`	Required
`future`	`asyncio.Future[Any]`	Required
`submitting`	`bool`	`False`
`agui_tool_call_id`	`str \| None`	`None`
`private_input`	`bool`	`False`

from harnest.agent import PendingClientTool

tool = PendingClientTool(
    id=...,
    user_id=...,
    session_id=...,
    call_id=...,
    name=...,
    arguments=...,
    output_schema=...,
    expires_at=...,
    run=...,
    future=...,
)

PendingClientTool.public

PendingClientTool.public() -> dict[str, Any]

Return the client-safe fields required to execute this tool call.

Example

from harnest.agent import PendingClientTool

tool: PendingClientTool
result = tool.public()

ToolCallRequest

Provider-neutral arguments for one managed tool call.

ToolCallRequest(name: str, args: tuple[Any, ...] = (), kwargs: Mapping[str, Any] = ...) -> None

Fields (— means no declared default):

Field	Type	Default
`name`	`str`	`—`
`args`	`tuple[Any, ...]`	`()`
`kwargs`	`Mapping[str, Any]`	`dict()`

Parameters and example

Parameter	Type	Default
`name`	`str`	Required
`args`	`tuple[Any, ...]`	`()`
`kwargs`	`Mapping[str, Any]`	`...`

from harnest.agent import ToolCallRequest

request = ToolCallRequest(name=...)

ToolLifecycleContext

Stable invocation identity associated with one managed tool call.

ToolLifecycleContext(
    framework: str,
    agent_name: str,
    invocation_id: str,
    user_id: str,
    session_id: str,
    tool_name: str,
) -> None

Fields (— means no declared default):

Field	Type	Default
`framework`	`str`	`—`
`agent_name`	`str`	`—`
`invocation_id`	`str`	`—`
`user_id`	`str`	`—`
`session_id`	`str`	`—`
`tool_name`	`str`	`—`

Parameters and example

Parameter	Type	Default
`framework`	`str`	Required
`agent_name`	`str`	Required
`invocation_id`	`str`	Required
`user_id`	`str`	Required
`session_id`	`str`	Required
`tool_name`	`str`	Required

from harnest.agent import ToolLifecycleContext

context = ToolLifecycleContext(
    framework=...,
    agent_name=...,
    invocation_id=...,
    user_id=...,
    session_id=...,
    tool_name=...,
)

ToolLifecycleContext.next

ToolLifecycleContext.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.agent import ToolLifecycleContext

context: ToolLifecycleContext
result = context.next()

ToolLifecycleContext.finish

ToolLifecycleContext.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.agent import ToolLifecycleContext

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

ToolLifecycleError

A tool interceptor returned invalid or ambiguous control flow.

Example

from harnest.agent import ToolLifecycleError

try:
    ...
except ToolLifecycleError as error:
    ...

approval

See harnest.agent.approval for its exports.

client_input

Collect private input for an async handler and return only authored JSON. The handler’s first positional parameter receives the validated private input and is excluded from the model tool signature. Remaining parameters are public request arguments. The handler must return None. response is frozen at declaration time and is the only successful model result.

client_input(
    *,
    input_schema: PydanticModel,
    response: Mapping[str, Any],
    description: str | None = None,
    timeout_seconds: int = 300,
    permission: str | None = None,
) -> Callable[[Callable[..., Awaitable[None]]], Callable[..., Awaitable[dict[str, Any]]]]

Parameters and example

Parameter	Type	Default	Description
`input_schema`	`PydanticModel`	Required	Pydantic model for the private value, passed as the handler’s first parameter.
`response`	`Mapping[str, Any]`	Required	JSON object returned to the model when the handler succeeds.
`description`	`str \| None`	`None`	Description the model sees. Defaults to the docstring.
`timeout_seconds`	`int`	`300`	Seconds to wait for the client’s private value.
`permission`	`str \| None`	`None`	Permission name required under an Agent Runtime Principal.

from harnest.agent import client_input

@client_input(input_schema=ConnectionInput, response={"status": "connected"})
async def connect(private: ConnectionInput, service: str) -> None:
    """Connect a service with a client-supplied token."""
    ...

client_tool

Declare a client tool with an optional runtime-principal permission tag.

client_tool(
    function: F | None = None,
    *,
    description: str | None = None,
    timeout_seconds: int = 300,
    output_schema: PydanticModel | None = None,
    permission: str | None = None,
) -> F | Callable[[F], F]

Parameters and example

Parameter	Type	Default	Description
`function`	`F \| None`	`None`	The stub to decorate. Harnest never runs its body.
`description`	`str \| None`	`None`	Description the model sees. Defaults to the docstring.
`timeout_seconds`	`int`	`300`	Seconds to wait for the client’s result.
`output_schema`	`PydanticModel \| None`	`None`	Pydantic model that validates the client’s result.
`permission`	`str \| None`	`None`	Permission name required under an Agent Runtime Principal.

from harnest.agent import client_tool

@client_tool
def browser_open(url: str) -> dict[str, str]:
    """Open a URL in the connected browser."""
    ...

client_tool_execution

Activate client-tool execution authority for the current context.

client_tool_execution(execution: ClientToolExecution) -> Iterator[None]

Parameters and example

Parameter	Type	Default
`execution`	`ClientToolExecution`	Required

from harnest.agent import client_tool_execution

with client_tool_execution(execution=...):
    ...

current_transient_media

Expose scoped staged bytes only during a managed invocation.

current_transient_media() -> TransientMediaAccess | None

Example

from harnest.agent import current_transient_media

access = current_transient_media()

instruction_file

Read an instruction file relative to a Python module. Pass __file__ as anchor so the path remains correct in a deployed bundle and does not depend on the process working directory.

instruction_file(anchor: str | Path, relative_path: str = 'instructions.md') -> str

Parameters and example

Parameter	Type	Default	Description
`anchor`	`str \| Path`	Required	Pass `__file__` so the path works in a deployed bundle.
`relative_path`	`str`	`'instructions.md'`	File path relative to the anchor’s folder.

from harnest.agent import instruction_file

instruction = instruction_file(__file__)

tool

Mark a typed Python function as a managed Harnest agent tool. Both managed backends wrap callables natively. This decorator preserves the function’s typed signature, checks that the model receives a description, validates an optional Pydantic result, and installs declared execution policy before backend lowering. Durable tools cross a framework-native suspension boundary and therefore must be asynchronous.

tool(
    function: F | None = None,
    *,
    description: str | None = None,
    output_schema: PydanticModel | None = None,
    durable: bool = False,
    permission: str | None = None,
) -> F | Callable[[F], F]

Parameters and example

Parameter	Type	Default	Description
`function`	`F \| None`	`None`	The decorated function. Filled in by bare `@tool`.
`description`	`str \| None`	`None`	Description the model sees. Defaults to the docstring.
`output_schema`	`PydanticModel \| None`	`None`	Pydantic model that validates the result.
`durable`	`bool`	`False`	Let the tool suspend and resume. Must be `async`.
`permission`	`str \| None`	`None`	Permission name required under an Agent Runtime Principal.

from harnest.agent import tool

@tool
def lookup_ticket(ticket_id: str) -> str:
    """Return the current ticket summary."""
    ...

​Tool declaration

​Private client input contract

​Exports

​Agent

​Agent.advanced

​Agent.build

​AgentDefinition

​AgentDefinition.advanced

​AgentDefinition.build

​AgentRuntimePermissionError

​AgentRuntimePrincipal

​AgentRuntimePrincipal.create

​AgentRuntimePrincipal.restrict

​ClientToolError

​ClientToolExecution

​ClientToolExecution.execute

​ClientToolExecution.transient_media

​InMemoryClientToolStore

​InMemoryClientToolStore.transient_media

​InMemoryClientToolStore.suspend

​InMemoryClientToolStore.submit

​InMemoryClientToolStore.run_for

​InMemoryClientToolStore.pending_for

​InMemoryClientToolStore.cancel

​PendingClientTool

​PendingClientTool.public

​ToolCallRequest

​ToolLifecycleContext

​ToolLifecycleContext.next

​ToolLifecycleContext.finish

​ToolLifecycleError

​approval

​client_input

​client_tool

​client_tool_execution

​current_transient_media

​instruction_file

​tool

Tool declaration

Private client input contract

Exports

Agent

Agent.advanced

Agent.build

AgentDefinition

AgentDefinition.advanced

AgentDefinition.build

AgentRuntimePermissionError

AgentRuntimePrincipal

AgentRuntimePrincipal.create

AgentRuntimePrincipal.restrict

ClientToolError

ClientToolExecution

ClientToolExecution.execute

ClientToolExecution.transient_media

InMemoryClientToolStore

InMemoryClientToolStore.transient_media

InMemoryClientToolStore.suspend

InMemoryClientToolStore.submit

InMemoryClientToolStore.run_for

InMemoryClientToolStore.pending_for

InMemoryClientToolStore.cancel

PendingClientTool

PendingClientTool.public

ToolCallRequest

ToolLifecycleContext

ToolLifecycleContext.next

ToolLifecycleContext.finish

ToolLifecycleError

approval

client_input

client_tool

client_tool_execution

current_transient_media

instruction_file

tool