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

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

## 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`](#agent) | Class |
| [`AgentDefinition`](#agentdefinition) | Class |
| [`AgentRuntimePermissionError`](#agentruntimepermissionerror) | Class |
| [`AgentRuntimePrincipal`](#agentruntimeprincipal) | Class |
| [`ClientToolError`](#clienttoolerror) | Class |
| [`ClientToolExecution`](#clienttoolexecution) | Class |
| [`InMemoryClientToolStore`](#inmemoryclienttoolstore) | Class |
| [`PendingClientTool`](#pendingclienttool) | Class |
| [`ToolCallRequest`](#toolcallrequest) | Class |
| [`ToolLifecycleContext`](#toollifecyclecontext) | Class |
| [`ToolLifecycleError`](#toollifecycleerror) | Class |
| [`approval`](#approval) | Module |
| [`client_input`](#client_input) | Function |
| [`client_tool`](#client_tool) | Function |
| [`client_tool_execution`](#client_tool_execution) | Function |
| [`current_transient_media`](#current_transient_media) | Function |
| [`instruction_file`](#instruction_file) | Function |
| [`tool`](#tool) | Function |

## Agent

Managed agent definition lowered by the selected Harnest backend.

```python theme={null}
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()` |

> [accordion] 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` | — |
>
> ```python theme={null}
> from harnest.agent import Agent
> from harnest.model import LiteLLMModel
>
> root_agent = Agent(name="support", model=LiteLLMModel("openai/your-model"))
> ```

### Agent.advanced

```python theme={null}
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.

> [accordion] 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` |
>
> ```python theme={null}
> from harnest.agent import Agent
>
> definition = Agent.advanced(target=...)
> ```

### Agent.build

```python theme={null}
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.

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent import Agent
>
> agent: Agent
> result = agent.build()
> ```

## AgentDefinition

Managed agent definition lowered by the selected Harnest backend.

```python theme={null}
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()` |

> [accordion] 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` | — |
>
> ```python theme={null}
> from harnest.agent import Agent
> from harnest.model import LiteLLMModel
>
> root_agent = Agent(name="support", model=LiteLLMModel("openai/your-model"))
> ```

### AgentDefinition.advanced

```python theme={null}
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.

> [accordion] 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` |
>
> ```python theme={null}
> from harnest.agent import AgentDefinition
>
> definition = AgentDefinition.advanced(target=...)
> ```

### AgentDefinition.build

```python theme={null}
AgentDefinition.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.

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent import AgentDefinition
>
> definition: AgentDefinition
> result = definition.build()
> ```

## AgentRuntimePermissionError

A capability is unavailable to the active Agent Runtime Principal.

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

## AgentRuntimePrincipal

Identify one default-deny invocation and its permission grants.

```python theme={null}
AgentRuntimePrincipal(permissions: frozenset[str] = ...) -> None
```

Fields (`—` means no declared default):

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

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `permissions` | `frozenset[str]` | `...` | Permission names granted to this invocation. |
>
> ```python theme={null}
> from harnest.agent import AgentRuntimePrincipal
>
> principal = AgentRuntimePrincipal.create(permissions={"tickets.read"})
> ```

### AgentRuntimePrincipal.create

```python theme={null}
AgentRuntimePrincipal.create(*, permissions: Sequence[str] | set[str] | frozenset[str] = ()) -> AgentRuntimePrincipal
```

Create an opaque runtime identity from application-authorized grants.

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `permissions` | `Sequence[str] \| set[str] \| frozenset[str]` | `()` | Permission names your application authorizes. |
>
> ```python theme={null}
> from harnest.agent import AgentRuntimePrincipal
>
> principal = AgentRuntimePrincipal.create(permissions={"tickets.read"})
> ```

### AgentRuntimePrincipal.restrict

```python theme={null}
AgentRuntimePrincipal.restrict(permissions: Sequence[str] | set[str] | frozenset[str]) -> AgentRuntimePrincipal
```

Create a fresh principal without permitting authority amplification.

> [accordion] 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`. |
>
> ```python theme={null}
> from harnest.agent import AgentRuntimePrincipal
>
> principal: AgentRuntimePrincipal
> read_only = principal.restrict({"tickets.read"})
> ```

## ClientToolError

A client tool request could not be completed safely.

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

## ClientToolExecution

Runtime capability visible only while Harnest owns an invocation.

```python theme={null}
ClientToolExecution(store: InMemoryClientToolStore, run: ApprovalRun) -> None
```

Fields (`—` means no declared default):

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

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `store` | `InMemoryClientToolStore` | Required |
> | `run` | `ApprovalRun` | Required |
>
> ```python theme={null}
> from harnest.agent import ClientToolExecution
>
> execution = ClientToolExecution(store=..., run=...)
> ```

### ClientToolExecution.execute

```python theme={null}
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.

> [accordion] 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` |
>
> ```python theme={null}
> 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.

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent import ClientToolExecution
>
> execution: ClientToolExecution
> value = execution.transient_media
> ```

## InMemoryClientToolStore

Development store for one-time client tool result delivery.

```python theme={null}
InMemoryClientToolStore(
    *,
    clock: Callable[[], float] = time,
    transient_media: TransientMediaLeaseStore | None = None,
    asset_stores: Mapping[str, AssetStorage] | None = None,
) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `clock` | `Callable[[], float]` | `time` |
> | `transient_media` | `TransientMediaLeaseStore \| None` | `None` |
> | `asset_stores` | `Mapping[str, AssetStorage] \| None` | `None` |
>
> ```python theme={null}
> from harnest.agent import InMemoryClientToolStore
>
> store = InMemoryClientToolStore()
> ```

### InMemoryClientToolStore.transient\_media

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

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent import InMemoryClientToolStore
>
> store: InMemoryClientToolStore
> value = store.transient_media
> ```

### InMemoryClientToolStore.suspend

```python theme={null}
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.

> [accordion] 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` |
>
> ```python theme={null}
> from harnest.agent import InMemoryClientToolStore
>
> store: InMemoryClientToolStore
> result = await store.suspend(
>     run=...,
>     name=...,
>     arguments=...,
>     output_schema=...,
>     timeout_seconds=...,
> )
> ```

### InMemoryClientToolStore.submit

```python theme={null}
async InMemoryClientToolStore.submit(request_id: str, *, user_id: str, output: Any) -> PendingClientTool
```

Validate and sanitize a client result before its framework resumes.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `request_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `output` | `Any` | Required |
>
> ```python theme={null}
> from harnest.agent import InMemoryClientToolStore
>
> store: InMemoryClientToolStore
> tool = await store.submit(request_id=..., user_id=..., output=...)
> ```

### InMemoryClientToolStore.run\_for

```python theme={null}
InMemoryClientToolStore.run_for(pending: PendingClientTool) -> ApprovalRun
```

Return the live invocation waiting for a client tool result.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `pending` | `PendingClientTool` | Required |
>
> ```python theme={null}
> from harnest.agent import InMemoryClientToolStore
>
> store: InMemoryClientToolStore
> result = store.run_for(pending=...)
> ```

### InMemoryClientToolStore.pending\_for

```python theme={null}
InMemoryClientToolStore.pending_for(*, user_id: str, session_id: str) -> list[PendingClientTool]
```

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

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.agent import InMemoryClientToolStore
>
> store: InMemoryClientToolStore
> result = store.pending_for(user_id=..., session_id=...)
> ```

### InMemoryClientToolStore.cancel

```python theme={null}
InMemoryClientToolStore.cancel(request_id: str, *, user_id: str) -> PendingClientTool
```

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

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `request_id` | `str` | Required |
> | `user_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.agent import InMemoryClientToolStore
>
> store: InMemoryClientToolStore
> tool = store.cancel(request_id=..., user_id=...)
> ```

## PendingClientTool

One principal-scoped client tool call awaiting its result.

```python theme={null}
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` |

> [accordion] 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` |
>
> ```python theme={null}
> from harnest.agent import PendingClientTool
>
> tool = PendingClientTool(
>     id=...,
>     user_id=...,
>     session_id=...,
>     call_id=...,
>     name=...,
>     arguments=...,
>     output_schema=...,
>     expires_at=...,
>     run=...,
>     future=...,
> )
> ```

### PendingClientTool.public

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

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

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent import PendingClientTool
>
> tool: PendingClientTool
> result = tool.public()
> ```

## ToolCallRequest

Provider-neutral arguments for one managed tool call.

```python theme={null}
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()` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
> | `args` | `tuple[Any, ...]` | `()` |
> | `kwargs` | `Mapping[str, Any]` | `...` |
>
> ```python theme={null}
> from harnest.agent import ToolCallRequest
>
> request = ToolCallRequest(name=...)
> ```

## ToolLifecycleContext

Stable invocation identity associated with one managed tool call.

```python theme={null}
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` | `—` |

> [accordion] 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 |
>
> ```python theme={null}
> from harnest.agent import ToolLifecycleContext
>
> context = ToolLifecycleContext(
>     framework=...,
>     agent_name=...,
>     invocation_id=...,
>     user_id=...,
>     session_id=...,
>     tool_name=...,
> )
> ```

### ToolLifecycleContext.next

```python theme={null}
ToolLifecycleContext.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.agent import ToolLifecycleContext
>
> context: ToolLifecycleContext
> result = context.next()
> ```

### ToolLifecycleContext.finish

```python theme={null}
ToolLifecycleContext.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.agent import ToolLifecycleContext
>
> context: ToolLifecycleContext
> result = context.finish(result=...)
> ```

## ToolLifecycleError

A tool interceptor returned invalid or ambiguous control flow.

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

## approval

See [`harnest.agent.approval`](https://usefused.com/docs/harnest/reference/api/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.

```python theme={null}
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]]]]
```

> [accordion] 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. |
>
> ```python theme={null}
> 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.

```python theme={null}
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]
```

> [accordion] 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. |
>
> ```python theme={null}
> 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.

```python theme={null}
client_tool_execution(execution: ClientToolExecution) -> Iterator[None]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `execution` | `ClientToolExecution` | Required |
>
> ```python theme={null}
> from harnest.agent import client_tool_execution
>
> with client_tool_execution(execution=...):
>     ...
> ```

## current\_transient\_media

Expose scoped staged bytes only during a managed invocation.

```python theme={null}
current_transient_media() -> TransientMediaAccess | None
```

> [accordion] Example
>
> ```python theme={null}
> 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.

```python theme={null}
instruction_file(anchor: str | Path, relative_path: str = 'instructions.md') -> str
```

> [accordion] 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. |
>
> ```python theme={null}
> 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.

```python theme={null}
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]
```

> [accordion] 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. |
>
> ```python theme={null}
> from harnest.agent import tool
>
> @tool
> def lookup_ticket(ticket_id: str) -> str:
>     """Return the current ticket summary."""
>     ...
> ```


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