Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

14.3 KB
Raw Blame
---
id: cubepi-agent
title: cubepi.agent
sidebar_position: 1
hide_table_of_contents: false
---

# `cubepi.agent`

### Agent {#agent}

_class_

```python
Agent(self, *, model: BoundModel, system_prompt: str = '', tools: list[AgentTool] | None = None, thinking: ThinkingLevel = 'off', 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, 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, channel: HitlChannel | None = None)
```


[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L130)


**Attributes**

- `convert_to_llm`
- `transform_context`
- `transform_system_prompt`
- `after_model_response`
- `before_tool_call`
- `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#L223)


#### `steer` {#agent-steer}

```python
steer(message: Message) -> None
```

[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L229)


#### `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#L232)


#### `follow_up` {#agent-follow-up}

```python
follow_up(message: Message) -> None
```

[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L240)


#### `abort` {#agent-abort}

```python
abort() -> None
```

[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L243)


#### `wait_for_idle` {#agent-wait-for-idle}

```python
wait_for_idle() -> None
```

[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L247)


#### `reset` {#agent-reset}

```python
reset() -> None
```

[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L251)


#### `prompt` {#agent-prompt}

```python
prompt(message: str | Message | list[Message]) -> None
```

[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L260)


#### `resume` {#agent-resume}

```python
resume() -> None
```

[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L300)


#### `detach` {#agent-detach}

```python
detach() -> None
```

[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/agent.py#L400)


#### `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#L418)


#### `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#L426)


#### `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#L466)



### AgentState {#agentstate}

_class_

```python
AgentState(self, system_prompt: str = '', model: Model = (lambda: Model(id='unknown', provider_id='unknown'))(), thinking: ThinkingLevel = 'off', is_streaming: bool = False, streaming_message: Message | None = None, error_message: str | None = None, _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#L91)


**Attributes**

- `system_prompt`: `str`
- `model`: `Model`
- `thinking`: `ThinkingLevel`
- `is_streaming`: `bool`
- `streaming_message`: `Message | None`
- `error_message`: `str | None`
- `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, provider: Provider, model: Model, 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, 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) -> list[Message]
```


[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/loop.py#L32)


### run_agent_loop_continue {#run-agent-loop-continue}

_function_

```python
run_agent_loop_continue(*, context: AgentContext, provider: Provider, model: Model, 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, 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) -> list[Message]
```


[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/loop.py#L91)


### 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, 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#L314)


### AfterToolCallContext {#aftertoolcallcontext}

_class_

```python
AfterToolCallContext(self, 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#L85)


**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#L70)


**Attributes**

- `content`: `list[Content] | None`
- `details`: `StructuredValue`
- `is_error`: `bool | None`
- `terminate`: `bool | None`


### AgentContext {#agentcontext}

_class_

```python
AgentContext(self, 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#L51)


**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#L110)


**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#L199)


### 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#L218)


### AgentStartEvent {#agentstartevent}

_class_


[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L106)


**Attributes**

- `type`: `Literal['agent_start']`


### AgentTool {#agenttool}

_class_

```python
AgentTool(self, name: str, description: str, parameters: type[TParams], execute: Callable[..., Awaitable[AgentToolResult]], label: str = '', execution_mode: Literal['sequential', 'parallel'] | None = None, hitl_builtin: bool = False)
```


[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L32)


**Attributes**

- `name`: `str`
- `description`: `str`
- `parameters`: `type[TParams]`
- `execute`: `Callable[..., Awaitable[AgentToolResult]]`
- `label`: `str`
- `execution_mode`: `Literal['sequential', 'parallel'] | None`
- `hitl_builtin`: `bool`


**Methods**

#### `to_definition` {#agenttool-to-definition}

```python
to_definition() -> ToolDefinition
```

[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L42)



### AgentToolResult {#agenttoolresult}

_class_


[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L25)


**Attributes**

- `content`: `list[Content]`
- `details`: `StructuredValue`
- `is_error`: `bool | None`
- `terminate`: `bool | None`


### BeforeToolCallContext {#beforetoolcallcontext}

_class_

```python
BeforeToolCallContext(self, assistant_message: AssistantMessage, tool_call: ToolCall, args: BaseModel | JsonObject, context: AgentContext)
```


[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L77)


**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#L62)


**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#L136)


**Attributes**

- `type`: `Literal['message_end']`
- `message`: `Message`


### MessageStartEvent {#messagestartevent}

_class_


[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L125)


**Attributes**

- `type`: `Literal['message_start']`
- `message`: `Message`


### MessageUpdateEvent {#messageupdateevent}

_class_


[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L130)


**Attributes**

- `type`: `Literal['message_update']`
- `message`: `AssistantMessage`
- `stream_event`: `StreamEvent`


### ShouldStopAfterTurnContext {#shouldstopafterturncontext}

_class_

```python
ShouldStopAfterTurnContext(self, message: AssistantMessage, tool_results: list[ToolResultMessage], context: AgentContext, new_messages: list[Message])
```


[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/agent/types.py#L95)


**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#L156)


**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#L141)


**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#L148)


**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#L119)


**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#L115)


**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 -->