SDK

API reference

Result shapes, exported symbols, error types, retries, and exit codes.

Exports

The public surface of each package:

from harnext import (
    Harnext,          # the agent client
    Session,          # persisted runs
    Harness,          # pipeline generator
    Runner,           # self-hosted runner
    tool,             # define a custom tool
    skill,            # define a custom skill
    ToolResult,       # rich tool return value
    CancelToken,      # cooperative cancellation
    providers,        # provider/model registry
    __version__,
)
from harnext.errors import HarnextError, RateLimitError  # ...

RunResult

textstroptional

The agent's final assistant message.

outputT | Noneoptional

Validated structured output when an output_schema was supplied; otherwise None.

stepslist[ToolStep]optional

Ordered tool calls with their arguments, status, and output.

files_changedlist[str]optional

Paths created, edited, or deleted during the run, relative to cwd.

usageUsageoptional

input_tokens, output_tokens, total_tokens.

session_idstroptional

The id of the session this run was recorded in.

successbooloptional

True if the agent finished the task without an error.

cancelledbooloptional

True if the run was stopped via a cancel token or signal.

ToolStep

toolstroptional

The tool name, e.g. edit or mcp:github.create_issue.

argsdictoptional

The arguments the model passed to the tool.

status"ok" | "error" | "denied"optional

Outcome of the call.

outputstroptional

What the tool returned to the model (truncated in transcripts).

Errors

All SDK errors subclass HarnextError. Catch the base type to handle anything, or specific types for targeted recovery.

Error	Raised when
`AuthenticationError`	A provider key is missing or rejected.
`ProviderError`	The provider returned an unexpected error.
`RateLimitError`	Rate limited after exhausting retries.
`ToolError`	A tool raised or returned `is_error`.
`PermissionDenied`	A tool call was denied by policy or callback.
`MaxTurnsExceeded`	The loop hit `max_turns` before finishing.
`SessionNotFound`	A session id could not be loaded.
`MCPConnectionError`	An MCP server failed to start or connect.

from harnext.errors import RateLimitError, MaxTurnsExceeded

try:
    result = agent.run("Big refactor")
except RateLimitError as e:
    print("retry after", e.retry_after)
except MaxTurnsExceeded as e:
    print("stopped after", e.turns, "turns")

Retries

Transient failures (HTTP 429 and 5xx) are retried automatically with exponential backoff, up to max_retries (default 3). Tune it per client, or set max_retries=0 to surface errors immediately.

Exit codes

When the SDK is driven from the CLI (harnext -p), runs map to these process exit codes — useful in CI:

Code	Meaning
`0`	Success.
`1`	The task failed or the agent reported an error.
`2`	Invalid usage or configuration.
`7`	A tool call was denied by permission policy.
`8`	`max_turns` reached without completion.
`130`	Cancelled (SIGINT).

That's the whole surface

You've now seen everything the SDK exposes. Head back to the overview or start building from the quickstart.

API reference

Exports#

RunResult#

ToolStep#

Errors#