Server tools

Use @tool when the capability should execute inside the agent server. For isolated Python execution, call an assigned Sandbox through context.sandboxes["<name>"].execute(code) or async aexecute(code). Your tool validates inputs and selects the result to return; its surrounding code runs on the agent server.

tools/lookup_order.py

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

@tool(
    output_schema=OrderStatus,
    description="""Look up an existing order when the user asks for its status.
    Ask for the order ID if missing; never guess it.

    Args:
        order_id: The exact order ID supplied by the user.
    """,
)
def lookup_order(order_id: str):
    return {"order_id": order_id, "status": "processing"}

description tells the model what the tool does and when to call it. It replaces the function docstring; omit it to use the docstring instead. Include argument descriptions in whichever you use. This works with ADK and LangGraph.

Tool properties

Export a typed function from tools/<name>.py, with a clear description and validated return type. See tool declaration options for schema and permission settings. You can call the decorated function directly in unit tests. Arguments and results must be structured. Convert unsupported custom objects to a Pydantic model or mapping at the tool boundary. Declare filters, pagination, and ordering as typed parameters or separate tools. Both frameworks reject unknown arguments and return repair guidance without echoing their 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

Harnest Studio

Guides

API reference

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