Server tools

Use @tool when the capability should execute inside the agent server. When only part of a tool needs isolated Python execution, call an assigned Sandbox through context.sandboxes["<name>"].execute(code) or async aexecute(code). The model calls your business tool, not the sandbox directly; your tool validates inputs and chooses which result to return. The surrounding tool code still runs in the agent server.

tools/lookup_order.py

from harnest.models.orders import OrderStatus
from harnest.agent import tool


@tool(output_schema=OrderStatus)
def lookup_order(order_id: str):
    """Load one order status."""

    return {"order_id": order_id, "status": "processing"}

Tool properties

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

Arguments and results must be structured. Convert unsupported custom objects to a Pydantic model or mapping at the tool boundary. Expose supported filters, pagination, and ordering as typed parameters or separate typed tools. Do not ask the model to invent undeclared options. Managed ADK and LangGraph reject unknown argument names before native framework coercion and return repair guidance without echoing argument values.

Runtime access

Need	Use
Application resource	`context.resource("name")`
Current user	`context.user_id`
Current session	`context.session_id`
Downstream credential	`await context.credentials.resolve(...)`

Credentials are private invocation capabilities. Do not expose them as model-generated arguments or ordinary context resources. Use permission= when trusted application code must select whether the tool is available for one invocation. An active principal denies an untagged tool. See Agent Runtime Principals.

Wait durably

Use an async durable tool when queued or external work must survive a request ending or a replica stopping:

tools/request_report.py

from harnest.lib.report_tasks import build_report
from harnest.agent import tool


@tool(durable=True)
async def request_report(account_id: str):
    handle = await build_report.defer(account_id=account_id)
    return await handle.result()

durable=True resumes framework execution; it does not restore a Python frame. See Durable execution.

Add approval

Every call
After evaluation

from harnest.agent.approval import require_human_approval


@tool
@require_human_approval(message="Approve deleting {customer_id}?")
def delete_customer(customer_id: str):
    return database.delete_customer(customer_id)

Protect only the sensitive block with request_human_approval(...).

Dynamic human approval

Evaluate risk before deciding whether the operation needs permission.

Overview

Get started

Guides

Server tools

Tool properties

Runtime access

Wait durably

Add approval

Dynamic human approval

​Tool properties

​Runtime access

​Wait durably

​Add approval

Dynamic human approval

Tool properties

Runtime access

Wait durably

Add approval