CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
---
id: cubepi-agent
title: cubepi.agent
sidebar_position: 1
hide_table_of_contents: false
---
# `cubepi.agent`
### Agent {#agent}
_class_
```python
Agent(
*,
model: BoundModel | FallbackBoundModel,
system_prompt: str = '',
tools: list[AgentTool] | None = None,
reasoning: ReasoningControl | None = None,
convert_to_llm: Callable[..., list[Message]] | None = None,
transform_context: Callable | None = None,
transform_system_prompt: Callable | None = None,
after_model_response: Callable | None = None,
before_tool_call: Callable | None = None,
resolve_tool_call: Callable | None = None,
after_tool_call: Callable | None = None,
should_stop_after_turn: Callable | None = None,
on_run_end: Callable | None = None,
on_payload: OnPayloadCallback | None = None,
on_response: OnResponseCallback | None = None,
steering_mode: str = 'one-at-a-time',
follow_up_mode: str = 'one-at-a-time',
tool_execution: str = 'parallel',
checkpointer: Checkpointer | None = None,
thread_id: str | None = None,
middleware: list[Middleware] | None = None,
deferred_tool_groups: list[DeferredToolGroup] | None = None,
deferred_tool_strategy: DeferredStrategy = 'dispatch',
channel: HitlChannel | None = None,
messages: Sequence[Message] | None = None,
)
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L168)
**Attributes**
- `convert_to_llm`
- `transform_context`
- `transform_system_prompt`
- `after_model_response`
- `before_tool_call`
- `resolve_tool_call`: `Callable | None`
- `after_tool_call`
- `should_stop_after_turn`
- `on_run_end`
- `on_payload`
- `on_response`
- `tool_execution`
- `checkpointer`
- `thread_id`
- `state`: `AgentState`
- `channel`: `HitlChannel | None`
- `in_flight_hitl_request`: `HitlRequest | None`
**Methods**
#### `subscribe` {#agent-subscribe}
```python
subscribe(listener: Callable) -> Callable[[], None]
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L321)
#### `steer` {#agent-steer}
```python
steer(message: Message) -> None
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L327)
#### `cancel_steer` {#agent-cancel-steer}
```python
cancel_steer(steer_id: str) -> bool
```
Remove a not-yet-drained steering message by its steer_id.
Returns True if a queued message was removed; False if it was already
drained or never queued (best-effort cancel).
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L330)
#### `follow_up` {#agent-follow-up}
```python
follow_up(message: Message) -> None
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L338)
#### `abort` {#agent-abort}
```python
abort() -> None
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L341)
#### `wait_for_idle` {#agent-wait-for-idle}
```python
wait_for_idle() -> None
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L345)
#### `reset` {#agent-reset}
```python
reset() -> None
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L349)
#### `prompt` {#agent-prompt}
```python
prompt(message: str | Message | list[Message], *, run_id: str | None = None) -> str
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L455)
#### `fork` {#agent-fork}
```python
fork(
src_thread_id: str,
new_thread_id: str,
*,
after_run_id: str,
metadata: JsonObject | None = None,
) -> None
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L531)
#### `fork_once` {#agent-fork-once}
```python
fork_once(
src_thread_id: str,
message: str | Message | list[Message],
*,
after_run_id: str,
) -> ForkOnceResult
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L554)
#### `resume` {#agent-resume}
```python
resume(*, run_id: str | None = None) -> str
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L673)
#### `detach` {#agent-detach}
```python
detach() -> None
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L805)
#### `load_pending_hitl_request` {#agent-load-pending-hitl-request}
```python
load_pending_hitl_request() -> HitlRequest | None
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L823)
#### `respond` {#agent-respond}
```python
respond(*, question_id: str | None = None, answer: StructuredValue) -> None
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L831)
#### `abort_pending` {#agent-abort-pending}
```python
abort_pending(reason: str = 'aborted by host') -> None
```
Abort a pending HITL request and CLOSE the conversation.
Per spec §5.2 "abort closes the conversation" — no new model call.
Two-phase: Phase 1 (no lock) interrupts any in-flight HITL await via
the agent signal; Phase 2 (with lock) appends synthetic deny
tool_results + a terminal stop_reason="aborted" assistant message
and emits AgentAbortedEvent.
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L910)
### AgentState {#agentstate}
_class_
```python
AgentState(
system_prompt: str = '',
model: Model = (lambda: Model(id='unknown', provider_id='unknown'))(),
reasoning: ReasoningControl = ReasoningControl(),
is_streaming: bool = False,
streaming_message: Message | None = None,
error_message: str | None = None,
active_run_id: str | None = None,
last_outcome: RunOutcome | None = None,
extra: JsonObject = dict(),
_tools: list[AgentTool] = list(),
_messages: list[Message] = list(),
_pending_tool_calls: set[str] = set(),
)
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L126)
**Attributes**
- `system_prompt`: `str`
- `model`: `Model`
- `reasoning`: `ReasoningControl`
- `is_streaming`: `bool`
- `streaming_message`: `Message | None`
- `error_message`: `str | None`
- `active_run_id`: `str | None`
- `last_outcome`: `RunOutcome | None`
- `extra`: `JsonObject`
- `tools`: `list[AgentTool]`
- `messages`: `list[Message]`
- `pending_tool_calls`: `set[str]`
### run_agent_loop {#run-agent-loop}
_function_
```python
run_agent_loop(
*,
prompts: list[Message],
context: AgentContext,
model: BoundModel | FallbackBoundModel,
convert_to_llm: Callable,
emit: Callable,
transform_context: Callable | None = None,
transform_system_prompt: Callable | None = None,
after_model_response: Callable | None = None,
before_tool_call: Callable | None = None,
resolve_tool_call: Callable | None = None,
after_tool_call: Callable | None = None,
should_stop_after_turn: Callable | None = None,
get_steering_messages: Callable | None = None,
get_follow_up_messages: Callable | None = None,
on_run_end: Callable | None = None,
stream_options: StreamOptions | None = None,
tool_execution: str = 'parallel',
system_prompt: str | None = None,
set_outcome: Callable[[str], None] | None = None,
) -> list[Message]
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/loop.py#L36)
### run_agent_loop_continue {#run-agent-loop-continue}
_function_
```python
run_agent_loop_continue(
*,
context: AgentContext,
model: BoundModel | FallbackBoundModel,
convert_to_llm: Callable,
emit: Callable,
transform_context: Callable | None = None,
transform_system_prompt: Callable | None = None,
after_model_response: Callable | None = None,
before_tool_call: Callable | None = None,
resolve_tool_call: Callable | None = None,
after_tool_call: Callable | None = None,
should_stop_after_turn: Callable | None = None,
get_steering_messages: Callable | None = None,
get_follow_up_messages: Callable | None = None,
on_run_end: Callable | None = None,
stream_options: StreamOptions | None = None,
tool_execution: str = 'parallel',
system_prompt: str | None = None,
set_outcome: Callable[[str], None] | None = None,
) -> list[Message]
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/loop.py#L97)
### tool {#tool}
_function_
```python
tool(
fn: ToolFunc | None = None,
*,
name: str | None = None,
description: str | None = None,
execution_mode: Literal['sequential', 'parallel'] | None = None,
) -> AgentTool[Any] | Callable[[ToolFunc], AgentTool[Any]]
```
Turn an async function into an [`AgentTool`](./cubepi-agent#agenttool).
Usable bare (`@tool`) or with arguments (`@tool(name=..., ...)`).
- The tool's input schema is generated from the function's parameters; each
needs a type annotation. `Field(...)` defaults/metadata are honoured.
- If the function declares `tool_call_id`, `signal`, or `on_update`,
the loop's values are passed through; otherwise they are omitted from the
schema and not passed.
- The return value may be an `AgentToolResult`, a `str`, a `Content`,
or a `list[Content]`.
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/tool_decorator.py#L180)
### execute_tool_calls {#execute-tool-calls}
_function_
```python
execute_tool_calls(
context: AgentContext,
assistant_message: AssistantMessage,
*,
tool_execution: str = 'parallel',
before_tool_call: Callable | None = None,
resolve_tool_call: Callable | None = None,
after_tool_call: Callable | None = None,
signal: asyncio.Event | None = None,
emit: Callable,
) -> ToolCallBatch
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/tools.py#L384)
### AfterToolCallContext {#aftertoolcallcontext}
_class_
```python
AfterToolCallContext(
assistant_message: AssistantMessage,
tool_call: ToolCall,
args: BaseModel | JsonObject,
result: AgentToolResult,
is_error: bool,
context: AgentContext,
)
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L90)
**Attributes**
- `assistant_message`: `AssistantMessage`
- `tool_call`: `ToolCall`
- `args`: `BaseModel | JsonObject`
- `result`: `AgentToolResult`
- `is_error`: `bool`
- `context`: `AgentContext`
### AfterToolCallResult {#aftertoolcallresult}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L75)
**Attributes**
- `content`: `list[Content] | None`
- `details`: `StructuredValue`
- `is_error`: `bool | None`
- `terminate`: `bool | None`
### AgentContext {#agentcontext}
_class_
```python
AgentContext(
system_prompt: str,
messages: list[Message],
tools: list[AgentTool] | None = None,
extra: JsonObject = dict(),
)
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L56)
**Attributes**
- `system_prompt`: `str`
- `messages`: `list[Message]`
- `tools`: `list[AgentTool] | None`
- `extra`: `JsonObject`
### AgentEndEvent {#agentendevent}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L115)
**Attributes**
- `type`: `Literal['agent_end']`
- `messages`: `list[Message]`
### AgentEvent {#agentevent}
_attribute_
```python
AgentEvent = AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEve...
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L204)
### AgentListener {#agentlistener}
_attribute_
```python
AgentListener = Callable[[AgentEvent, asyncio.Event | None], Awaitable[None] | None]
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L223)
### AgentStartEvent {#agentstartevent}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L111)
**Attributes**
- `type`: `Literal['agent_start']`
### AgentTool {#agenttool}
_class_
```python
AgentTool(
name: str,
description: str,
parameters: type[TParams],
execute: Callable[..., Awaitable[AgentToolResult]],
label: str = '',
execution_mode: Literal['sequential', 'parallel'] | None = None,
hitl_builtin: bool = False,
hitl: HitlBinding | None = None,
expose_to_model: bool = True,
)
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L33)
**Attributes**
- `name`: `str`
- `description`: `str`
- `parameters`: `type[TParams]`
- `execute`: `Callable[..., Awaitable[AgentToolResult]]`
- `label`: `str`
- `execution_mode`: `Literal['sequential', 'parallel'] | None`
- `hitl_builtin`: `bool`
- `hitl`: `HitlBinding | None`
- `expose_to_model`: `bool`
**Methods**
#### `to_definition` {#agenttool-to-definition}
```python
to_definition() -> ToolDefinition
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L47)
### AgentToolResult {#agenttoolresult}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L26)
**Attributes**
- `content`: `list[Content]`
- `details`: `StructuredValue`
- `is_error`: `bool | None`
- `terminate`: `bool | None`
### BeforeToolCallContext {#beforetoolcallcontext}
_class_
```python
BeforeToolCallContext(
assistant_message: AssistantMessage,
tool_call: ToolCall,
args: BaseModel | JsonObject,
context: AgentContext,
)
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L82)
**Attributes**
- `assistant_message`: `AssistantMessage`
- `tool_call`: `ToolCall`
- `args`: `BaseModel | JsonObject`
- `context`: `AgentContext`
### BeforeToolCallResult {#beforetoolcallresult}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L67)
**Attributes**
- `block`: `bool`
- `reason`: `str | None`
- `edited_args`: `JsonObject | None`
- `deny_reason`: `str | None`
- `hitl_trace`: `StructuredObject | None`
### MessageEndEvent {#messageendevent}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L141)
**Attributes**
- `type`: `Literal['message_end']`
- `message`: `Message`
### MessageStartEvent {#messagestartevent}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L130)
**Attributes**
- `type`: `Literal['message_start']`
- `message`: `Message`
### MessageUpdateEvent {#messageupdateevent}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L135)
**Attributes**
- `type`: `Literal['message_update']`
- `message`: `AssistantMessage`
- `stream_event`: `StreamEvent`
### ShouldStopAfterTurnContext {#shouldstopafterturncontext}
_class_
```python
ShouldStopAfterTurnContext(
message: AssistantMessage,
tool_results: list[ToolResultMessage],
context: AgentContext,
new_messages: list[Message],
)
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L100)
**Attributes**
- `message`: `AssistantMessage`
- `tool_results`: `list[ToolResultMessage]`
- `context`: `AgentContext`
- `new_messages`: `list[Message]`
### ToolExecutionEndEvent {#toolexecutionendevent}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L161)
**Attributes**
- `type`: `Literal['tool_execution_end']`
- `tool_call_id`: `str`
- `tool_name`: `str`
- `result`: `StructuredValue`
- `is_error`: `bool`
- `terminate`: `bool` — True iff the tool's AgentToolResult.terminate was True (or the after_tool_call hook set terminate=True). Recorders use this to mark the turn as terminated-by-tool without unwrapping `result`.
- `blocked_by_hook`: `bool` — True iff the tool call was blocked by a `before_tool_call` hook returning `block=True`. Distinguishes hook-blocks from other immediate errors (tool-not-found, arg-validation failure).
- `block_reason`: `str | None` — When `blocked_by_hook` is True, the reason string from `BeforeToolCallResult.reason` (or `None` if the hook supplied no reason).
### ToolExecutionStartEvent {#toolexecutionstartevent}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L146)
**Attributes**
- `type`: `Literal['tool_execution_start']`
- `tool_call_id`: `str`
- `tool_name`: `str`
- `args`: `JsonObject`
### ToolExecutionUpdateEvent {#toolexecutionupdateevent}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L153)
**Attributes**
- `type`: `Literal['tool_execution_update']`
- `tool_call_id`: `str`
- `tool_name`: `str`
- `args`: `JsonObject | None`
- `partial_result`: `StructuredValue`
### TurnEndEvent {#turnendevent}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L124)
**Attributes**
- `type`: `Literal['turn_end']`
- `message`: `AssistantMessage`
- `tool_results`: `list[ToolResultMessage]`
### TurnStartEvent {#turnstartevent}
_class_
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L120)
**Attributes**
- `type`: `Literal['turn_start']`
### emit_event {#emit-event}
_function_
```python
emit_event(emit_fn: Callable, event: object) -> None
```
[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/utils/emit.py#L7)
<!-- GENERATED by build_api_reference.py — DO NOT EDIT -->