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
from pydantic import BaseModel
from cubeloop.agent.types import (
AgentContext,
AgentEndEvent,
AgentStartEvent,
AgentTool,
AgentToolResult,
BeforeToolCallResult,
AfterToolCallResult,
MessageEndEvent,
MessageStartEvent,
MessageUpdateEvent,
ToolExecutionEndEvent,
ToolExecutionStartEvent,
ToolExecutionUpdateEvent,
TurnEndEvent,
TurnStartEvent,
)
from cubeloop.providers.base import (
AssistantMessage,
StreamEvent,
TextContent,
ToolResultMessage,
UserMessage,
)
class TestAgentEvents:
def test_agent_start_event(self):
e = AgentStartEvent()
assert e.type == "agent_start"
def test_agent_end_event(self):
msg = UserMessage(content=[TextContent(text="hi")])
e = AgentEndEvent(messages=[msg])
assert e.type == "agent_end"
assert len(e.messages) == 1
def test_turn_start_event(self):
e = TurnStartEvent()
assert e.type == "turn_start"
def test_turn_end_event(self):
msg = AssistantMessage(content=[TextContent(text="hi")])
e = TurnEndEvent(message=msg, tool_results=[])
assert e.type == "turn_end"
def test_message_start_event(self):
msg = UserMessage(content=[TextContent(text="hi")])
e = MessageStartEvent(message=msg)
assert e.type == "message_start"
def test_message_update_event(self):
msg = AssistantMessage(content=[TextContent(text="h")])
se = StreamEvent(type="text_delta", delta="h")
e = MessageUpdateEvent(message=msg, stream_event=se)
assert e.type == "message_update"
def test_message_end_event(self):
msg = AssistantMessage(content=[TextContent(text="hello")])
e = MessageEndEvent(message=msg)
assert e.type == "message_end"
def test_tool_execution_events(self):
start = ToolExecutionStartEvent(
tool_call_id="t1", tool_name="search", args={"q": "test"}
)
assert start.type == "tool_execution_start"
update = ToolExecutionUpdateEvent(
tool_call_id="t1",
tool_name="search",
args={"q": "test"},
partial_result=AgentToolResult(content=[TextContent(text="partial")]),
)
assert update.type == "tool_execution_update"
end = ToolExecutionEndEvent(
tool_call_id="t1",
tool_name="search",
result=AgentToolResult(content=[TextContent(text="done")]),
is_error=False,
)
assert end.type == "tool_execution_end"
class TestAgentTool:
async def test_tool_definition_generation(self):
class SearchParams(BaseModel):
query: str
limit: int = 10
async def execute(tool_call_id, params, *, signal=None, on_update=None):
return AgentToolResult(content=[TextContent(text=f"found: {params.query}")])
tool = AgentTool(
name="search",
description="Search the web",
parameters=SearchParams,
execute=execute,
)
defn = tool.to_definition()
assert defn.name == "search"
assert defn.description == "Search the web"
assert "query" in defn.parameters.get("properties", {})
assert "limit" in defn.parameters.get("properties", {})
async def test_tool_execution(self):
class EchoParams(BaseModel):
text: str
async def execute(tool_call_id, params, *, signal=None, on_update=None):
return AgentToolResult(content=[TextContent(text=params.text)])
tool = AgentTool(
name="echo",
description="Echo text",
parameters=EchoParams,
execute=execute,
)
result = await tool.execute("t1", EchoParams(text="hello"))
assert result.content[0].text == "hello"
class TestAgentContext:
def test_context_creation(self):
ctx = AgentContext(system_prompt="You are helpful.", messages=[], tools=[])
assert ctx.system_prompt == "You are helpful."
assert ctx.messages == []
class TestHookTypes:
def test_before_tool_call_result_defaults(self):
r = BeforeToolCallResult()
assert r.block is False
assert r.reason is None
def test_before_tool_call_result_block(self):
r = BeforeToolCallResult(block=True, reason="Not allowed")
assert r.block is True
assert r.reason == "Not allowed"
def test_after_tool_call_result_partial_override(self):
r = AfterToolCallResult(terminate=True)
assert r.terminate is True
assert r.content is None
assert r.is_error is None
class TestTypedMessages:
def test_agent_context_accepts_message_union(self):
ctx = AgentContext(
system_prompt="test",
messages=[
UserMessage(content=[TextContent(text="hi")]),
AssistantMessage(content=[TextContent(text="hello")]),
],
)
assert len(ctx.messages) == 2
def test_agent_end_event_typed_messages(self):
msg = UserMessage(content=[TextContent(text="hi")])
event = AgentEndEvent(messages=[msg])
assert event.messages[0].role == "user"
def test_turn_end_event_typed_message(self):
msg = AssistantMessage(content=[TextContent(text="done")])
event = TurnEndEvent(message=msg, tool_results=[])
assert event.message.role == "assistant"
def test_message_start_event_typed(self):
msg = UserMessage(content=[TextContent(text="hi")])
event = MessageStartEvent(message=msg)
assert event.message.role == "user"
def test_turn_end_event_typed_tool_results(self):
msg = AssistantMessage(content=[TextContent(text="done")])
tr = ToolResultMessage(
tool_call_id="t1",
tool_name="search",
content=[TextContent(text="result")],
)
event = TurnEndEvent(message=msg, tool_results=[tr])
assert len(event.tool_results) == 1
assert event.tool_results[0].role == "tool_result"
class TestStructuredValueSerialization:
"""Regression: fields typed ``StructuredValue`` must dump the runtime
subclass, not the declared ``BaseModel`` base. Without
``SerializeAsAny`` on the union branch, pydantic silently emits ``{}``
for any concrete BaseModel held in such a field — which previously lost
``ToolResultMessage.details`` on checkpointer save and compaction
message-ref hashing.
"""
def _inner(self) -> AgentToolResult:
return AgentToolResult(
content=[TextContent(text="inner")],
details={"kind": "quote_result", "chip_metrics": {"price": 9}},
)
def test_tool_execution_end_event_preserves_basemodel_result(self):
ev = ToolExecutionEndEvent(
tool_call_id="t1", tool_name="quote", result=self._inner()
)
dumped = ev.model_dump()
assert dumped["result"] != {}
assert dumped["result"]["content"] == [{"type": "text", "text": "inner"}]
assert dumped["result"]["details"] == {
"kind": "quote_result",
"chip_metrics": {"price": 9},
}
# json mode must agree with python mode
assert ev.model_dump(mode="json")["result"] == dumped["result"]
def test_tool_result_message_preserves_basemodel_details(self):
msg = ToolResultMessage(
tool_call_id="t1",
tool_name="quote",
content=[TextContent(text="hi")],
details=self._inner(),
)
# Checkpointer path: plain model_dump()
dumped = msg.model_dump()
assert dumped["details"] != {}
assert dumped["details"]["details"] == {
"kind": "quote_result",
"chip_metrics": {"price": 9},
}
# Compaction path: mode="json", exclude_none=True
compact = msg.model_dump(mode="json", exclude_none=True)
assert compact["details"]["content"] == [{"type": "text", "text": "inner"}]
assert compact["content"] == [{"type": "text", "text": "hi"}]
def test_after_tool_call_result_preserves_basemodel_details(self):
r = AfterToolCallResult(details=self._inner())
dumped = r.model_dump()
assert dumped["details"] != {}
assert dumped["details"]["content"] == [{"type": "text", "text": "inner"}]
def test_basemodel_nested_in_list_and_dict_is_polymorphic(self):
# list branch
ev1 = ToolExecutionEndEvent(
tool_call_id="t1", tool_name="x", result=[self._inner()]
)
assert ev1.model_dump()["result"][0]["details"] == {
"kind": "quote_result",
"chip_metrics": {"price": 9},
}
# dict branch
ev2 = ToolExecutionEndEvent(
tool_call_id="t1", tool_name="x", result={"wrap": self._inner()}
)
assert ev2.model_dump()["result"]["wrap"]["content"] == [
{"type": "text", "text": "inner"}
]
def test_plain_dict_value_still_roundtrips(self):
# Non-BaseModel payloads must still validate and dump cleanly.
msg = ToolResultMessage(
tool_call_id="t1",
tool_name="x",
content=[TextContent(text="hi")],
details={"k": [1, 2, {"nested": True}]},
)
dumped = msg.model_dump()
restored = ToolResultMessage.model_validate(dumped)
assert restored.details == {"k": [1, 2, {"nested": True}]}