Human

Protocol and Response Types

base

Human interface protocol and response types.

Defines the protocol for human-in-the-loop agent backends (CLI, Slack, GitHub, etc.). Human-issued tool calls are validated through the same tool pipeline as LLM-issued ones.

HumanResponse(content='', tool_calls=list()) dataclass

Response from a human agent.

Attributes:

Name	Type	Description
content	str	Free-text response from the human.
tool_calls	list[ToolCall]	Actions the human chose to take.

HumanInterface

Bases: Protocol

Protocol for human agent backends.

Implementations present the event and context to a human and collect their response. The available tools are provided so the interface can display valid actions.

prompt(event, context, available_tools=None) async

Present an event to a human and collect their response.

Parameters:

Name	Type	Description	Default
event	Event	The event the human needs to respond to.	required
context	str	Formatted context string (artifacts, history, etc.).	required
available_tools	list[dict[str, Any]] | None	Tool definitions the human can invoke.	None

Returns:

Type	Description
HumanResponse	Human's response with optional tool calls.

MockHuman

mock

MockHuman — deterministic human interface for testing.

Supports auto-respond policies: approve_all, reject_all, scripted, and random_delay for simulating human response time.

MockHuman(policy='approve_all', scripts=dict(), delay_range=(0.0, 0.0), calls=list()) dataclass

Deterministic human interface for testing.

Policies: - approve_all: Always emit an "approve" tool call. - reject_all: Always emit a "reject" tool call. - scripted: Map event types to pre-configured responses. - random_delay: Like approve_all but with a simulated delay.

Attributes:

Name	Type	Description
policy	str	One of "approve_all", "reject_all", "scripted", "random_delay".
scripts	dict[str, HumanResponse]	Map of event type → HumanResponse (for scripted policy).
delay_range	tuple[float, float]	(min, max) seconds for random_delay policy.
calls	list[dict[str, Any]]	Record of all prompt calls for test assertions.

call_count property

Total number of prompt calls.

prompt(event, context, available_tools=None) async

Return a pre-configured response based on policy.

Parameters:

Name	Type	Description	Default
event	Event	The event the human needs to respond to.	required
context	str	Formatted context string.	required
available_tools	list[dict[str, Any]] | None	Tool definitions (unused by mock).	None

Returns:

Type	Description
HumanResponse	HumanResponse based on the configured policy.

reset()

Clear call history.

CLIHuman

cli

CLIHuman — async stdin/stdout human interface.

Presents events and context to a human operator via the terminal and collects free-text responses with optional action selection.

CLIHuman(input_stream=None, output_stream=None)

Terminal-based human interface.

Displays event info, context, and available actions, then reads the human's response from stdin without blocking the event loop.

Parameters:

Name	Type	Description	Default
input_stream	Any	Readable stream (defaults to sys.stdin).	None
output_stream	Any	Writable stream (defaults to sys.stdout).	None

prompt(event, context, available_tools=None) async

Display event info and collect human response.

Parameters:

Name	Type	Description	Default
event	Event	The event to respond to.	required
context	str	Formatted context string.	required
available_tools	list[dict[str, Any]] | None	Tool definitions for numbered menu.	None

Returns:

Type	Description
HumanResponse	HumanResponse with the human's text and optional tool call.