turn()

turn(input, options?): Promise<HarnessTurnResult<HarnessParsedOutput<OutputDefinition>>>

Parameters

Parameter	Type
`input`	`string`
`options?`	`HarnessTurnOptions`<`TOOLS`, `OutputDefinition`>

Returns Promise<HarnessTurnResult<HarnessParsedOutput<OutputDefinition>>>

HarnessTurnOptions

Per-turn transport-neutral observation callbacks. Type Parameters

Type Parameter	Default type
`TOOLS` extends `ToolSet`	`ToolSet`
`OutputDefinition` extends `HarnessOutputDefinition` \| `undefined`	`undefined`

Properties callbacks?

optional callbacks?: Readonly<{ onFinish?: GenerateTextOnFinishCallback<TOOLS>; onStart?: GenerateTextOnStartCallback; onStepFinish?: GenerateTextOnStepFinishCallback<TOOLS>; onStepStart?: GenerateTextOnStepStartCallback<TOOLS>; onToolCallFinish?: GenerateTextOnToolCallFinishCallback<TOOLS>; onToolCallStart?: GenerateTextOnToolCallStartCallback<TOOLS>; }>

AI SDK lifecycle callbacks, chained after harness persistence work. onCancel?

optional onCancel?: (error) => void | Promise<void>

Runs once after cleanup when the caller-owned signal cancels a turn. Parameters

Parameter	Type
`error`	`HarnessCancellationError`

Returns void | Promise<void> onError?

optional onError?: (error) => void | Promise<void>

Runs once after cleanup for non-cancellation failures. Parameters

Parameter	Type
`error`	`unknown`

Returns void | Promise<void> onOutput?

optional onOutput?: (output) => void | Promise<void>

Runs once after the complete successful output has been persistently journaled. Parameters

Parameter	Type
`output`	`HarnessTurnResult`<`HarnessParsedOutput`<`OutputDefinition`>>

Returns void | Promise<void> onStepCommitted?

optional onStepCommitted?: (step) => void | Promise<void>

Runs after the completed step has been persistently journaled. Parameters

Parameter	Type
`step`	`HarnessStep`

Returns void | Promise<void> signal?

optional signal?: AbortSignal

Caller-owned cancellation signal passed to AI SDK without transport coupling. steps?

optional steps?: HarnessStepContext

Persistent context supplied only by the harness run ledger.

HarnessTurnResult

Transport-neutral result of a completed turn. Type Parameters

Type Parameter	Default type
`Output`	`unknown`

Properties finishReason

readonly finishReason: FinishReason

journalThrough

readonly journalThrough: number

output?

readonly optional output?: Output

Parsed AI SDK output when a structured output mode is configured. stepCount

readonly stepCount: number

text

readonly text: string

usage

readonly usage: HarnessUsage

HarnessUsage

Transport-safe aggregate token usage for a completed turn. Properties inputTokens

readonly inputTokens: number | undefined

outputTokens

readonly outputTokens: number | undefined

totalTokens

readonly totalTokens: number | undefined

HarnessStep

One completed model step, excluding provider request/response bodies and metadata. Properties finishReason

finishReason: FinishReason

journalThrough

journalThrough: number

number

number: number

text

text: string

toolCalls

toolCalls: readonly Readonly<{ id: string; input: unknown; name: string; }>[]

toolResults

toolResults: readonly Readonly<{ id: string; isError: boolean; name: string; output: unknown; }>[]

HarnessStepLimitError

Raised after the final allowed model step still requests executable tools. Constructors Constructor

new HarnessStepLimitError(maxSteps, completedSteps, lastToolCalls): HarnessStepLimitError

Parameters

Parameter	Type
`maxSteps`	`number`
`completedSteps`	`number`
`lastToolCalls`	readonly `Readonly`<{ `id`: `string`; `name`: `string`; }>[]

Returns HarnessStepLimitError Properties cause?

optional cause?: unknown

code

readonly code: "HARNESS_STEP_LIMIT"

completedSteps

readonly completedSteps: number

lastToolCalls

readonly lastToolCalls: readonly Readonly<{ id: string; name: string; }>[]

