Skip to content

invoke_harness

Operation

Async only

This operation uses an event stream, so only the asynchronous client supports it.

invoke_harness async

invoke_harness(request: InvokeHarnessInput | InvokeHarnessInputDict | None = None, /, *, plugins: list[Plugin] | None = None, **kwargs: Unpack[InvokeHarnessInputDict]) -> AsyncOutputEventStream[InvokeHarnessStreamOutput, InvokeHarnessOutput]

Operation to invoke a Harness.

Parameters:

Name Type Description Default
request InvokeHarnessInput | InvokeHarnessInputDict | None

The input as a model or dictionary. Pass this or keyword arguments, not both.

None
plugins list[Plugin] | None

A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations.

None
**kwargs Unpack[InvokeHarnessInputDict]

The input fields as keyword arguments.

{}

Returns:

Type Description
AsyncOutputEventStream[InvokeHarnessStreamOutput, InvokeHarnessOutput]

An AsyncOutputEventStream for server-to-client streaming.

Input

Pass the input as keyword arguments, a positional dictionary, or a positional model object. Pass plugins separately as a keyword argument.

InvokeHarnessInputDict

Bases: TypedDict

Dictionary form of InvokeHarnessInput.

Attributes

actor_id instance-attribute
actor_id: str | None

The actor ID for memory operations. Overrides the actor ID configured on the harness.

allowed_tools instance-attribute
allowed_tools: Sequence[str] | None

The tools that the agent is allowed to use for this invocation. If specified, overrides the harness default.

baggage instance-attribute
baggage: str | None

W3C Baggage header for user-defined context propagation. Format: key1=value1,key2=value2

harness_arn instance-attribute
harness_arn: Required[str]

The ARN of the harness to invoke.

max_iterations instance-attribute
max_iterations: int | None

The maximum number of iterations the agent loop can execute. If specified, overrides the harness default.

max_tokens instance-attribute
max_tokens: int | None

The maximum number of tokens the agent can generate per iteration. If specified, overrides the harness default.

messages instance-attribute

The messages to send to the agent.

model instance-attribute

The model configuration to use for this invocation. If specified, overrides the harness default.

qualifier instance-attribute
qualifier: str | None

The endpoint name to invoke. If omitted, the DEFAULT endpoint is used.

runtime_session_id instance-attribute
runtime_session_id: Required[str]

The session ID for the invocation. Use the same session ID across requests to continue a conversation.

runtime_user_id instance-attribute
runtime_user_id: str | None

An identifier for the end user making the request. This value is passed through to the runtime container.

skills instance-attribute

The skills available to the agent for this invocation. If specified, overrides the harness default.

system_prompt instance-attribute

The system prompt to use for this invocation. If specified, overrides the harness default.

timeout_seconds instance-attribute
timeout_seconds: int | None

The maximum duration in seconds for the agent loop execution. If specified, overrides the harness default.

tools instance-attribute

The tools available to the agent for this invocation. If specified, overrides the harness default.

trace_id instance-attribute
trace_id: str | None

Trace ID for maintaining observability through the operation.

trace_parent instance-attribute
trace_parent: str | None

W3C trace context parent header containing version, trace ID, parent span ID, and trace flags.

trace_state instance-attribute
trace_state: str | None

W3C trace context state header for vendor-specific trace information.

InvokeHarnessInput dataclass

Bases: _SerdeShape

Dataclass for InvokeHarnessInput structure.

Attributes

actor_id class-attribute instance-attribute
actor_id: str | None = ...

The actor ID for memory operations. Overrides the actor ID configured on the harness.

allowed_tools class-attribute instance-attribute
allowed_tools: list[str] | None = ...

The tools that the agent is allowed to use for this invocation. If specified, overrides the harness default.

baggage class-attribute instance-attribute
baggage: str | None = ...

W3C Baggage header for user-defined context propagation. Format: key1=value1,key2=value2

harness_arn class-attribute instance-attribute
harness_arn: str | None = ...

The ARN of the harness to invoke.

max_iterations class-attribute instance-attribute
max_iterations: int | None = ...

The maximum number of iterations the agent loop can execute. If specified, overrides the harness default.

max_tokens class-attribute instance-attribute
max_tokens: int | None = ...

The maximum number of tokens the agent can generate per iteration. If specified, overrides the harness default.

messages class-attribute instance-attribute
messages: list[HarnessMessage] | None = ...

The messages to send to the agent.

model class-attribute instance-attribute
model: HarnessModelConfiguration | None = ...

The model configuration to use for this invocation. If specified, overrides the harness default.

qualifier class-attribute instance-attribute
qualifier: str | None = ...

The endpoint name to invoke. If omitted, the DEFAULT endpoint is used.

runtime_session_id class-attribute instance-attribute
runtime_session_id: str | None = ...

The session ID for the invocation. Use the same session ID across requests to continue a conversation.

runtime_user_id class-attribute instance-attribute
runtime_user_id: str | None = ...

An identifier for the end user making the request. This value is passed through to the runtime container.

skills class-attribute instance-attribute
skills: list[HarnessSkill] | None = ...

The skills available to the agent for this invocation. If specified, overrides the harness default.

system_prompt class-attribute instance-attribute
system_prompt: list[HarnessSystemContentBlock] | None = ...

The system prompt to use for this invocation. If specified, overrides the harness default.

timeout_seconds class-attribute instance-attribute
timeout_seconds: int | None = ...

The maximum duration in seconds for the agent loop execution. If specified, overrides the harness default.

tools class-attribute instance-attribute
tools: list[HarnessTool] | None = ...

The tools available to the agent for this invocation. If specified, overrides the harness default.

trace_id class-attribute instance-attribute
trace_id: str | None = ...

Trace ID for maintaining observability through the operation.

trace_parent class-attribute instance-attribute
trace_parent: str | None = ...

W3C trace context parent header containing version, trace ID, parent span ID, and trace flags.

trace_state class-attribute instance-attribute
trace_state: str | None = ...

W3C trace context state header for vendor-specific trace information.

Output

This operation returns an AsyncOutputEventStream for server-to-client streaming.

Event Stream Structure

Output Event Type

InvokeHarnessStreamOutput

Initial Response Structure

InvokeHarnessOutput dataclass

Bases: _SerdeShape

Dataclass for InvokeHarnessOutput structure.

Attributes
response_metadata class-attribute instance-attribute
response_metadata: ResponseMetadata = ...

Metadata about the response that produced this output. Use this to recover the request identifiers a service's support team needs in order to investigate a call. Members of the metadata are individually optional.