maxSteps

readonly maxSteps: number

message

message: string

name

name: string

stack?

optional stack?: string

stackTraceLimit

static stackTraceLimit: number

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. Methods captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}. The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace. The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns void prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns any See https://v8.dev/docs/stack-trace-api#customizing-stack-traces

HarnessProviderError

Stable provider-boundary error containing only allowlisted diagnostics. Constructors Constructor

new HarnessProviderError(diagnostics): HarnessProviderError

Parameters

Parameter	Type
`diagnostics`	`HarnessProviderDiagnostics`

Returns HarnessProviderError Properties cause?

optional cause?: unknown

code

readonly code: "HARNESS_PROVIDER_ERROR"

diagnostics

readonly diagnostics: HarnessProviderDiagnostics

message

message: string

name

name: string

stack?

optional stack?: string

stackTraceLimit

static stackTraceLimit: number

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns void prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns any See https://v8.dev/docs/stack-trace-api#customizing-stack-traces

HarnessProviderDiagnostics

Safe provider failure fields. Raw causes, URLs, headers, and bodies are never retained. Properties causeName

readonly causeName: string

modelId

readonly modelId: string

provider

readonly provider: string

retryable?

readonly optional retryable?: boolean

statusCode?

readonly optional statusCode?: number

HarnessToolOutputError

Local tool failure used when a successful execution returns an unsafe output. Constructors Constructor

new HarnessToolOutputError(toolName): HarnessToolOutputError

Parameters

Parameter	Type
`toolName`	`string`

Returns HarnessToolOutputError Properties cause?

optional cause?: unknown

code

readonly code: "HARNESS_TOOL_OUTPUT_ERROR"

message

message: string

name

name: string

stack?

optional stack?: string

toolName

readonly toolName: string

stackTraceLimit

static stackTraceLimit: number

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns void prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns any See https://v8.dev/docs/stack-trace-api#customizing-stack-traces

HarnessCancellationError

Stable cancellation classification for an aborted caller-owned turn signal. Constructors Constructor

new HarnessCancellationError(): HarnessCancellationError

Returns HarnessCancellationError Properties cause?

optional cause?: unknown

code

readonly code: "HARNESS_CANCELLED"

message

message: string

name

name: string

stack?

optional stack?: string

stackTraceLimit

static stackTraceLimit: number

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns void prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns any See https://v8.dev/docs/stack-trace-api#customizing-stack-traces

HarnessObserverError

Stable aggregate retaining a primary turn failure when its observer also fails. Constructors Constructor

new HarnessObserverError(primary, observer, phase): HarnessObserverError

Parameters

Parameter	Type
`primary`	`unknown`
`observer`	`unknown`
`phase`	`"cancel"` \| `"error"`

Returns HarnessObserverError Properties cause?

optional cause?: unknown

code

readonly code: "HARNESS_OBSERVER_ERROR"

message

message: string

name

name: string

observer

readonly observer: unknown

phase

readonly phase: "cancel" | "error"

primary

readonly primary: unknown

stack?

optional stack?: string

stackTraceLimit

static stackTraceLimit: number

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns void prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns any See https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Get Started

Inside the Managed Harness

The Agent Harness SDK

The Agent Runtime SDK

The Agent Client SDK

For AI Agents

HarnessTurnOptions

HarnessTurnResult

HarnessUsage

HarnessStep

HarnessStepLimitError

HarnessProviderError

HarnessProviderDiagnostics

HarnessToolOutputError

HarnessCancellationError

HarnessObserverError

​HarnessTurnOptions

​HarnessTurnResult

​HarnessUsage

​HarnessStep

​HarnessStepLimitError

​HarnessProviderError

​HarnessProviderDiagnostics

​HarnessToolOutputError

​HarnessCancellationError

​HarnessObserverError

HarnessTurnOptions

HarnessTurnResult

HarnessUsage

HarnessStep

HarnessStepLimitError

HarnessProviderError

HarnessProviderDiagnostics

HarnessToolOutputError

HarnessCancellationError

HarnessObserverError