Skip to content

Build and run agents you can see, understand and trust.

feat(agent): implement permission checking logic within the agent class (#1518)

DavdGao0f4243b8349f
diff --git a/src/agentscope/_utils/_common.py b/src/agentscope/_utils/_common.py
index 118e23213..37d326308 100644
--- a/src/agentscope/_utils/_common.py
+++ b/src/agentscope/_utils/_common.py
@@ -15,10 +15,12 @@ import requests
from json_repair import repair_json
from .._logging import logger
+from ..exception import ToolJSONDecodeError
def _json_loads_with_repair(
json_str: str,
+ schema: dict | None = None,
) -> dict:
"""The given json_str maybe incomplete, e.g. '{"key', so we need to
repair and load it into a Python object.
@@ -31,6 +33,8 @@ def _json_loads_with_repair(
Args:
json_str (`str`):
The JSON string to parse, which may be incomplete or malformed.
+ schema (`dict`, optional):
+ An optional JSON schema to guide the repair process.
Returns:
`dict`:
@@ -38,24 +42,59 @@ def _json_loads_with_repair(
Returns an empty dict if all repair attempts fail.
"""
try:
- repaired = repair_json(json_str, stream_stable=True)
- result = json.loads(repaired)
- if isinstance(result, dict):
- return result
+ # Loads directly
+ res = json.loads(json_str)
+ if isinstance(res, dict):
+ return res
+
+ error_message = (
+ f"Error: Your argument string is decoded into a {type(res)} "
+ f"object, but a dict object is expected!"
+ )
+ except json.JSONDecodeError as e:
+ error_message = (
+ f"Error: When decoding your tool arguments from JSON format "
+ f"to a Python dictionary, a JSONDecodeError was raised with "
+ f"message: {str(e)}."
+ )
+
+ try:
+ # Try to repair with json_repair
+ repaired = repair_json(json_str, stream_stable=True, schema=schema)
+ res = json.loads(repaired)
+ if isinstance(res, dict):
+ return res
except Exception:
- if len(json_str) > 100:
- log_str = json_str[:100] + "..."
- else:
- log_str = json_str
-
- logger.warning(
- "Failed to load JSON dict from string: %s. Returning empty dict "
- "instead.",
- log_str,
+ # Whatever the error is, we throw the original error message to the
+ # agent, which is more helpful for debugging.
+ pass
+
+ # If still failed, we throw the original error message to the agent, rather
+ # than the error from json_repair, which is less helpful for debugging.
+ if len(json_str) > 200:
+ error_json_str = json_str[:100] + "[TRUNCATE]" + json_str[-100:]
+ ellipsis_hint = (
+ "(Because the JSON string is too long, a truncated label "
+ '"[TRUNCATE]" is used here to indicate the truncation)'
)
+ else:
+ error_json_str = json_str
+ ellipsis_hint = ""
+
+ raise ToolJSONDecodeError(
+ f"""<system-reminder>{error_message}
- return {}
+Your argument string is decoded by the following code snippet{ellipsis_hint}:
+```python
+import json
+
+your_tool_arguments = {repr(error_json_str)}
+json.loads(your_tool_arguments)
+```
+
+**You should recorrect the arguments in JSON format.**</system-reminder>""",
+ )
def _get_timestamp(add_random_suffix: bool = False) -> str:
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.py
index c7356feb0..d87862059 100644
--- a/src/agentscope/agent/_agent.py
+++ b/src/agentscope/agent/_agent.py
@@ -1,15 +1,32 @@
# -*- coding: utf-8 -*-
"""The unified agent class in AgentScope library."""
+import asyncio
import uuid
-from typing import AsyncGenerator, Literal
+from asyncio import Queue
+from copy import deepcopy
+from typing import Any, AsyncGenerator, Sequence, Literal, List
+import jsonschema
+from pydantic import (
+ BaseModel,
+ Field,
+ field_validator,
+ ValidationInfo,
+ SerializeAsAny,
+ PrivateAttr,
+ ConfigDict,
+)
+
+from ._state import AgentState
+from ._utils import _ToolCallBatch
+from .._logging import logger
+from .._utils._common import _json_loads_with_repair
from ..event import (
AgentEvent,
- EventType,
- ModelCallEndedEvent,
- ModelCallStartedEvent,
- RunFinishedEvent,
- RunStartedEvent,
+ ModelCallEndEvent,
+ ModelCallStartEvent,
+ ReplyEndEvent,
+ ReplyStartEvent,
TextBlockDeltaEvent,
TextBlockEndEvent,
TextBlockStartEvent,
@@ -19,7 +36,7 @@ from ..event import (
ToolCallDeltaEvent,
ToolCallEndEvent,
ToolCallStartEvent,
- ToolResultBinaryDeltaEvent,
+ ToolResultDataDeltaEvent,
ToolResultEndEvent,
ToolResultStartEvent,
ToolResultTextDeltaEvent,
@@ -27,10 +44,23 @@ from ..event import (
RequireExternalExecutionEvent,
ExternalExecutionResultEvent,
UserConfirmResultEvent,
+ DataBlockStartEvent,
+ DataBlockDeltaEvent,
+ DataBlockEndEvent,
+ ExceedMaxItersEvent,
+)
+from ..exception import AgentOrientedException
+from ..model import (
+ ChatResponse,
+ ChatUsage,
+ ChatModelBase,
+ _deserialize_model,
)
-from ..model import ChatResponse, ChatUsage, ChatModelBase
from ..message import (
Msg,
+ AssistantMsg,
+ SystemMsg,
+ UserMsg,
TextBlock,
ThinkingBlock,
ToolCallBlock,
@@ -38,364 +68,516 @@ from ..message import (
DataBlock,
Base64Source,
URLSource,
+ ToolCallState,
+ ToolResultState,
+)
+from ..tool import (
+ Toolkit,
+ ToolChunk,
+ ToolChoice,
+ PermissionBehavior,
+ ToolResponse,
+ PermissionEngine,
+ PermissionDecision,
)
-DEFAULT_COMPRESSION_PROMPT = (
- "<system-hint>You have been working on the task described above but have "
- "not yet completed it. "
- "Now write a continuation summary that will allow you to resume work "
- "efficiently in a future context window "
- "where the conversation history will be replaced with this summary. "
- "Your summary should be structured, concise, and actionable.</system-hint>"
-)
+class SummarySchema(BaseModel):
+ """The compressed memory model, used to generate summary of old memories"""
+ task_overview: str = Field(
+ max_length=300,
+ description=(
+ "The user's core request and success criteria.\n"
+ "Any clarifications or constraints they specified"
+ ),
+ )
+ current_state: str = Field(
+ max_length=300,
+ description=(
+ "What has been completed so far.\n"
+ "File created, modified, or analyzed (with paths if relevant).\n"
+ "Key outputs or artifacts produced."
+ ),
+ )
+ important_discoveries: str = Field(
+ max_length=300,
+ description=(
+ "Technical constraints or requirements uncovered.\n"
+ "Decisions made and their rationale.\n"
+ "Errors encountered and how they were resolved.\n"
+ "What approaches were tried that didn't work (and why)"
+ ),
+ )
+ next_steps: str = Field(
+ max_length=200,
+ description=(
+ "Specific actions needed to complete the task.\n"
+ "Any blockers or open questions to resolve.\n"
+ "Priority order if multiple steps remain"
+ ),
+ )
+ context_to_preserve: str = Field(
+ max_length=300,
+ description=(
+ "User preferences or style requirements.\n"
+ "Domain-specific details that aren't obvious.\n"
+ "Any promises made to the user"
+ ),
+ )
-class Agent:
- """The unified agent class in AgentScope library."""
- def __init__(
- self,
- name: str,
- sys_prompt: str,
- model: "ChatModelBase",
- max_iters: int = 20,
- ) -> None:
- """Initialize an agent instance."""
- if max_iters <= 0:
- raise ValueError("max_iters must be greater than 0")
-
- self.name = name
- self._sys_prompt = sys_prompt
- self.model = model
- self.max_iters = max_iters
-
- # TODO: storage - these should be loaded from storage
- self._loaded = False
- self.context: list[Msg] = []
- self.reply_id: str = ""
- self.cur_iter: int = 0
- self.confirmed_tool_call_ids: list[str] = []
- self.cur_summary: str = ""
-
- @property
- def sys_prompt(self) -> str:
- """Get the system prompt of the agent."""
- # TODO: Add toolkit skills prompt when toolkit is implemented
- return self._sys_prompt
+class CompressionConfig(BaseModel):
+ """The compression related configuration in AgentScope"""
+
+ model_config = {"arbitrary_types_allowed": True}
+ """Allow arbitrary types in the pydantic model."""
+
+ trigger_threshold: int = 20000
+ """The token threshold to trigger the compression process. When the
+ total token count in the memory exceeds this threshold, the
+ compression will be activated."""
+
+ keep_recent: int = 5
+ """The number of most recent messages to keep uncompressed in the
+ memory to preserve the recent context."""
+
+ compression_prompt: str = (
+ "<system-hint>You have been working on the task described above "
+ "but have not yet completed it. "
+ "Now write a continuation summary that will allow you to resume "
+ "work efficiently in a future context window where the "
+ "conversation history will be replaced with this summary. "
+ "Your summary should be structured, concise, and actionable."
+ "</system-hint>"
+ )
+ """The prompt used to guide the compression model to generate the
+ compressed summary, which will be wrapped into a user message and
+ attach to the end of the current memory."""
+
+ summary_template: str = (
+ "<system-info>Here is a summary of your previous work\n"
+ "# Task Overview\n"
+ "{task_overview}\n\n"
+ "# Current State\n"
+ "{current_state}\n\n"
+ "# Important Discoveries\n"
+ "{important_discoveries}\n\n"
+ "# Next Steps\n"
+ "{next_steps}\n\n"
+ "# Context to Preserve\n"
+ "{context_to_preserve}"
+ "</system-info>"
+ )
+ """The string template to present the compressed summary to the agent,
+ which will be formatted with the fields from the
+ `compression_summary_model`."""
+
+ summary_schema: dict = Field(
+ default_factory=SummarySchema.model_json_schema,
+ )
+ """The structured model used to guide the agent to generate the
+ structured compressed summary."""
+
+ compression_model: SerializeAsAny[ChatModelBase] | None = None
+ """The compression model used to generate the compressed summary. If
+ not provided, the agent's model will be used."""
+
+ @field_validator("compression_model", mode="before")
+ @classmethod
+ def validate_compression_model(cls, v: Any, info: ValidationInfo) -> Any:
+ """Deserialize compression_model from dict using context-injected
+ custom classes."""
+ if not isinstance(v, dict):
+ return v
+ custom_classes = (
+ info.context.get("custom_model_classes", [])
+ if info.context
+ else []
+ )
+ return _deserialize_model(
+ v,
+ custom_classes=custom_classes,
+ context=info.context,
+ )
+
+
+class ReasoningConfig(BaseModel):
+ """The reasoning related configuration"""
+
+ max_iters: int = 20
+ """The maximum number of iterations for the reasoning-acting loop."""
+
+
+class ActingConfig(BaseModel):
+ """The acting related configuration in AgentScope"""
+
+ parallel: bool = True
+ """Whether to execute tool calls in parallel when there are multiple tool
+ calls awaiting execution."""
+
- async def load_state(self) -> None:
- """Load the state from storage if available."""
- # TODO: Implement storage loading
+class Agent(BaseModel):
+ """The agent class."""
- async def save_state(self) -> None:
- """Save the state to storage if available."""
- # TODO: Implement storage saving
+ model_config = ConfigDict(arbitrary_types_allowed=True)
+
+ name: str = Field(description="The identifier of the agent.")
+ """The name of the agent."""
+
+ system_prompt: str = Field(default="You're a helpful assistant.")
+ """The base system prompt of the agent, extra hints will be attached to
+ this prompt during agent's reply."""
+
+ model: SerializeAsAny[ChatModelBase] = Field(
+ description="The language model used by the agent.",
+ )
+ """The language model used by the agent."""
+
+ max_retries: int = Field(
+ default=10,
+ gt=0,
+ description="Maximum number of retries when the model call fails.",
+ )
+ """The maximum number of retries when the model call fails. Must be
+ greater than 0."""
+
+ fallback_model: SerializeAsAny[ChatModelBase] | None = Field(
+ default=None,
+ description="The fallback model used when the main model fails.",
+ )
+ """The fallback model used when the main model fails. Also supports the
+ max_retries logic."""
+
+ compression: CompressionConfig = Field(
+ default_factory=CompressionConfig,
+ description="The compression related configuration for the agent.",
+ )
+ """The agent compression related configuration."""
+
+ reasoning: ReasoningConfig = Field(
+ default_factory=ReasoningConfig,
+ description="The reasoning related configuration for the agent.",
+ )
+ """The reasoning related configuration for the agent."""
+
+ acting: ActingConfig = Field(
+ default_factory=ActingConfig,
+ description="The acting related configuration for the agent.",
+ )
+ """The acting, i.e. tool execution, related configuration for the agent."""
+
+ state: AgentState = Field(default_factory=AgentState)
+ """The agent state, including the conversation context, permission context,
+ tool context, etc."""
+
+ toolkit: Toolkit = Field(exclude=True)
+ """The toolkit used by the agent."""
+
+ _engine: PermissionEngine = PrivateAttr()
+ """The permission engine used to manage the tool usage permissions for the
+ agent."""
+
+ # @field_validator("model", "fallback_model", mode="before")
+ # @classmethod
+ # def validate_model(cls, v: Any, info: ValidationInfo) -> Any:
+ # """Deserialize model from dict using context-injected custom
+ # classes."""
+ # if not isinstance(v, dict):
+ # return v
+ # custom_classes = (
+ # info.context.get("custom_model_classes", [])
+ # if info.context
+ # else []
+ # )
+ # return _deserialize_model(
+ # v,
+ # custom_classes=custom_classes,
+ # context=info.context,
+ # )
+
+ def model_post_init(self, __context: Any) -> None:
+ """Initialize the permission engine after the model is initialized."""
+ self._engine = PermissionEngine(self.state.permission_context)
+
+ # =======================================================================
+ # Agent public methods
+ # =======================================================================
async def reply_stream(
self,
msgs: Msg | list[Msg] | None = None,
- event: AgentEvent | None = None,
+ event: UserConfirmResultEvent
+ | ExternalExecutionResultEvent
+ | None = None,
) -> AsyncGenerator[AgentEvent, None]:
- """Reply to the given message and stream agent events."""
- await self.load_state()
+ """Reply to the given message and stream agent events.
+
+
+ **NOTE**:
+
+ - If requiring outside interaction for multiple tool calls and only
+ receive partial confirmation or execution results, the agent won't
+ re-send the requiring events for the unconfirmed or unexecuted tool
+ calls.
+ """
try:
async for chunk in self._reply(msgs=msgs, event=event):
if not isinstance(chunk, Msg):
yield chunk
finally:
- await self.save_state()
+ pass
async def reply(
self,
msgs: Msg | list[Msg] | None = None,
- event: AgentEvent | None = None,
+ event: UserConfirmResultEvent
+ | ExternalExecutionResultEvent
+ | None = None,
) -> Msg:
- """Reply to the given message, consuming all streamed events."""
- await self.load_state()
+ """Reply to the given message, consuming all streamed events.
+
+ Args:
+ msgs (`Msg | list[Msg] | None`, optional):
+ The message(s) to reply to. Can be a single `Msg` object,
+ a list of `Msg` objects, or `None` if there are no new
+ messages.
+ event (`UserConfirmResultEvent | ExternalExecutionResultEvent | \
+ None`, optional):
+ The event to continue from, which should be the result of the
+ required outside interaction triggered by the previous reply.
+ If the previous reply does not trigger any outside
+ interaction, this should be `None`.
+
+ Returns:
+ `Msg`:
+ A final reply message.
+ """
try:
final_msg: Msg | None = None
- async for chunk in self._reply(msgs=msgs, event=event):
- if chunk.is_last:
- final_msg = chunk.msg
+ async for evt_or_msg in self._reply(msgs=msgs, event=event):
+ if isinstance(evt_or_msg, Msg):
+ final_msg = evt_or_msg
if final_msg is None:
raise RuntimeError("Agent did not produce a final message.")
return final_msg
finally:
- await self.save_state()
+ pass
- def _save_to_context(
- self,
- blocks: list,
- _usage: ChatUsage | None = None,
- ) -> None:
- """Save content blocks into the context."""
- if len(self.context) == 0:
- self.context.append(
- Msg(name=self.name, content=list(blocks), role="assistant"),
- )
- else:
- last_msg = self.context[-1]
- if last_msg.role == "assistant" and last_msg.name == self.name:
- if isinstance(last_msg.content, str):
- last_msg.content = [TextBlock(text=last_msg.content)]
- last_msg.content.extend(blocks)
- # TODO: Merge usage if needed
- else:
- self.context.append(
- Msg(
- name=self.name,
- content=list(blocks),
- role="assistant",
- ),
- )
+ async def observe(self, msgs: Msg | list[Msg] | None = None) -> None:
+ """Receive external observation message(s) and save them into
+ context."""
+ await self._handle_incoming_messages(msgs)
- def _get_pending_tool_calls(self) -> list[ToolCallBlock]:
- """Get tool calls from the last assistant message that have no result
- yet."""
- if len(self.context) == 0:
- return []
- last_msg = self.context[-1]
- if last_msg.role != "assistant":
- return []
- content = (
- last_msg.content if isinstance(last_msg.content, list) else []
- )
- tool_calls = [b for b in content if isinstance(b, ToolCallBlock)]
- result_ids = {b.id for b in content if isinstance(b, ToolResultBlock)}
- return [tc for tc in tool_calls if tc.id not in result_ids]
-
- def _get_awaiting_tool_calls(self) -> dict:
- """Get the awaiting tool calls that need user confirmation or external
- execution."""
- pending_tool_calls = self._get_pending_tool_calls()
- pre_tool_calls: list = []
-
- for tool_call in enumerate(pending_tool_calls):
- # TODO: toolkit checks for user confirmation and external execution
- pre_tool_calls.append(tool_call)
-
- return {
- "awaiting_type": None,
- "expected_event_type": None,
- "awaiting_tool_calls": [],
- "pre_tool_calls": pre_tool_calls,
- }
+ async def compress_memory(self) -> None:
+ """Compress the agent's memory if the token count exceeds the
+ threshold."""
+ # TODO: Implement when compression_config is available
+
+ # ======================================================================
+ # Agent core methods, including _reply, _reasoning, _acting, etc.
+ # ======================================================================
async def _reply(
self,
msgs: Msg | list[Msg] | None = None,
- event: AgentEvent | None = None,
+ event: UserConfirmResultEvent
+ | ExternalExecutionResultEvent
+ | None = None,
) -> AsyncGenerator[AgentEvent | Msg, None]:
- """Core reply logic. Yields chunks with is_last flag."""
- awaiting_info = self._get_awaiting_tool_calls()
- expected_event_type = awaiting_info["expected_event_type"]
-
- if expected_event_type is not None:
- if event is None or event.type != expected_event_type:
- raise ValueError(
- f"Agent is awaiting '{expected_event_type}' but received "
- f"event of type '{event.type if event else 'none'}'.",
- )
-
- if isinstance(event, ExternalExecutionResultEvent):
- self._save_to_context(list(event.execution_results))
-
- elif isinstance(event, UserConfirmResultEvent):
- for result in event.confirm_results:
- confirmed = result.confirmed
- tool_call = result.tool_call
- if confirmed:
- self.confirmed_tool_call_ids.append(tool_call["id"])
- else:
- rejection_text = (
- f"<system-info>**Note** the user rejected the "
- f"execution of tool "
- f'"{tool_call["name"]}"!</system-info>'
- )
- yield ToolResultStartEvent(
- reply_id=self.reply_id,
- tool_call_id=tool_call["id"],
- tool_call_name=tool_call["name"],
- )
- yield ToolResultTextDeltaEvent(
- reply_id=self.reply_id,
- tool_call_id=tool_call["id"],
- delta=rejection_text,
- )
- yield ToolResultEndEvent(
- reply_id=self.reply_id,
- tool_call_id=tool_call["id"],
- state="interrupted",
- )
- self._save_to_context(
- [
- ToolResultBlock(
- id=tool_call["id"],
- name=tool_call["name"],
- output=[TextBlock(text=rejection_text)],
- state="interrupted",
- ),
- ],
- )
-
- processed_ids = {
- r.get("tool_call", {}).get("id")
- for r in event.confirm_results
- }
- if self.context:
- last_content = self.context[-1].content
- if isinstance(last_content, list):
- for block in last_content:
- if (
- isinstance(block, ToolCallBlock)
- and block.id in processed_ids
- ):
- block.await_user_confirmation = False
+ """Core reply logic."""
+ # ===================================================================
+ # Step 1: Checking agent input:
+ # - if incoming event and agent is waiting for an event
+ # - if event is None and agent is not waiting for an event
+ # ===================================================================
+ is_awaiting = await self._check_incoming_event(event)
+ # ===================================================================
+ # Step 2: Handling agent event if applicable
+ # - yield tool result events for the denied tool calls, or
+ # - update the reply state as a new reply process
+ # ===================================================================
+ if is_awaiting:
+ async for evt in self._handle_incoming_event(event):
+ yield evt
else:
- self.cur_iter = 0
- self.reply_id = str(uuid.uuid4())
- self.confirmed_tool_call_ids = []
+ await self._handle_incoming_messages(msgs)
+ # Update the context with the incoming message and state
+ self.state.reply_id = uuid.uuid4().hex
+ self.state.cur_iter = 0
- yield RunStartedEvent(
- session_id="",
- reply_id=self.reply_id,
+ yield ReplyStartEvent(
+ session_id=self.state.session_id,
+ reply_id=self.state.reply_id,
name=self.name,
- role="assistant",
)
- if isinstance(msgs, list):
- self.context.extend(msgs)
- elif msgs is not None:
- self.context.append(msgs)
+ # ===================================================================
+ # Step 3: Enter the reasoning-acting loop until reaching max_iters or
+ # no more tool calls to execute
+ # ===================================================================
+ while self.state.cur_iter < self.reasoning.max_iters:
+ # ===============================================================
+ # Step 3.1:
+ # ===============================================================
+ action, data = self._check_next_action()
+ if action == "exit" and isinstance(data, Msg):
+ yield data
+ return
- while self.cur_iter < self.max_iters:
- pending_tool_calls = self._get_pending_tool_calls()
- if len(pending_tool_calls) == 0:
- await self._compress_memory_if_needed()
- async for evt in self._reasoning(tool_choice="auto"):
+ # ===============================================================
+ # Step 3.2: Execute reasoning if no more tools to be executed
+ # ===============================================================
+ if action == "reasoning":
+ # Compressed the memory if needed before reasoning
+ await self.compress_memory()
+ # Perform reasoning
+ async for evt in self._reasoning():
+ # Exit the loop when no tool calls generated and the reply
+ # message is generated
+ if isinstance(evt, Msg):
+ yield ReplyEndEvent(
+ session_id=self.state.session_id,
+ reply_id=self.state.reply_id,
+ )
+ yield evt
+ return
yield evt
- awaiting_info = self._get_awaiting_tool_calls()
- awaiting_type = awaiting_info["awaiting_type"]
- awaiting_tool_calls = awaiting_info["awaiting_tool_calls"]
- pre_tool_calls = awaiting_info["pre_tool_calls"]
-
- for tool_call in pre_tool_calls:
- async for evt in self._acting(tool_call=tool_call):
- yield evt
- self.confirmed_tool_call_ids = [
- cid
- for cid in self.confirmed_tool_call_ids
- if cid != tool_call.id
- ]
+ # ===============================================================
+ # Step 3.3: Getting batches of tool calls to be executed
+ # - If not, finish the loop by yielding RunFinishedEvent and exit
+ # - Otherwise, execute by batch and continue the loop
+ # ===============================================================
+ for batch in await self._batch_tool_calls():
+ if batch.type == "sequential":
+ evt_generator = self._execute_sequential_tool_calls(
+ batch.tool_calls,
+ )
- if awaiting_type is not None:
- if awaiting_type == EventType.REQUIRE_USER_CONFIRM:
- yield RequireUserConfirmEvent(
- reply_id=self.reply_id,
- tool_calls=awaiting_tool_calls,
+ elif batch.type == "concurrent":
+ evt_generator = self._execute_concurrent_tool_calls(
+ batch.tool_calls,
)
+
else:
- yield RequireExternalExecutionEvent(
- reply_id=self.reply_id,
- tool_calls=awaiting_tool_calls,
+ raise ValueError(
+ f"Invalid batch type: {batch.type}",
)
- waiting_text = (
- "Waiting for user confirmation ..."
- if awaiting_type == EventType.REQUIRE_USER_CONFIRM
- else "Waiting for external execution ..."
- )
- yield Msg(
- name=self.name,
- content=[TextBlock(text=waiting_text)],
- role="assistant",
- )
- return
- if len(pre_tool_calls) == 0:
- break
+ break_execution = False
+ async for evt in evt_generator:
+ yield evt
+ if isinstance(
+ evt,
+ (
+ RequireUserConfirmEvent,
+ RequireExternalExecutionEvent,
+ ),
+ ):
+ break_execution = True
- self.cur_iter += 1
+ # If it requires outside interaction stop executing the next
+ # batch and wait for outside trigger events
+ if break_execution:
+ # Yield a Msg object for outside handling
+ yield AssistantMsg(
+ id=self.state.reply_id,
+ name=self.name,
+ content="Waiting for tool calls to be confirmed or "
+ "executed from outside ...",
+ )
- last_block = None
- if self.context:
- last_content = self.context[-1].content
- if isinstance(last_content, list) and last_content:
- last_block = last_content[-1]
- if last_block is None or not isinstance(last_block, TextBlock):
- async for evt in self._reasoning(tool_choice="none"):
- yield evt
+ return
+
+ # Update the iteration count after each round of reasoning-acting
+ self.state.cur_iter += 1
- yield RunFinishedEvent(
- session_id="",
- reply_id=self.reply_id,
+ # ===================================================================
+ # Step 4: Handling the max iteration executed
+ # ===================================================================
+ yield ExceedMaxItersEvent(
+ reply_id=self.state.reply_id,
+ name=self.name,
)
- final_block = None
- if self.context:
- last_content = self.context[-1].content
- if isinstance(last_content, list) and last_content:
- final_block = last_content[-1]
- yield Msg(
- id=self.reply_id,
+ yield AssistantMsg(
+ id=self.state.reply_id,
name=self.name,
- content=[final_block] if final_block else [],
- role="assistant",
+ content="Executed maximum iterations of reasoning-acting loop"
+ "without finishing the task.",
)
async def _reasoning(
self,
- tool_choice: Literal["auto", "none", "required"] = "auto",
- ) -> AsyncGenerator:
+ tool_choice: ToolChoice = "auto",
+ ) -> AsyncGenerator[
+ ModelCallStartEvent
+ | TextBlockStartEvent
+ | TextBlockDeltaEvent
+ | TextBlockEndEvent
+ | ToolCallBlock
+ | ToolCallDeltaEvent
+ | ToolCallEndEvent
+ | ThinkingBlockStartEvent
+ | ThinkingBlockDeltaEvent
+ | ThinkingBlockEndEvent
+ | DataBlockStartEvent
+ | DataBlockDeltaEvent
+ | DataBlockEndEvent
+ | ModelCallEndEvent
+ | Msg,
+ None,
+ ]:
"""Core reasoning logic. Yields chunks with is_last flag."""
# TODO: Pass tool schemas from toolkit when toolkit is implemented
- yield ModelCallStartedEvent(
- reply_id=self.reply_id,
+ yield ModelCallStartEvent(
+ reply_id=self.state.reply_id,
model_name=self.model.model_name,
)
- system_msg = Msg(
- name="system",
- content=[TextBlock(text=self.sys_prompt)],
- role="system",
- )
- messages = [system_msg]
- if self.cur_summary:
+ # The system prompt
+ messages = [
+ SystemMsg(name="system", content=await self._get_system_prompt()),
+ ]
+ # The compressed summary
+ if self.state.summary:
messages.append(
- Msg(
- name="user",
- content=[TextBlock(text=self.cur_summary)],
- role="user",
- ),
+ UserMsg(name="user", content=self.state.summary),
)
- messages.extend(self.context)
+ # The conversation context
+ messages.extend(self.state.context)
+
+ # Get the tools schemas
+ tools = self.toolkit.get_function_schemas(
+ self.state.tool_context.activated_groups,
+ )
- # TODO: Pass tools and tool_choice when toolkit is implemented
- res = await self.model(
+ res = await self._call_model(
messages=messages,
+ tools=tools,
tool_choice=tool_choice,
)
- block_ids: dict = {
- "text_block_id": None,
- "thinking_block_id": None,
- "tool_call_ids": [],
- }
+ block_ids: dict = {"text": None, "thinking": None, "tools": []}
completed_response: ChatResponse | None = None
if self.model.stream:
async for chunk in res:
+ # Break if it's the last chunk with completed response
if chunk.is_last:
completed_response = chunk
break
+
+ # Convert the chunk into events
async for evt in self._convert_chat_response_to_event(
block_ids,
chunk,
):
yield evt
+
elif isinstance(res, ChatResponse):
completed_response = res
async for evt in self._convert_chat_response_to_event(
@@ -404,24 +586,26 @@ class Agent:
):
yield evt
- if block_ids["text_block_id"] is not None:
+ # Send the ended events for the remaining active blocks
+ if block_ids["text"] is not None:
yield TextBlockEndEvent(
- reply_id=self.reply_id,
- block_id=block_ids["text_block_id"],
+ reply_id=self.state.reply_id,
+ block_id=block_ids["text"],
)
- if block_ids["thinking_block_id"] is not None:
+ if block_ids["thinking"] is not None:
yield ThinkingBlockEndEvent(
- reply_id=self.reply_id,
- block_id=block_ids["thinking_block_id"],
+ reply_id=self.state.reply_id,
+ block_id=block_ids["thinking"],
)
- for tool_call_id in block_ids["tool_call_ids"]:
+ for tool_call_id in block_ids["tools"]:
yield ToolCallEndEvent(
- reply_id=self.reply_id,
+ reply_id=self.state.reply_id,
tool_call_id=tool_call_id,
)
- yield ModelCallEndedEvent(
- reply_id=self.reply_id,
+ # Send the model call ended event with usage if available
+ yield ModelCallEndEvent(
+ reply_id=self.state.reply_id,
input_tokens=completed_response.usage.input_tokens
if completed_response.usage
else 0,
@@ -435,136 +619,1098 @@ class Agent:
completed_response.usage,
)
- async def _acting(
+ # If no tool call is generated, return the final message directly
+ if not any(
+ isinstance(_, ToolCallBlock) for _ in completed_response.content
+ ):
+ yield AssistantMsg(
+ id=self.state.reply_id,
+ name=self.name,
+ content=list(completed_response.content),
+ )
+
+ async def _check_incoming_event(
+ self,
+ event: UserConfirmResultEvent | ExternalExecutionResultEvent | None,
+ ) -> bool:
+ """Check if the agent is waiting for the incoming event, if no, raise
+ error.
+
+ Args:
+ event (`UserConfirmResultEvent | ExternalExecutionResultEvent \
+ | None`):
+ The incoming event to be checked.
+
+ Raises:
+ `ValueError`:
+ If the agent is not waiting for the incoming event, or the
+ event is not valid.
+
+ Returns:
+ `bool`:
+ If the agent is waiting for the incoming event, that means
+ this reply calling continues from the previous one. If not,
+ the reply id and iteration count should be updated for the new
+ reply.
+ """
+ awaiting_confirmations = []
+ awaiting_external_executions = []
+
+ last_msg = self._get_last_msg()
+ if last_msg:
+ # The completed tool call ids
+ tool_result_ids = [
+ _.id for _ in last_msg.get_content_blocks("tool_result")
+ ]
+
+ for tool_call in last_msg.get_content_blocks("tool_call"):
+ if tool_call.state == ToolCallState.ASKING:
+ awaiting_confirmations.append(tool_call.id)
+ elif (
+ tool_call.state == ToolCallState.SUBMITTED
+ and tool_call.id not in tool_result_ids
+ ):
+ # submitted but no result yet, i.e. external execution
+ awaiting_external_executions.append(tool_call.id)
+
+ # No incoming event but needed
+ if event is None and (
+ awaiting_confirmations or awaiting_external_executions
+ ):
+ raise ValueError(
+ f"Agent is waiting for {len(awaiting_confirmations)} tool "
+ f"calls and external execution results for "
+ f"{len(awaiting_external_executions)} tool calls, "
+ f"but received no event.",
+ )
+
+ if isinstance(event, UserConfirmResultEvent):
+ if not awaiting_confirmations:
+ raise ValueError(
+ f"Agent is not waiting for user confirmation, "
+ f"but received UserConfirmResultEvent: {event}",
+ )
+
+ # Given event, required but not match
+ extra_ids = set(
+ _.tool_call.id for _ in event.confirm_results
+ ) - set(awaiting_confirmations)
+ if extra_ids:
+ raise ValueError(
+ f"Received UserConfirmResultEvent with tool call ids "
+ f"{extra_ids} that are not waiting for confirmation.",
+ )
+
+ if isinstance(event, ExternalExecutionResultEvent):
+ if not awaiting_external_executions:
+ raise ValueError(
+ f"Agent is not waiting for external execution result, "
+ f"but received ExternalExecutionResultEvent: {event}",
+ )
+
+ extra_ids = set(_.id for _ in event.execution_results) - set(
+ awaiting_external_executions,
+ )
+ if extra_ids:
+ raise ValueError(
+ f"Received ExternalExecutionResultEvent with tool call "
+ f"ids {extra_ids} that are not waiting for external "
+ f"execution results.",
+ )
+
+ return event is not None
+
+ async def _handle_incoming_event(
+ self,
+ event: UserConfirmResultEvent | ExternalExecutionResultEvent | None,
+ ) -> AsyncGenerator[
+ ToolResultStartEvent
+ | ToolResultTextDeltaEvent
+ | ToolResultDataDeltaEvent
+ | ToolResultEndEvent,
+ None,
+ ]:
+ """Handle the incoming event and update the context accordingly.
+
+ Args:
+ event (`UserConfirmResultEvent | ExternalExecutionResultEvent \
+ | None`):
+ The incoming event to be handled.
+
+ Yields:
+ `ToolResultStartEvent \
+ | ToolResultTextDeltaEvent \
+ | ToolResultDataDeltaEvent \
+ | ToolResultEndEvent`:
+ The events generated during the handling of the incoming event.
+ """
+ # Return directly if no event
+ if event is None or len(self.state.context) == 0:
+ return
+
+ if isinstance(event, UserConfirmResultEvent):
+ # The confirmed tool calls
+ confirmed_tool_calls = {
+ _.tool_call.id: _ for _ in event.confirm_results
+ }
+
+ # Update the state with the confirmed tool calls
+ last_msg = self.state.context[-1]
+ for tool_call in last_msg.get_content_blocks("tool_call"):
+ if len(confirmed_tool_calls) == 0:
+ break
+
+ if tool_call.id in confirmed_tool_calls:
+ confirmation = confirmed_tool_calls[tool_call.id]
+ if confirmation.confirmed:
+ # Update state and wait for execution in the next step
+ self._update_tool_call_state(
+ tool_call.id,
+ ToolCallState.ALLOWED,
+ )
+
+ # Update name and input in case user modification is
+ # allowed
+ tool_call.name = confirmation.tool_call.name
+ tool_call.input = confirmation.tool_call.input
+
+ # Update the permission rule if accepted
+ if confirmation.rules:
+ for rule in confirmation.rules:
+ self._engine.add_rule(rule)
+
+ else:
+ # Update the state to deny and handling
+ async for evt in self._handle_error_tool_call(
+ tool_call,
+ message=(
+ "<system-reminder>The execution of tool "
+ f'"{tool_call.name}" is denied by user!'
+ "</system-reminder>"
+ ),
+ state=ToolResultState.DENIED,
+ ):
+ yield evt
+
+ # Delete for quick lookup and later processing
+ confirmed_tool_calls.pop(tool_call.id)
+
+ elif isinstance(event, ExternalExecutionResultEvent):
+ # Directly append the execution results into context
+ for tool_result in event.execution_results:
+ async for evt in self._convert_tool_chunk_to_event(
+ tool_result.id,
+ tool_result.output,
+ ):
+ yield evt
+
+ yield ToolResultEndEvent(
+ reply_id=self.state.reply_id,
+ tool_call_id=tool_result.id,
+ state=tool_result.state,
+ )
+
+ self._save_to_context([tool_result])
+
+ # Update the state according to the execution result state
+ self._update_tool_call_state(
+ tool_result.id,
+ ToolCallState.FINISHED,
+ )
+
+ else:
+ raise ValueError(f"Invalid event type: {event}")
+
+ async def _handle_incoming_messages(
+ self,
+ msgs: Msg | list[Msg] | None,
+ ) -> None:
+ """Check and handle the incoming messages before the reasoning-acting
+ loop."""
+ if msgs:
+ copied_msgs: list = deepcopy(msgs)
+ if isinstance(copied_msgs, Msg):
+ copied_msgs = [copied_msgs]
+ for msg in copied_msgs:
+ if (
+ not isinstance(msg, Msg)
+ or msg.role == "system"
+ or msg.has_content_blocks(
+ ["tool_call", "tool_result", "thinking"],
+ )
+ ):
+ raise ValueError(
+ f"Invalid message in the input: {msg}. "
+ f"The message should be a Msg object with "
+ f"role 'user' or 'assistant', "
+ f"and should not contain tool calls, "
+ f"tool results or thinking blocks.",
+ )
+
+ self.state.context.append(msg)
+
+ async def _batch_tool_calls(self) -> list[_ToolCallBatch]:
+ """Batch the tool calls into a sequence of batches that should be
+ executed **sequentially** or **concurrently** according to the tool
+ properties `is_concurrency_safe` and `is_read_only`.
+ """
+ # All tool calls that haven't the corresponding results in the context
+ tool_calls = self._get_executable_tool_calls()
+
+ # Batch the tool calls according to whether they can be executed
+ # concurrently or not
+ batches: list[_ToolCallBatch] = []
+ for tool_call in tool_calls:
+ registered_tool = self.toolkit.tools.get(tool_call.name)
+
+ # Treat unregistered or unavailable tools as concurrent tools since
+ # it will not generate side effects and be blocked with acting
+ if (
+ registered_tool is None
+ or registered_tool.tool.is_concurrency_safe
+ ):
+ if len(batches) == 0 or batches[-1].type != "concurrent":
+ batches.append(
+ _ToolCallBatch(
+ type="concurrent",
+ tool_calls=[tool_call],
+ ),
+ )
+ else:
+ batches[-1].tool_calls.append(tool_call)
+ else:
+ if len(batches) == 0 or batches[-1].type != "sequential":
+ batches.append(
+ _ToolCallBatch(
+ type="sequential",
+ tool_calls=[tool_call],
+ ),
+ )
+ else:
+ batches[-1].tool_calls.append(tool_call)
+
+ return batches
+
+ async def _execute_sequential_tool_calls(
+ self,
+ tool_calls: list[ToolCallBlock],
+ ) -> AsyncGenerator[
+ RequireUserConfirmEvent
+ | RequireExternalExecutionEvent
+ | ToolResultStartEvent
+ | ToolResultTextDeltaEvent
+ | ToolResultDataDeltaEvent
+ | ToolResultEndEvent,
+ None,
+ ]:
+ """Execute the given tool calls sequentially and yield the events.
+
+ If "RequireUserConfirmEvent" or "RequireExternalExecutionEvent" is
+ yielded during the execution, the execution will be paused in the
+ sequential mode and wait for the outside trigger events.
+
+ Args:
+ tool_calls (`list[ToolCallBlock]`):
+ The tool calls to be executed sequentially.
+
+ Yields:
+ `RequireUserConfirmEvent \
+ | RequireExternalExecutionEvent \
+ | ToolResultStartEvent \
+ | ToolResultTextDeltaEvent \
+ | ToolResultDataDeltaEvent \
+ | ToolResultEndEvent`:
+ The events generated during the execution of the tool calls.
+ """
+ break_execution = False
+ for tool_call in tool_calls:
+ async for evt in self._execute_tool_call(tool_call):
+ yield evt
+ if isinstance(
+ evt,
+ (
+ RequireUserConfirmEvent,
+ RequireExternalExecutionEvent,
+ ),
+ ):
+ break_execution = True
+ break
+ if break_execution:
+ break
+
+ async def _execute_concurrent_tool_calls(
+ self,
+ tool_calls: list[ToolCallBlock],
+ ) -> AsyncGenerator[
+ RequireUserConfirmEvent
+ | RequireExternalExecutionEvent
+ | ToolResultStartEvent
+ | ToolResultTextDeltaEvent
+ | ToolResultDataDeltaEvent
+ | ToolResultEndEvent,
+ None,
+ ]:
+ """Execute the given tool calls concurrently and yield the events.
+
+ All tool calls are executed concurrently. If one or more tool calls
+ fail, the remaining ones are **not** cancelled and will run to
+ completion. After all tool calls finish, every exception is collected
+ and re-raised together as an :py:exc:`ExceptionGroup` so the caller
+ can inspect each failure individually.
+
+ The event stream is guaranteed to be complete: the loop exits only
+ after a sentinel value placed by the gather task is received, which
+ means every ``queue.put`` from every worker has already finished
+ before the generator returns.
+
+ Args:
+ tool_calls (`list[ToolCallBlock]`):
+ The tool calls to be executed concurrently.
+
+ Yields:
+ `RequireUserConfirmEvent \
+ | RequireExternalExecutionEvent \
+ | ToolResultStartEvent \
+ | ToolResultTextDeltaEvent \
+ | ToolResultDataDeltaEvent \
+ | ToolResultEndEvent`:
+ The events generated during the execution of the tool calls.
+
+ Raises:
+ `ExceptionGroup`:
+ Raised after all tool calls finish when one or more of them
+ raised an exception. Each individual exception is included in
+ the group.
+ """
+ # A sentinel object that signals all worker tasks have finished and
+ # all events have already been put into the queue.
+ sentinel = object()
+
+ # Create a queue to collect events from all concurrent workers.
+ queue: Queue = Queue()
+
+ async def _run_all() -> list[BaseException | None]:
+ """Run all tool calls concurrently and push the sentinel when done.
+
+ Returns:
+ `list[BaseException | None]`:
+ One entry per tool call. Each entry is either ``None``
+ (success) or the exception raised by that tool call.
+ """
+ # return_exceptions=True keeps all tasks running even when some
+ # fail, and returns exceptions as values instead of re-raising.
+ results = await asyncio.gather(
+ *[self._into_queue(tc, queue) for tc in tool_calls],
+ return_exceptions=True,
+ )
+ # The sentinel is placed AFTER gather returns, which guarantees
+ # that every queue.put inside _into_queue has already completed.
+ await queue.put(sentinel)
+ return results # type: ignore[return-value]
+
+ gather_task = asyncio.create_task(_run_all())
+
+ # Drain the queue until the sentinel is encountered.
+ while True:
+ event = await queue.get()
+ if event is sentinel:
+ break
+ yield event
+
+ # All tasks are done at this point; collect and re-raise exceptions.
+ results = await gather_task
+ exceptions = [r for r in results if isinstance(r, Exception)]
+ if exceptions:
+ raise ExceptionGroup(
+ "One or more tool calls raised an exception",
+ exceptions,
+ )
+
+ async def _into_queue(
self,
tool_call: ToolCallBlock,
- ) -> AsyncGenerator:
- """Core acting logic. Yields chunks with is_last flag."""
+ queue: Queue,
+ ) -> None:
+ """Execute a single tool call and forward every event into *queue*.
+
+ Args:
+ tool_call (`ToolBlockCall`):
+ The tool call to execute.
+ queue (`Queue`):
+ The shared async queue that collects events from all
+ concurrent workers.
+ """
+ async for evt in self._execute_tool_call(tool_call):
+ await queue.put(evt)
+
+ async def _execute_tool_call(
+ self,
+ tool_call: ToolCallBlock,
+ ) -> AsyncGenerator[
+ RequireUserConfirmEvent
+ | RequireExternalExecutionEvent
+ | ToolResultStartEvent
+ | ToolResultTextDeltaEvent
+ | ToolResultDataDeltaEvent
+ | ToolResultEndEvent,
+ None,
+ ]:
+ """Execute a single tool call with permission checking.
+
+ Args:
+ tool_call (`ToolCallBlock`):
+ The tool call block to be executed.
+
+ Yields:
+ `RequireUserConfirmEvent \
+ | RequireExternalExecutionEvent \
+ | ToolResultStartEvent \
+ | ToolResult \
+ | TextDeltaEvent \
+ | ToolResultDataDeltaEvent \
+ | ToolResultEndEvent`:
+ The events generated during the tool call execution.
+ """
+ # ===================================================================
+ # Step 1: Check and parse the tool call input:
+ # - if failed, directly return the error message to the agent
+ # - if success, continue to permission checking and tool execution
+ # ===================================================================
+ try:
+ # Check if the tool is available
+ tool = self.toolkit.check_tool_available(
+ tool_call.name,
+ self.state.tool_context.activated_groups,
+ )
+
+ # Try to parse the input with the tool schema
+ parsed_input = _json_loads_with_repair(
+ tool_call.input,
+ tool.input_schema,
+ )
+
+ # Validate the parsed input with the tool schema
+ # TODO: Maybe some logic to mix the validation error in runtime
+ try:
+ jsonschema.validate(parsed_input, tool.input_schema)
+ except jsonschema.ValidationError as e:
+ raise AgentOrientedException(
+ f"Input validation failed for tool '{tool_call.name}': "
+ f"{e.message}",
+ ) from e
+
+ # The exceptions that
+ # - cannot found tool
+ # - tool not available
+ # - input parsing failure
+ except AgentOrientedException as e:
+ async for evt in self._handle_error_tool_call(
+ tool_call,
+ e.message,
+ state=ToolResultState.ERROR,
+ ):
+ yield evt
+
+ return
+
+ # ===================================================================
+ # Step 2: Check permission by toolkit and permission engine
+ # ===================================================================
+ if tool_call.state == ToolCallState.ALLOWED:
+ # Already allowed by user confirmation, skip permission checking
+ decision = PermissionDecision(
+ behavior=PermissionBehavior.ALLOW,
+ message="Already allowed by user confirmation.",
+ )
+ else:
+ decision = await self._engine.check_permission(
+ tool,
+ parsed_input,
+ )
+
+ # ===================================================================
+ # Step 3: Handle the permission and execute the tool call if allowed
+ # ===================================================================
+
+ # Case 1: Ask for user confirmation if needed
+ if decision.behavior in [
+ PermissionBehavior.ASK,
+ PermissionBehavior.PASSTHROUGH,
+ ]:
+ # Set the state of the tool call to "ask"
+ # **Note** the update must be done before yielding the event
+ self._update_tool_call_state(
+ tool_call.id,
+ ToolCallState.ASKING,
+ )
+
+ yield RequireUserConfirmEvent(
+ reply_id=self.state.reply_id,
+ tool_calls=[tool_call],
+ )
+ return
+
+ # Case 2: Denied by the permission system
+ if decision.behavior == PermissionBehavior.DENY:
+ async for evt in self._handle_error_tool_call(
+ tool_call,
+ decision.message,
+ state=ToolResultState.DENIED,
+ ):
+ yield evt
+
+ return
+
+ # Case 3: Allowed by the permission system, execute the tool call and
+ # yield the events
+ if decision.behavior == PermissionBehavior.ALLOW:
+ self._update_tool_call_state(
+ tool_call.id,
+ ToolCallState.ALLOWED,
+ )
+ # Send start event
+ yield ToolResultStartEvent(
+ reply_id=self.state.reply_id,
+ tool_call_id=tool_call.id,
+ tool_call_name=tool_call.name,
+ )
+ # Send requiring external execution event if it's an external tool
+ if tool.is_external_tool:
+ # Update the state to "submitted" BEFORE yielding
+ # because the outer loop will break immediately after
+ # receiving this event, preventing any code after yield
+ # from executing
+ self._update_tool_call_state(
+ tool_call.id,
+ ToolCallState.SUBMITTED,
+ )
+ yield RequireExternalExecutionEvent(
+ reply_id=self.state.reply_id,
+ tool_calls=[tool_call],
+ )
+ return
+
+ # Execute the tool call and yield the events.
+
+ res = self.toolkit.call_tool(tool_call, self.state)
+ async for chunk in res:
+ if isinstance(chunk, ToolResponse):
+ self._save_to_context(
+ [
+ ToolResultBlock(
+ id=tool_call.id,
+ name=tool_call.name,
+ output=chunk.content,
+ state=chunk.state,
+ ),
+ ],
+ )
+ # Ends the tool call lifecycle.
+ self._update_tool_call_state(
+ tool_call.id,
+ ToolCallState.FINISHED,
+ )
+ # The ended event for the tool result
+ yield ToolResultEndEvent(
+ reply_id=self.state.reply_id,
+ tool_call_id=tool_call.id,
+ state=chunk.state,
+ )
+
+ else:
+ async for evt in self._convert_tool_chunk_to_event(
+ tool_call.id,
+ chunk.content,
+ ):
+ yield evt
+
+ return
+
+ raise ValueError(
+ f"Invalid permission decision behavior: {decision.behavior}",
+ )
+
+ async def _handle_error_tool_call(
+ self,
+ tool_call: ToolCallBlock,
+ message: str,
+ state: ToolResultState,
+ ) -> AsyncGenerator[
+ ToolResultStartEvent
+ | ToolResultTextDeltaEvent
+ | ToolResultDataDeltaEvent
+ | ToolResultEndEvent,
+ None,
+ ]:
+ """A quick handling for the non-streaming tool results, and ends the
+ lifecycle of the tool call by updating its state to "finished".
+
+ Args:
+ tool_call (`ToolCallBlock`):
+ The tool call block that has errors.
+ message (`str`):
+ The error message to be returned for the tool call.
+ state (`ToolResultState`):
+ The state of the tool result, which can be "error", "denied",
+
+ Yields:
+ `ToolResultStartEvent \
+ | ToolResultTextDeltaEvent \
+ | ToolResultDataDeltaEvent \
+ | ToolResultEndEvent`:
+ The events generated for the error tool call.
+ """
+
yield ToolResultStartEvent(
- reply_id=self.reply_id,
+ reply_id=self.state.reply_id,
tool_call_id=tool_call.id,
tool_call_name=tool_call.name,
)
- # TODO: Implement toolkit execution when toolkit is available
- # res = self.toolkit.call_tool_function(tool_call)
- # async for tool_res in res:
- # if tool_res.is_last:
- # result_block = {
- # "type": "tool_result",
- # "id": tool_call["id"],
- # "name": tool_call["name"],
- # "output": tool_res.content,
- # "state": tool_res.state,
- # }
- # self._save_to_context([result_block])
- # return
- # async for evt in self._convert_tool_response_to_event(
- # tool_call, tool_res
- # ):
- # yield evt
- raise NotImplementedError("Toolkit not yet implemented.")
-
- async def _observe(self, msgs: Msg | list[Msg] | None = None) -> None:
- """Receive external observation message(s) and save them into
- context."""
- await self.load_state()
- if isinstance(msgs, list):
- self.context.extend(msgs)
- elif msgs is not None:
- self.context.append(msgs)
+ result = ToolChunk(
+ content=[TextBlock(text=message)],
+ state=state,
+ )
+
+ # Return the result directly to the agent
+ self._save_to_context(
+ [
+ ToolResultBlock(
+ id=tool_call.id,
+ name=tool_call.name,
+ output=message,
+ state=state,
+ ),
+ ],
+ )
+
+ async for evt in self._convert_tool_chunk_to_event(
+ tool_call.id,
+ result.content,
+ ):
+ yield evt
+
+ yield ToolResultEndEvent(
+ reply_id=self.state.reply_id,
+ tool_call_id=tool_call.id,
+ state=state,
+ )
+
+ self._update_tool_call_state(
+ tool_call.id,
+ ToolCallState.FINISHED,
+ )
+
+ # =======================================================================
+ # Context management related methods
+ # =======================================================================
+
+ def _split_context_for_compression(self) -> tuple[list[Msg], list[Msg]]:
+ """Split context into parts to compress and parts to keep recent."""
+ # TODO: Implement full splitting logic when compression_config is
+ # available
+ return [], list(self.state.context)
+
+ # ======================================================================
+ # Agent internal utility methods
+ # ======================================================================
+
+ async def _get_system_prompt(self) -> str:
+ """Get the system prompt of the agent."""
+ prompt = [self.system_prompt]
+
+ # Skill related instructions
+ skill_instructions = await self.toolkit.get_skill_instructions()
+ if skill_instructions:
+ prompt.append(skill_instructions)
+
+ return "\n".join(prompt)
+
+ async def _call_model(
+ self,
+ messages: list[Msg],
+ tools: list[dict],
+ tool_choice: ToolChoice,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Perform model inference and return the response.
+
+ Args:
+ messages (`list[Msg]`):
+ The input messages to the model.
+ tools (`list[dict]`):
+ The function schemas of the tools.
+ tool_choice (`ToolChoice`):
+ The tool choice strategy for the model call.
+
+ Returns:
+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+ The model response, which can be a `ChatResponse` for
+ non-streaming models, or an async generator yielding
+ `ChatResponse` chunks for streaming models.
+ """
+ models = [self.model]
+
+ # Fallback to the secondary model if the primary model fails after
+ # retries
+ if self.fallback_model:
+ models.append(self.fallback_model)
+
+ last_exception = None
+ for model in models:
+ for _ in range(self.max_retries):
+ try:
+ return await model(
+ messages=messages,
+ tools=tools,
+ tool_choice=tool_choice,
+ )
+ except Exception as e:
+ logger.warning(
+ "Model %s call failed for agent %s. "
+ "Retrying (%d/%d)...",
+ model.model_name,
+ self.name,
+ _ + 1,
+ self.max_retries,
+ )
+ last_exception = e
+
+ if last_exception:
+ raise last_exception from None
+
+ raise RuntimeError(
+ "Model call failed after retries, but no exception was raised.",
+ )
+
+ def _update_tool_call_state(
+ self,
+ tool_call_id: str,
+ state: ToolCallState,
+ ) -> None:
+ """Update the tool call state. This function is to avoid the update
+ not reflected in the context due to the shallow copy of the content
+ blocks somewhere in the code.
+
+ Args:
+ tool_call_id (`str`):
+ The tool call id to be updated.
+ state (`ToolCallState`):
+ The new state of the tool call.
+ """
+ if len(self.state.context) == 0:
+ return
+ last_msg = self.state.context[-1]
+ if last_msg.role != "assistant" or last_msg.name != self.name:
+ return
+ for block in last_msg.get_content_blocks():
+ if isinstance(block, ToolCallBlock) and block.id == tool_call_id:
+ block.state = state
+ break
+
+ def _save_to_context(
+ self,
+ blocks: Sequence[
+ TextBlock
+ | ThinkingBlock
+ | ToolCallBlock
+ | ToolResultBlock
+ | DataBlock
+ ],
+ _usage: ChatUsage | None = None,
+ ) -> None:
+ """Save content blocks into the context."""
+ if len(self.state.context) == 0:
+ self.state.context.append(
+ AssistantMsg(name=self.name, content=list(blocks)),
+ )
+ else:
+ last_msg = self.state.context[-1]
+ if last_msg.role == "assistant" and last_msg.name == self.name:
+ if isinstance(last_msg.content, str):
+ last_msg.content = [TextBlock(text=last_msg.content)]
+ last_msg.content.extend(blocks)
+ # TODO: Merge usage if needed
+ else:
+ self.state.context.append(
+ AssistantMsg(
+ name=self.name,
+ content=list(blocks),
+ ),
+ )
+
+ def _get_last_msg(self) -> Msg | None:
+ """Get the last message in the context that belongs to this agent."""
+ if len(self.state.context) == 0:
+ return None
+ last_msg = self.state.context[-1]
+ if last_msg.role == "assistant" and last_msg.name == self.name:
+ return last_msg
+ return None
+
+ def _check_next_action(
+ self,
+ ) -> (
+ tuple[Literal["exit"], Msg]
+ | tuple[Literal["reasoning"], None]
+ | tuple[Literal["acting"], None]
+ ):
+ """Check the next action for the agent
+
+ Awaiting tool calls:
+ The tool calls waiting for the outside events (confirmation or
+ external execution results, state = "asking" or "submitted")
+ Executable tool calls:
+ The tool calls allowed by the incoming confirmation events and
+ haven't been executed yet (state = "allowed")
+
+ The next action:
+
+ | | Awaiting tool calls | No awaiting tool call |
+ | ------------------------ | ---------------------------- | ---------------------------- |
+ | Executable tool calls | Acting executable tool calls | Acting executable tool calls |
+ | No executable tool calls | Exit the _reply | Reasoning |
+
+ Returns:
+ `tuple[Literal["exit"], Msg]`:
+ If there is no executable tool call and there are awaiting tool
+ calls, which means the agent is waiting for the outside events
+ and should not do anything before that, the next action is to
+ exit the _reply and wait for the outside events.
+ `tuple[Literal["reasoning"], None]`:
+ If there is no executable tool call and no awaiting tool call,
+ which means the agent has nothing to do in this iteration and
+ can continue reasoning for the next step.
+ `tuple[Literal["acting"], None]`:
+ If there are executable tool calls, which means the agent can
+ act by executing the tool calls.
+ """ # noqa: E501
+ last_msg = self._get_last_msg()
+ if last_msg is None:
+ return "reasoning", None
+
+ # In case wrong tool call state, first filter with the results
+ finished_ids = {
+ _.id for _ in last_msg.get_content_blocks("tool_result")
+ }
+ unfinished_tool_calls = [
+ _
+ for _ in last_msg.get_content_blocks("tool_call")
+ if _.id not in finished_ids
+ ]
+
+ # Find if there are executable or awaiting tool calls
+ awaiting_tool_calls: list[ToolCallBlock] = []
+ executable_tool_calls: list[ToolCallBlock] = []
+
+ confirming_names, asking_names = [], []
+ for _ in unfinished_tool_calls:
+ if _.state in [ToolCallState.PENDING, ToolCallState.ALLOWED]:
+ executable_tool_calls.append(_)
+
+ elif _.state == ToolCallState.ASKING:
+ asking_names.append(_.name)
+ awaiting_tool_calls.append(_)
+
+ elif _.state == ToolCallState.SUBMITTED:
+ confirming_names.append(_.name)
+ awaiting_tool_calls.append(_)
+
+ if executable_tool_calls:
+ return "acting", None
+
+ if awaiting_tool_calls:
+ # Prepare the message
+ evt = ["I'm waiting for "]
+ if asking_names:
+ evt += [
+ f"user confirmation for {len(asking_names)} tool calls",
+ ]
+
+ if confirming_names:
+ if evt:
+ evt += [", and "]
+ evt += [
+ f"external execution results for {len(confirming_names)} "
+ f"tool calls",
+ ]
+
+ text = "".join(evt) + "."
+
+ return "exit", AssistantMsg(
+ name=self.name,
+ content=[TextBlock(text=text)],
+ )
+
+ return "reasoning", None
+
+ def _get_executable_tool_calls(self) -> list[ToolCallBlock]:
+ """Get tool calls from the last message that to be executed, which
+ means we should reserve the tool calls that:
+
+ 1. doesn't have results yet, **and**
+ 2. haven't been submitted for external execution (state != "submitted")
+ """
+ last_msg = self._get_last_msg()
+ if last_msg is None:
+ return []
+
+ # The tool results
+ result_ids = {_.id for _ in last_msg.get_content_blocks("tool_result")}
+ # The tool calls that doesn't have results yet
+ tool_calls_wo_results = [
+ _
+ for _ in last_msg.get_content_blocks("tool_call")
+ if _.id not in result_ids
+ ]
+
+ # Filter the ones that are "submitted", which already report the
+ # external execution requirement
+ pending_tool_calls = [
+ _
+ for _ in tool_calls_wo_results
+ if _.state
+ in [
+ ToolCallState.PENDING,
+ ToolCallState.ALLOWED,
+ ]
+ ]
+ return pending_tool_calls
async def _convert_chat_response_to_event(
self,
block_ids: dict,
chunk: ChatResponse,
) -> AsyncGenerator:
- """Convert a ChatResponse chunk into a sequence of agent events."""
+ """Convert a ChatResponse chunk into a sequence of agent events. To
+ keep the identifiers of the content blocks reasonable, the input
+ blocks_ids is used to track the block ids.
+
+ Args:
+ block_ids (`dict`):
+ The block ids used to track the block generation.
+ chunk (`ChatResponse`):
+ The chat response chunk to be converted.
+ """
+
+ # Classify the content blocks into different types
+ text_blocks, thinking_blocks, tool_call_blocks = [], [], []
for block in chunk.content:
if isinstance(block, TextBlock):
- if block_ids["text_block_id"] is None:
- block_ids["text_block_id"] = str(uuid.uuid4())
- yield TextBlockStartEvent(
- reply_id=self.reply_id,
- block_id=block_ids["text_block_id"],
- )
- yield TextBlockDeltaEvent(
- reply_id=self.reply_id,
- block_id=block_ids["text_block_id"],
- delta=block.text,
+ text_blocks.append(block)
+ elif isinstance(block, ThinkingBlock):
+ thinking_blocks.append(block)
+ elif isinstance(block, ToolCallBlock):
+ tool_call_blocks.append(block)
+
+ # Handle the text blocks
+ if text_blocks:
+ # If the current chunk has text blocks but no text block id,
+ # start with a start event
+ if not block_ids.get("text"):
+ block_ids["text"] = uuid.uuid4().hex
+ yield TextBlockStartEvent(
+ reply_id=self.state.reply_id,
+ block_id=block_ids["text"],
)
+ # Go on using the existing text block id to generate delta events
+ yield TextBlockDeltaEvent(
+ reply_id=self.state.reply_id,
+ block_id=block_ids["text"],
+ delta="".join([_.text for _ in text_blocks]),
+ )
- elif isinstance(block, ThinkingBlock):
- if block_ids["thinking_block_id"] is None:
- block_ids["thinking_block_id"] = str(uuid.uuid4())
- yield ThinkingBlockStartEvent(
- reply_id=self.reply_id,
- block_id=block_ids["thinking_block_id"],
- )
- yield ThinkingBlockDeltaEvent(
- reply_id=self.reply_id,
- block_id=block_ids["thinking_block_id"],
- delta=block.thinking,
+ elif block_ids.get("text"):
+ yield TextBlockEndEvent(
+ reply_id=self.state.reply_id,
+ block_id=block_ids["text"],
+ )
+ block_ids["text"] = None
+
+ # Handle the thinking blocks
+ if thinking_blocks:
+ # Generate a new thinking block id and start event
+ if not block_ids.get("thinking"):
+ block_ids["thinking"] = uuid.uuid4().hex
+ yield ThinkingBlockStartEvent(
+ reply_id=self.state.reply_id,
+ block_id=block_ids["thinking"],
)
+ # Generate the thinking delta event with the existing id
+ yield ThinkingBlockDeltaEvent(
+ reply_id=self.state.reply_id,
+ block_id=block_ids["thinking"],
+ delta="".join([_.thinking for _ in thinking_blocks]),
+ )
- elif isinstance(block, ToolCallBlock):
- if block.id not in block_ids["tool_call_ids"]:
- block_ids["tool_call_ids"].append(block.id)
- yield ToolCallStartEvent(
- reply_id=self.reply_id,
- tool_call_id=block.id,
- tool_call_name=block.name,
- )
- yield ToolCallDeltaEvent(
- reply_id=self.reply_id,
- tool_call_id=block.id,
- delta=block.input,
+ elif block_ids.get("thinking"):
+ yield ThinkingBlockEndEvent(
+ reply_id=self.state.reply_id,
+ block_id=block_ids["thinking"],
+ )
+ block_ids["thinking"] = None
+
+ # Handle the tool calls that exist in the current chunk
+ for tool_call in tool_call_blocks:
+ # Not in previous chunk, start with a start event
+ if tool_call.id not in block_ids["tools"]:
+ block_ids["tools"].append(tool_call.id)
+ yield ToolCallStartEvent(
+ reply_id=self.state.reply_id,
+ tool_call_id=tool_call.id,
+ tool_call_name=tool_call.name,
)
+ yield ToolCallDeltaEvent(
+ reply_id=self.state.reply_id,
+ tool_call_id=tool_call.id,
+ delta=tool_call.input,
+ )
- async def _convert_tool_response_to_event(
+ # Handle the tool calls that exist in the previous chunk but not in the
+ # current chunk
+ finished_ids = set(block_ids["tools"]) - set(
+ _.id for _ in tool_call_blocks
+ )
+ for finished_id in finished_ids:
+ yield ToolCallEndEvent(
+ reply_id=self.state.reply_id,
+ tool_call_id=finished_id,
+ )
+ block_ids["tools"].remove(finished_id)
+
+ async def _convert_tool_chunk_to_event(
self,
- tool_call: ToolCallBlock,
- tool_res: object,
+ tool_call_id: str,
+ output_blocks: str | List[TextBlock | DataBlock],
) -> AsyncGenerator:
- """Convert a ToolResponse into a sequence of agent events."""
- # TODO: Properly typed once toolkit is implemented
- for block in tool_res.content: # type: ignore[attr-defined]
+ """Convert a ToolChunk into a sequence of agent events."""
+ if isinstance(output_blocks, str):
+ yield ToolResultTextDeltaEvent(
+ reply_id=self.state.reply_id,
+ tool_call_id=tool_call_id,
+ delta=output_blocks,
+ )
+ return
+
+ for block in output_blocks:
if isinstance(block, TextBlock):
yield ToolResultTextDeltaEvent(
- reply_id=self.reply_id,
- tool_call_id=tool_call.id,
+ reply_id=self.state.reply_id,
+ tool_call_id=tool_call_id,
delta=block.text,
)
elif isinstance(block, DataBlock):
if isinstance(block.source, Base64Source):
- yield ToolResultBinaryDeltaEvent(
- reply_id=self.reply_id,
- tool_call_id=tool_call.id,
+ yield ToolResultDataDeltaEvent(
+ reply_id=self.state.reply_id,
+ tool_call_id=tool_call_id,
media_type=block.source.media_type,
data=block.source.data,
)
elif isinstance(block.source, URLSource):
- yield ToolResultBinaryDeltaEvent(
- reply_id=self.reply_id,
- tool_call_id=tool_call.id,
+ yield ToolResultDataDeltaEvent(
+ reply_id=self.state.reply_id,
+ tool_call_id=tool_call_id,
media_type=block.source.media_type,
- url=block.source.url,
+ url=str(block.source.url),
)
-
- yield ToolResultEndEvent(
- reply_id=self.reply_id,
- tool_call_id=tool_call.id,
- state=tool_res.state, # type: ignore[attr-defined]
- )
-
- def _split_context_for_compression(self) -> tuple[list[Msg], list[Msg]]:
- """Split context into parts to compress and parts to keep recent."""
- # TODO: Implement full splitting logic when compression_config is
- # available
- return [], list(self.context)
-
- async def _compress_memory_if_needed(self) -> None:
- """Compress the agent's memory if the token count exceeds the
- threshold."""
- # TODO: Implement when compression_config is available
diff --git a/src/agentscope/agent/_state.py b/src/agentscope/agent/_state.py
index 889a0fd15..592c38cca 100644
--- a/src/agentscope/agent/_state.py
+++ b/src/agentscope/agent/_state.py
@@ -113,6 +113,10 @@ class ToolContext(BaseModel):
class AgentState(BaseModel):
"""The agent state that should be saved and loaded from storage."""
+ session_id: str = Field(default_factory=lambda: uuid.uuid4().hex)
+ """The session id of the agent. Normally, each session will maintain one
+ independent agent state for each agent."""
+
summary: str | list[TextBlock | DataBlock] = ""
"""The compressed summary of the context, which will be prepended to the
context when feed into the LLM."""
diff --git a/src/agentscope/agent/_utils.py b/src/agentscope/agent/_utils.py
new file mode 100644
index 000000000..2c3889a7e
--- /dev/null
+++ b/src/agentscope/agent/_utils.py
@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""The utility classes used in building the agent class."""
+from dataclasses import dataclass
+from typing import Literal
+
+from ..message import ToolCallBlock
+
+
+@dataclass
+class _ToolCallBatch:
+ """A batch of tool calls that execute either sequentially or
+ concurrently."""
+
+ type: Literal["sequential", "concurrent"]
+ """The batch type"""
+ tool_calls: list[ToolCallBlock]
+ """The list of tool calls in the batch."""
diff --git a/src/agentscope/event/__init__.py b/src/agentscope/event/__init__.py
index 4d045dc8f..d05d143aa 100644
--- a/src/agentscope/event/__init__.py
+++ b/src/agentscope/event/__init__.py
@@ -4,16 +4,16 @@
from ._event import (
EventType,
EventBase,
- RunStartedEvent,
- RunFinishedEvent,
- ModelCallStartedEvent,
- ModelCallEndedEvent,
+ ReplyStartEvent,
+ ReplyEndEvent,
+ ModelCallStartEvent,
+ ModelCallEndEvent,
TextBlockStartEvent,
TextBlockDeltaEvent,
TextBlockEndEvent,
- BinaryBlockStartEvent,
- BinaryBlockDeltaEvent,
- BinaryBlockEndEvent,
+ DataBlockStartEvent,
+ DataBlockDeltaEvent,
+ DataBlockEndEvent,
ThinkingBlockStartEvent,
ThinkingBlockDeltaEvent,
ThinkingBlockEndEvent,
@@ -22,7 +22,7 @@ from ._event import (
ToolCallEndEvent,
ToolResultStartEvent,
ToolResultTextDeltaEvent,
- ToolResultBinaryDeltaEvent,
+ ToolResultDataDeltaEvent,
ToolResultEndEvent,
ExceedMaxItersEvent,
RequireUserConfirmEvent,
@@ -36,16 +36,16 @@ from ._event import (
__all__ = [
"EventType",
"EventBase",
- "RunStartedEvent",
- "RunFinishedEvent",
- "ModelCallStartedEvent",
- "ModelCallEndedEvent",
+ "ReplyStartEvent",
+ "ReplyEndEvent",
+ "ModelCallStartEvent",
+ "ModelCallEndEvent",
"TextBlockStartEvent",
"TextBlockDeltaEvent",
"TextBlockEndEvent",
- "BinaryBlockStartEvent",
- "BinaryBlockDeltaEvent",
- "BinaryBlockEndEvent",
+ "DataBlockStartEvent",
+ "DataBlockDeltaEvent",
+ "DataBlockEndEvent",
"ThinkingBlockStartEvent",
"ThinkingBlockDeltaEvent",
"ThinkingBlockEndEvent",
@@ -54,7 +54,7 @@ __all__ = [
"ToolCallEndEvent",
"ToolResultStartEvent",
"ToolResultTextDeltaEvent",
- "ToolResultBinaryDeltaEvent",
+ "ToolResultDataDeltaEvent",
"ToolResultEndEvent",
"ExceedMaxItersEvent",
"RequireUserConfirmEvent",
diff --git a/src/agentscope/event/_event.py b/src/agentscope/event/_event.py
index f9b3ca943..c53850611 100644
--- a/src/agentscope/event/_event.py
+++ b/src/agentscope/event/_event.py
@@ -2,30 +2,31 @@
"""Event types for agent execution."""
import uuid
from datetime import datetime
-from enum import Enum
+from enum import StrEnum
from typing import Literal, List, TypeAlias
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, ConfigDict
-from ..message import ToolCallBlock, ToolResultBlock
+from ..message import ToolCallBlock, ToolResultBlock, ToolResultState
+from ..tool import PermissionRule
-class EventType(str, Enum):
+class EventType(StrEnum):
"""Event type enumeration."""
- RUN_STARTED = "RUN_STARTED"
- RUN_FINISHED = "RUN_FINISHED"
+ REPLY_START = "REPLY_START"
+ REPLY_END = "REPLY_END"
- MODEL_CALL_STARTED = "MODEL_CALL_STARTED"
- MODEL_CALL_ENDED = "MODEL_CALL_ENDED"
+ MODEL_CALL_START = "MODEL_CALL_START"
+ MODEL_CALL_END = "MODEL_CALL_END"
TEXT_BLOCK_START = "TEXT_BLOCK_START"
TEXT_BLOCK_DELTA = "TEXT_BLOCK_DELTA"
TEXT_BLOCK_END = "TEXT_BLOCK_END"
- BINARY_BLOCK_START = "BINARY_BLOCK_START"
- BINARY_BLOCK_DELTA = "BINARY_BLOCK_DELTA"
- BINARY_BLOCK_END = "BINARY_BLOCK_END"
+ DATA_BLOCK_START = "DATA_BLOCK_START"
+ DATA_BLOCK_DELTA = "DATA_BLOCK_DELTA"
+ DATA_BLOCK_END = "DATA_BLOCK_END"
THINKING_BLOCK_START = "THINKING_BLOCK_START"
THINKING_BLOCK_DELTA = "THINKING_BLOCK_DELTA"
@@ -37,7 +38,7 @@ class EventType(str, Enum):
TOOL_RESULT_START = "TOOL_RESULT_START"
TOOL_RESULT_TEXT_DELTA = "TOOL_RESULT_TEXT_DELTA"
- TOOL_RESULT_BINARY_DELTA = "TOOL_RESULT_BINARY_DELTA"
+ TOOL_RESULT_DATA_DELTA = "TOOL_RESULT_DATA_DELTA"
TOOL_RESULT_END = "TOOL_RESULT_END"
EXCEED_MAX_ITERS = "EXCEED_MAX_ITERS"
@@ -52,42 +53,44 @@ class EventType(str, Enum):
class EventBase(BaseModel):
"""Base event class."""
+ model_config = ConfigDict(use_enum_values=True)
+
id: str = Field(default_factory=lambda: uuid.uuid4().hex)
"""Unique event identifier."""
- created_at: str = Field(default_factory=datetime.now().isoformat)
+ created_at: str = Field(default_factory=lambda: datetime.now().isoformat())
"""ISO 8601 timestamp of when the event was created."""
-class RunStartedEvent(EventBase):
- """Run started event."""
+class ReplyStartEvent(EventBase):
+ """Reply start event."""
- type: Literal[EventType.RUN_STARTED] = EventType.RUN_STARTED
+ type: Literal[EventType.REPLY_START] = EventType.REPLY_START
"""Event type."""
session_id: str
- """ID of the session this run belongs to."""
+ """ID of the session this reply belongs to."""
reply_id: str
- """ID of the reply message produced by this run."""
+ """ID of the reply message produced by this reply."""
name: str
"""Name of the agent."""
role: Literal["user", "assistant", "system"] = "assistant"
"""Role of the agent."""
-class RunFinishedEvent(EventBase):
- """Run finished event."""
+class ReplyEndEvent(EventBase):
+ """Reply end event."""
- type: Literal[EventType.RUN_FINISHED] = EventType.RUN_FINISHED
+ type: Literal[EventType.REPLY_END] = EventType.REPLY_END
"""Event type."""
session_id: str
- """ID of the session this run belongs to."""
+ """ID of the session this reply belongs to."""
reply_id: str
- """ID of the reply message produced by this run."""
+ """ID of the reply message produced by this reply."""
-class ModelCallStartedEvent(EventBase):
- """Model call started event."""
+class ModelCallStartEvent(EventBase):
+ """Model call start event."""
- type: Literal[EventType.MODEL_CALL_STARTED] = EventType.MODEL_CALL_STARTED
+ type: Literal[EventType.MODEL_CALL_START] = EventType.MODEL_CALL_START
"""Event type."""
reply_id: str
"""ID of the reply message this model call belongs to."""
@@ -95,10 +98,10 @@ class ModelCallStartedEvent(EventBase):
"""Name of the model being called."""
-class ModelCallEndedEvent(EventBase):
- """Model call ended event."""
+class ModelCallEndEvent(EventBase):
+ """Model call end event."""
- type: Literal[EventType.MODEL_CALL_ENDED] = EventType.MODEL_CALL_ENDED
+ type: Literal[EventType.MODEL_CALL_END] = EventType.MODEL_CALL_END
"""Event type."""
reply_id: str
"""ID of the reply message this model call belongs to."""
@@ -143,43 +146,43 @@ class TextBlockEndEvent(EventBase):
"""Unique identifier of the text block."""
-class BinaryBlockStartEvent(EventBase):
- """Binary block start event."""
+class DataBlockStartEvent(EventBase):
+ """Data block start event."""
- type: Literal[EventType.BINARY_BLOCK_START] = EventType.BINARY_BLOCK_START
+ type: Literal[EventType.DATA_BLOCK_START] = EventType.DATA_BLOCK_START
"""Event type."""
reply_id: str
"""ID of the reply message this block belongs to."""
block_id: str
- """Unique identifier of the binary block."""
+ """Unique identifier of the data block."""
media_type: str
- """MIME type of the binary content (e.g. "image/png")."""
+ """MIME type of the data content (e.g. "image/png")."""
-class BinaryBlockDeltaEvent(EventBase):
- """Binary block delta event."""
+class DataBlockDeltaEvent(EventBase):
+ """Data block delta event."""
- type: Literal[EventType.BINARY_BLOCK_DELTA] = EventType.BINARY_BLOCK_DELTA
+ type: Literal[EventType.DATA_BLOCK_DELTA] = EventType.DATA_BLOCK_DELTA
"""Event type."""
reply_id: str
"""ID of the reply message this block belongs to."""
block_id: str
- """Unique identifier of the binary block."""
+ """Unique identifier of the data block."""
data: str
- """Incremental base64-encoded binary data."""
+ """Incremental base64-encoded data."""
media_type: str
- """MIME type of the binary content."""
+ """MIME type of the data content."""
-class BinaryBlockEndEvent(EventBase):
- """Binary block end event."""
+class DataBlockEndEvent(EventBase):
+ """Data block end event."""
- type: Literal[EventType.BINARY_BLOCK_END] = EventType.BINARY_BLOCK_END
+ type: Literal[EventType.DATA_BLOCK_END] = EventType.DATA_BLOCK_END
"""Event type."""
reply_id: str
"""ID of the reply message this block belongs to."""
block_id: str
- """Unique identifier of the binary block."""
+ """Unique identifier of the data block."""
class ThinkingBlockStartEvent(EventBase):
@@ -286,12 +289,12 @@ class ToolResultTextDeltaEvent(EventBase):
"""Incremental text content of the tool result."""
-class ToolResultBinaryDeltaEvent(EventBase):
- """Tool result binary delta event."""
+class ToolResultDataDeltaEvent(EventBase):
+ """Tool result data delta event."""
type: Literal[
- EventType.TOOL_RESULT_BINARY_DELTA
- ] = EventType.TOOL_RESULT_BINARY_DELTA
+ EventType.TOOL_RESULT_DATA_DELTA
+ ] = EventType.TOOL_RESULT_DATA_DELTA
"""Event type."""
reply_id: str
"""ID of the reply message this tool result belongs to."""
@@ -308,25 +311,25 @@ class ToolResultBinaryDeltaEvent(EventBase):
class ToolResultEndEvent(EventBase):
"""Tool result end event."""
+ model_config = ConfigDict(use_enum_values=True)
+
type: Literal[EventType.TOOL_RESULT_END] = EventType.TOOL_RESULT_END
"""Event type."""
reply_id: str
"""ID of the reply message this tool result belongs to."""
tool_call_id: str
"""ID of the corresponding tool call."""
- state: Literal["success", "error", "interrupted", "running"]
+ state: ToolResultState
"""Final execution state of the tool call."""
class ExceedMaxItersEvent(EventBase):
- """Exceed max iterations event."""
+ """Exceeded max iterations event."""
type: Literal[EventType.EXCEED_MAX_ITERS] = EventType.EXCEED_MAX_ITERS
"""Event type."""
reply_id: str
"""ID of the reply message associated with this run."""
- agent_id: str
- """ID of the agent that exceeded the iteration limit."""
name: str
"""Name of the agent."""
@@ -364,6 +367,11 @@ class ConfirmResult(BaseModel):
"""Whether the user confirmed the tool call."""
tool_call: ToolCallBlock
"""The tool call that was confirmed or rejected."""
+ rules: list[PermissionRule] | None = None
+ """The allowed permission rules for this tool call. This field is only
+ applicable when ``confirmed`` is True. In case user modification is
+ needed, complete permission rules are used here instead of references to
+ the suggested rules in ``RequireUserConfirmEvent``."""
class UserConfirmResultEvent(EventBase):
@@ -393,19 +401,19 @@ class ExternalExecutionResultEvent(EventBase):
AgentEvent: TypeAlias = (
- RunStartedEvent
- | RunFinishedEvent
+ ReplyStartEvent
+ | ReplyEndEvent
| ExceedMaxItersEvent
| RequireUserConfirmEvent
| RequireExternalExecutionEvent
- | ModelCallStartedEvent
- | ModelCallEndedEvent
+ | ModelCallStartEvent
+ | ModelCallEndEvent
| TextBlockStartEvent
| TextBlockDeltaEvent
| TextBlockEndEvent
- | BinaryBlockStartEvent
- | BinaryBlockDeltaEvent
- | BinaryBlockEndEvent
+ | DataBlockStartEvent
+ | DataBlockDeltaEvent
+ | DataBlockEndEvent
| ThinkingBlockStartEvent
| ThinkingBlockDeltaEvent
| ThinkingBlockEndEvent
@@ -414,7 +422,7 @@ AgentEvent: TypeAlias = (
| ToolCallEndEvent
| ToolResultStartEvent
| ToolResultTextDeltaEvent
- | ToolResultBinaryDeltaEvent
+ | ToolResultDataDeltaEvent
| ToolResultEndEvent
| UserConfirmResultEvent
| ExternalExecutionResultEvent
diff --git a/src/agentscope/exception/__init__.py b/src/agentscope/exception/__init__.py
index 9a9edc47d..83be2bf25 100644
--- a/src/agentscope/exception/__init__.py
+++ b/src/agentscope/exception/__init__.py
@@ -2,19 +2,21 @@
"""The exception module in agentscope."""
from ._base import (
- AgentOrientedExceptionBase,
+ AgentOrientedException,
DeveloperOrientedException,
)
from ._tool import (
ToolInterruptedError,
ToolNotFoundError,
- ToolInvalidArgumentsError,
+ ToolJSONDecodeError,
+ ToolGroupInactiveError,
)
__all__ = [
- "AgentOrientedExceptionBase",
+ "AgentOrientedException",
"DeveloperOrientedException",
"ToolInterruptedError",
"ToolNotFoundError",
- "ToolInvalidArgumentsError",
+ "ToolJSONDecodeError",
+ "ToolGroupInactiveError",
]
diff --git a/src/agentscope/exception/_base.py b/src/agentscope/exception/_base.py
index d14eaad7b..a96a945c3 100644
--- a/src/agentscope/exception/_base.py
+++ b/src/agentscope/exception/_base.py
@@ -2,7 +2,7 @@
"""The base exception class in agentscope."""
-class AgentOrientedExceptionBase(Exception):
+class AgentOrientedException(Exception):
"""The base class for all agent-oriented exceptions. These exceptions are
expect to the captured and exposed to the agent during runtime, so that
agents can handle the error appropriately during the runtime.
diff --git a/src/agentscope/exception/_tool.py b/src/agentscope/exception/_tool.py
index 1ea3b2965..730b9be4a 100644
--- a/src/agentscope/exception/_tool.py
+++ b/src/agentscope/exception/_tool.py
@@ -1,16 +1,20 @@
# -*- coding: utf-8 -*-
"""The tool-related exceptions in agentscope."""
-from ._base import AgentOrientedExceptionBase
+from ._base import AgentOrientedException
-class ToolNotFoundError(AgentOrientedExceptionBase):
+class ToolNotFoundError(AgentOrientedException):
"""Exception raised when a tool was not found."""
-class ToolInterruptedError(AgentOrientedExceptionBase):
+class ToolInterruptedError(AgentOrientedException):
"""Exception raised when a tool calling was interrupted by the user."""
-class ToolInvalidArgumentsError(AgentOrientedExceptionBase):
- """Exception raised when the arguments passed to a tool are invalid."""
+class ToolJSONDecodeError(AgentOrientedException):
+ """Exception raised when tool arguments fail JSON decoding or repair."""
+
+
+class ToolGroupInactiveError(AgentOrientedException):
+ """Exception raised when a tool group is inactive."""
diff --git a/src/agentscope/message/__init__.py b/src/agentscope/message/__init__.py
index 178e08417..f27d4d2e5 100644
--- a/src/agentscope/message/__init__.py
+++ b/src/agentscope/message/__init__.py
@@ -8,7 +8,9 @@ from ._block import (
ThinkingBlock,
HintBlock,
ToolCallBlock,
+ ToolCallState,
ToolResultBlock,
+ ToolResultState,
DataBlock,
Base64Source,
URLSource,
@@ -21,7 +23,9 @@ __all__ = [
"ThinkingBlock",
"HintBlock",
"ToolCallBlock",
+ "ToolCallState",
"ToolResultBlock",
+ "ToolResultState",
"DataBlock",
"Base64Source",
"URLSource",
diff --git a/src/agentscope/message/_base.py b/src/agentscope/message/_base.py
index 8697bca12..4d1e73b66 100644
--- a/src/agentscope/message/_base.py
+++ b/src/agentscope/message/_base.py
@@ -1,9 +1,9 @@
# -*- coding: utf-8 -*-
"""The message class in agentscope."""
+import uuid
from datetime import datetime
from typing import Literal, List, overload, Sequence, Self
-import shortuuid
from pydantic import BaseModel, Field, model_validator
from ._block import (
@@ -52,11 +52,11 @@ class Msg(BaseModel):
"""The message content, a string or a list of content blocks."""
role: Literal["user", "assistant", "system"]
"""The role of the sender."""
- id: str = Field(default_factory=shortuuid.uuid)
+ id: str = Field(default_factory=lambda: uuid.uuid4().hex)
"""The message identifier."""
metadata: dict = Field(default_factory=dict)
"""The metadata of the message"""
- created_at: str = Field(default_factory=datetime.now().isoformat)
+ created_at: str = Field(default_factory=lambda: datetime.now().isoformat())
"""The creation time of the message"""
@model_validator(mode="after")
@@ -73,16 +73,31 @@ class Msg(BaseModel):
def has_content_blocks(
self,
- block_type: ContentBlockTypes | None = None,
+ block_type: ContentBlockTypes | list[ContentBlockTypes] | None = None,
) -> bool:
"""Check if the message has content blocks of the given type.
Args:
- block_type (ContentBlockTypes | None, defaults to None):
- The type of the block to be checked. If `None`, it will
- check if there are any content blocks.
+ block_type (`ContentBlockTypes | list[ContentBlockTypes] | None`, \
+ optional):
+ The type of the block to be checked. If `None`, all blocks will
+ be checked. If a list is provided, it checks if there are
+ blocks of any types in the list.
+
+ Returns:
+ `bool`:
+ `True` if there are content blocks of the given type, `False`
+ otherwise.
"""
- return len(self.get_content_blocks(block_type)) > 0
+ blocks = self.get_content_blocks()
+ if block_type is None:
+ return len(blocks) > 0
+
+ typs = [block_type] if isinstance(block_type, str) else block_type
+ for _ in list(self.get_content_blocks()):
+ if _.type in typs:
+ return True
+ return False
def get_text_content(self, separator: str = "\n") -> str | None:
"""Get the pure text blocks from the message content.
@@ -231,6 +246,7 @@ def AssistantMsg(
content: str | list[ContentBlock],
metadata: dict | None = None,
created_at: str | None = None,
+ id: str | None = None, # pylint: disable=redefined-builtin
) -> Msg:
"""Create an assistant message with role "assistant".
@@ -244,6 +260,8 @@ def AssistantMsg(
The metadata of the message. Defaults to `None`.
created_at (`str | None`, optional):
The creation time of the message in ISO format. Defaults to `None`.
+ id (`str | None`, optional):
+ The unique identifier of the message.
Returns:
`Msg`:
@@ -255,6 +273,7 @@ def AssistantMsg(
role="assistant",
metadata=metadata or {},
created_at=created_at or datetime.now().isoformat(),
+ id=id or uuid.uuid4().hex,
)
diff --git a/src/agentscope/message/_block.py b/src/agentscope/message/_block.py
index 5ffe5e085..56fbd7d0b 100644
--- a/src/agentscope/message/_block.py
+++ b/src/agentscope/message/_block.py
@@ -1,8 +1,9 @@
# -*- coding: utf-8 -*-
"""The content blocks of messages."""
import uuid
+from enum import StrEnum
from typing import Literal, List, TypeAlias
-from pydantic import BaseModel, Field, AnyUrl, field_serializer
+from pydantic import BaseModel, Field, AnyUrl, field_serializer, ConfigDict
class TextBlock(BaseModel):
@@ -82,9 +83,21 @@ class DataBlock(BaseModel):
"""The name of the data block, which is optional."""
+class ToolCallState(StrEnum):
+ """The state of the tool call."""
+
+ PENDING = "pending"
+ ASKING = "asking"
+ ALLOWED = "allowed"
+ SUBMITTED = "submitted"
+ FINISHED = "finished"
+
+
class ToolCallBlock(BaseModel):
"""The tool call block."""
+ model_config = ConfigDict(use_enum_values=True)
+
type: Literal["tool_call"] = "tool_call"
"""The type of the tool call block, which is always 'tool_call'."""
id: str
@@ -93,13 +106,48 @@ class ToolCallBlock(BaseModel):
"""The name of the tool to be called."""
input: str
"""The raw JSON string input of the tool, accumulated during streaming."""
- await_user_confirmation: bool = False
- """Whether to await user confirmation before executing the tool."""
+ state: ToolCallState = ToolCallState.PENDING
+ """The tool call state
+ - 'pending': the initial state when the tool call hasn't been processed
+ by the permission system
+ - 'asking': the tool call is asking and waiting for user confirmation
+ - 'allowed': allowed by the permission system/user and waits for execution
+ - 'submitted': the tool call has been submitted for external execution
+ and is waiting for results event
+
+ Transitions
+ -----------
+ pending
+ ├── permission DENY / input validation failed ──► finished
+ ├── permission ASK ──────────────────────────── ► asking
+ │ ├── user denied ───────────────────────► finished
+ │ └── user approved ─────────────────────► allowed
+ └── permission ALLOW ────────────────────────── ► allowed
+
+ allowed
+ ├── local tool ── (execute) ─────────────────► finished
+ └── external tool ──────────────────────────── ► submitted
+
+ submitted
+ └── ExternalExecutionResultEvent received ─────► finished
+ """
+
+
+class ToolResultState(StrEnum):
+ """The tool result state."""
+
+ SUCCESS = "success"
+ ERROR = "error"
+ INTERRUPTED = "interrupted"
+ DENIED = "denied"
+ RUNNING = "running"
class ToolResultBlock(BaseModel):
"""The tool result block."""
+ model_config = ConfigDict(use_enum_values=True)
+
type: Literal["tool_result"] = "tool_result"
"""The type of the tool result block, which is always 'tool_result'."""
id: str
@@ -109,7 +157,7 @@ class ToolResultBlock(BaseModel):
output: str | List[TextBlock | DataBlock]
"""The output of the tool, which can be a raw string of a list of
text and multimodal blocks."""
- state: Literal["success", "error", "interrupted", "running"]
+ state: ToolResultState = ToolResultState.RUNNING
"""The execution state of the tool."""
diff --git a/src/agentscope/model/__init__.py b/src/agentscope/model/__init__.py
index 221272767..62713a1cc 100644
--- a/src/agentscope/model/__init__.py
+++ b/src/agentscope/model/__init__.py
@@ -1,5 +1,6 @@
# -*- coding: utf-8 -*-
"""The model module."""
+from typing import Any, Type
from ._model_base import ChatModelBase
from ._model_response import ChatResponse
@@ -11,6 +12,56 @@ from ._gemini_model import GeminiChatModel
from ._trinity_model import TrinityChatModel
from ._model_usage import ChatUsage
+# Built-in model classes (internal use only)
+_BUILTIN_MODELS: list[Type[ChatModelBase]] = [
+ DashScopeChatModel,
+ OpenAIChatModel,
+ AnthropicChatModel,
+ OllamaChatModel,
+ GeminiChatModel,
+]
+
+
+def _deserialize_model(
+ data: dict[str, Any],
+ custom_classes: list[Type[ChatModelBase]] | None = None,
+ context: dict[str, Any] | None = None,
+) -> ChatModelBase:
+ """Deserialize a chat model from a dictionary.
+
+ Args:
+ data: Dictionary containing serialized model data with 'type' field.
+ custom_classes: Optional list of custom model classes to support.
+ context: Optional context dict to pass to nested validators.
+
+ Returns:
+ Deserialized model instance.
+
+ Raises:
+ ValueError: If 'type' field is missing or unknown.
+ """
+ if "type" not in data:
+ raise ValueError("Model data must contain 'type' field")
+
+ type_value = data["type"]
+
+ all_classes = _BUILTIN_MODELS + (custom_classes or [])
+ registry = {
+ cls.model_fields["type"].default: cls
+ for cls in all_classes
+ if "type" in cls.model_fields
+ and cls.model_fields["type"].default is not None
+ }
+
+ if type_value not in registry:
+ raise ValueError(
+ f"Unknown model type '{type_value}'. "
+ f"Available types: {list(registry.keys())}",
+ )
+
+ return registry[type_value].model_validate(data, context=context)
+
+
__all__ = [
"ChatUsage",
"ChatModelBase",
diff --git a/src/agentscope/model/_model_response.py b/src/agentscope/model/_model_response.py
index 985091b55..cddd3351d 100644
--- a/src/agentscope/model/_model_response.py
+++ b/src/agentscope/model/_model_response.py
@@ -31,7 +31,7 @@ class ChatResponse(DictMixin):
id: str = field(default_factory=lambda: uuid.uuid4().hex)
"""The unique identifier formatter """
- created_at: str = field(default_factory=datetime.now().isoformat)
+ created_at: str = field(default_factory=lambda: datetime.now().isoformat())
"""When the response was created"""
type: Literal["chat"] = field(default_factory=lambda: "chat")
diff --git a/src/agentscope/tool/__init__.py b/src/agentscope/tool/__init__.py
index aa5a3f348..f567a559c 100644
--- a/src/agentscope/tool/__init__.py
+++ b/src/agentscope/tool/__init__.py
@@ -30,8 +30,15 @@ from ._builtin import (
)
__all__ = [
+ # Basic tool related types and functions
+ "ToolChoice",
+ "Function",
+ "ToolBase",
+ "MCPTool",
"Toolkit",
+ "ToolChunk",
"ToolResponse",
+ # Permission related types and functions
"PermissionContext",
"AdditionalWorkingDirectory",
"PermissionDecision",
@@ -39,11 +46,7 @@ __all__ = [
"PermissionRule",
"PermissionMode",
"PermissionBehavior",
- "ToolChunk",
- "ToolBase",
- "MCPTool",
- "ToolChoice",
- "Function",
+ # Builtin tools
"ResetTools",
"Bash",
"Edit",
@@ -51,6 +54,7 @@ __all__ = [
"Grep",
"Read",
"Write",
+ # Skill related types and functions
"Skill",
"SkillLoaderBase",
"LocalSkillLoader",
diff --git a/src/agentscope/tool/_adapters.py b/src/agentscope/tool/_adapters.py
index 3ecda7842..7f26b87b8 100644
--- a/src/agentscope/tool/_adapters.py
+++ b/src/agentscope/tool/_adapters.py
@@ -58,6 +58,7 @@ class _FunctionTool(ToolBase):
self.input_schema = _extract_input_schema(func)
self.is_concurrency_safe = is_concurrency_safe
self.is_read_only = is_read_only
+ self.is_external_tool = False
self.is_mcp = False
self._func = func
@@ -146,7 +147,8 @@ class MCPTool(ToolBase):
"required": tool.inputSchema.get("required", []),
}
- self.is_concurrency_safe = True
+ self.is_concurrency_safe = False
+ self.is_external_tool = False
# Extract is_read_only from MCP tool annotations
self.is_read_only = False
diff --git a/src/agentscope/tool/_base.py b/src/agentscope/tool/_base.py
index 312af22ab..acde293ef 100644
--- a/src/agentscope/tool/_base.py
+++ b/src/agentscope/tool/_base.py
@@ -30,6 +30,9 @@ class ToolBase(ABC):
is_read_only: bool
"""If this tool is read-only, which will be used in the permission
checking."""
+ is_external_tool: bool
+ """If this tool is an external tool, which doesn't need to implement the
+ __call__ method and the agent will yield the external tool call event."""
is_mcp: bool
"""If this tool is an MCP tool, which will be used in the permission"""
mcp_name: str | None = None
@@ -172,10 +175,18 @@ class ToolBase(ABC):
return False
- @abstractmethod
async def __call__(
self,
*args: Any,
**kwargs: Any,
) -> ToolChunk | AsyncGenerator[ToolChunk, None]:
"""Invoke the tool with the given arguments."""
+ if not self.is_external_tool:
+ raise NotImplementedError(
+ f"{self.__class__.__name__} does not implement __call__",
+ )
+
+ raise RuntimeError(
+ f"{self.__class__.__name__} is an external tool and should not "
+ f"be called directly",
+ )
diff --git a/src/agentscope/tool/_builtin/_bash.py b/src/agentscope/tool/_builtin/_bash.py
index 38c84c512..b975ead29 100644
--- a/src/agentscope/tool/_builtin/_bash.py
+++ b/src/agentscope/tool/_builtin/_bash.py
@@ -127,6 +127,7 @@ easier to review tool calls and give permission.
is_mcp: bool = False
is_read_only: bool = False
is_concurrency_safe: bool = False
+ is_external_tool: bool = False
def __init__(
self,
diff --git a/src/agentscope/tool/_builtin/_edit.py b/src/agentscope/tool/_builtin/_edit.py
index 0ff2ce30d..5bef1ddb9 100644
--- a/src/agentscope/tool/_builtin/_edit.py
+++ b/src/agentscope/tool/_builtin/_edit.py
@@ -82,6 +82,7 @@ Usage:
is_mcp: bool = False
is_read_only: bool = False
is_concurrency_safe: bool = False
+ is_external_tool: bool = False
def __init__(
self,
diff --git a/src/agentscope/tool/_builtin/_glob.py b/src/agentscope/tool/_builtin/_glob.py
index 8ed13c3bc..9dd98d97c 100644
--- a/src/agentscope/tool/_builtin/_glob.py
+++ b/src/agentscope/tool/_builtin/_glob.py
@@ -52,6 +52,7 @@ codebase.""" # ignore: E501
is_mcp: bool = False
is_read_only: bool = True
is_concurrency_safe: bool = True
+ is_external_tool: bool = False
def __init__(self) -> None:
"""Initialize the glob tool."""
diff --git a/src/agentscope/tool/_builtin/_grep.py b/src/agentscope/tool/_builtin/_grep.py
index 564226c80..1566b2696 100644
--- a/src/agentscope/tool/_builtin/_grep.py
+++ b/src/agentscope/tool/_builtin/_grep.py
@@ -154,6 +154,7 @@ class Grep(ToolBase):
is_mcp: bool = False
is_read_only: bool = True
is_concurrency_safe: bool = True
+ is_external_tool: bool = False
def __init__(self) -> None:
"""Initialize the grep tool."""
diff --git a/src/agentscope/tool/_builtin/_meta.py b/src/agentscope/tool/_builtin/_meta.py
index fb39cc042..893762ac2 100644
--- a/src/agentscope/tool/_builtin/_meta.py
+++ b/src/agentscope/tool/_builtin/_meta.py
@@ -47,6 +47,7 @@ class ResetTools(ToolBase):
is_mcp: bool = False
is_read_only: bool = False
is_concurrency_safe: bool = True
+ is_external_tool: bool = False
def __init__(
self,
diff --git a/src/agentscope/tool/_builtin/_read.py b/src/agentscope/tool/_builtin/_read.py
index 243ec6440..75aa549a5 100644
--- a/src/agentscope/tool/_builtin/_read.py
+++ b/src/agentscope/tool/_builtin/_read.py
@@ -70,6 +70,7 @@ Usage:
is_mcp: bool = False
is_read_only: bool = True
is_concurrency_safe: bool = True
+ is_external_tool: bool = False
def __init__(
self,
diff --git a/src/agentscope/tool/_builtin/_skill.py b/src/agentscope/tool/_builtin/_skill.py
index 2da14bf80..d10d0dae8 100644
--- a/src/agentscope/tool/_builtin/_skill.py
+++ b/src/agentscope/tool/_builtin/_skill.py
@@ -42,6 +42,9 @@ class SkillViewer(ToolBase):
is_concurrency_safe: bool = True
"""The skill viewer is concurrency safe."""
+ is_external_tool: bool = False
+ """The skill viewer is not an external tool."""
+
is_read_only: bool = True
"""The skill viewer is read-only."""
diff --git a/src/agentscope/tool/_builtin/_write.py b/src/agentscope/tool/_builtin/_write.py
index 6cf5b5396..45aff0ca8 100644
--- a/src/agentscope/tool/_builtin/_write.py
+++ b/src/agentscope/tool/_builtin/_write.py
@@ -60,6 +60,7 @@ Usage:
is_mcp: bool = False
is_read_only: bool = False
is_concurrency_safe: bool = False
+ is_external_tool: bool = False
def __init__(
self,
diff --git a/src/agentscope/tool/_permission/_engine.py b/src/agentscope/tool/_permission/_engine.py
index 2b4aa2008..56f22ecff 100644
--- a/src/agentscope/tool/_permission/_engine.py
+++ b/src/agentscope/tool/_permission/_engine.py
@@ -1,13 +1,11 @@
# -*- coding: utf-8 -*-
"""The permission engine for checking and enforcing permission rules."""
-import json
from typing import Any, List, TYPE_CHECKING
from ._context import PermissionContext
from ._rule import PermissionRule
from ._decision import PermissionDecision, PermissionBehavior
from ._types import PermissionMode
-from ...message import ToolCallBlock
if TYPE_CHECKING:
from .._base import ToolBase
@@ -82,8 +80,8 @@ class PermissionEngine:
async def check_permission(
self,
- tool_call: ToolCallBlock,
tool: ToolBase,
+ tool_input: dict[str, Any],
) -> PermissionDecision:
"""Check permission for a tool execution request.
@@ -101,38 +99,36 @@ class PermissionEngine:
6. Default behavior (ask)
Args:
- tool_call (`ToolCallBlock`):
- The tool call block containing tool name and input
tool (`ToolBase`):
The tool instance being called (used for tool-specific checks)
+ tool_input (`dict`):
+ The tool input data (used for rule matching and tool-specific
+ checks)
Returns:
`PermissionDecision`:
Decision indicating whether to allow, deny, or ask
"""
- tool_name = tool_call.name
- input_data = json.loads(tool_call.input)
-
# 1. Check tool-level deny rules (highest priority)
- deny_decision = self._check_deny_rules(tool, input_data)
+ deny_decision = self._check_deny_rules(tool, tool_input)
if deny_decision:
return deny_decision
# 2. Check tool-level ask rules
- ask_decision = self._check_ask_rules(tool, input_data)
+ ask_decision = self._check_ask_rules(tool, tool_input)
if ask_decision:
# Generate suggestions for ASK decisions
ask_decision.suggested_rules = self._generate_suggestions(
- tool_call,
tool,
+ tool_input,
)
return ask_decision
# 3. Tool-specific permission checks (dangerous paths, etc.)
# These are bypass-immune
tool_decision = await self._tool_check_permissions(
- input_data,
+ tool_input,
tool,
)
@@ -155,13 +151,13 @@ class PermissionEngine:
and "safety" in tool_decision.decision_reason.lower()
):
tool_decision.suggested_rules = self._generate_suggestions(
- tool_call,
tool,
+ tool_input,
)
return tool_decision
# 4. Check allow rules
- allow_decision = self._check_allow_rules(tool, input_data)
+ allow_decision = self._check_allow_rules(tool, tool_input)
if allow_decision:
return allow_decision
@@ -169,15 +165,15 @@ class PermissionEngine:
if self.context.mode == PermissionMode.BYPASS:
return PermissionDecision(
behavior=PermissionBehavior.ALLOW,
- message=f"Permission granted for {tool_name} (bypass mode)",
+ message=f"Permission granted for {tool.name} (bypass mode)",
decision_reason="Bypass mode allows all operations",
)
# 7. Default behavior (passthrough → ask)
- default_decision = self._default_decision_ask(tool_name)
+ default_decision = self._default_decision_ask(tool.name)
default_decision.suggested_rules = self._generate_suggestions(
- tool_call,
tool,
+ tool_input,
)
return default_decision
@@ -422,8 +418,8 @@ class PermissionEngine:
def _generate_suggestions(
self,
- tool_call: ToolCallBlock,
tool: ToolBase,
+ tool_input: dict[str, Any],
) -> List[PermissionRule]:
"""Generate suggested permission rules from a tool call.
@@ -437,18 +433,17 @@ class PermissionEngine:
- For other tools: Generate exact match rule
Args:
- tool_call (`ToolCallBlock`):
- The tool call block containing name and parameters
tool (`ToolBase`):
The tool instance being called (used for tool-specific
suggestions)
+ tool_input (`dict[str, Any]`):
+ The tool input data (used for generating suggestions)
Returns:
`List[PermissionRule]`:
List of suggested permission rules (usually 1, max 5 for
compound commands)
"""
- input_data = json.loads(tool_call.input)
# Try to use tool's generate_suggestions method if available
- return tool.generate_suggestions(input_data)
+ return tool.generate_suggestions(tool_input)
diff --git a/src/agentscope/tool/_response.py b/src/agentscope/tool/_response.py
index 5ecb8bcf4..786f8833d 100644
--- a/src/agentscope/tool/_response.py
+++ b/src/agentscope/tool/_response.py
@@ -5,7 +5,7 @@ from typing import List, Literal, Self
from pydantic import BaseModel, Field
-from ..message import DataBlock, TextBlock, Base64Source
+from ..message import DataBlock, TextBlock, Base64Source, ToolResultState
class ToolChunk(BaseModel):
@@ -16,7 +16,7 @@ class ToolChunk(BaseModel):
instance should have the same block id, so that the agent can group them
together."""
- state: Literal["error", "interrupted", "running"] = "running"
+ state: ToolResultState = ToolResultState.RUNNING
"""The execution state of the tool chunk."""
is_last: bool = True
@@ -37,7 +37,12 @@ class ToolResponse(BaseModel):
content: List[TextBlock | DataBlock] = Field(default_factory=list)
"""The completed tool result data blocks."""
- state: Literal["error", "interrupted", "finished"] = "finished"
+ state: Literal[
+ ToolResultState.ERROR,
+ ToolResultState.DENIED,
+ ToolResultState.INTERRUPTED,
+ ToolResultState.SUCCESS,
+ ] = ToolResultState.SUCCESS
"""The execution state of the tool response."""
metadata: dict = Field(default_factory=dict)
@@ -106,13 +111,14 @@ class ToolResponse(BaseModel):
current_ids_to_index[chunk_block.id] = len(self.content) - 1
# Update id, state and metadata
- # TODO: what's the relationship between the chunk id and response id?
# Only reserve the failure state and keep the previous state if not
# worse.
- if chunk.state == "error":
- self.state = "error"
+ if chunk.state == ToolResultState.ERROR:
+ self.state = ToolResultState.ERROR
elif chunk.state == "interrupted":
- self.state = "interrupted"
+ self.state = ToolResultState.INTERRUPTED
+ elif chunk.state == ToolResultState.DENIED:
+ self.state = ToolResultState.DENIED
self.metadata.update(chunk.metadata)
diff --git a/src/agentscope/tool/_toolkit.py b/src/agentscope/tool/_toolkit.py
index 69fafc1b3..f593235d3 100644
--- a/src/agentscope/tool/_toolkit.py
+++ b/src/agentscope/tool/_toolkit.py
@@ -31,7 +31,11 @@ from ._response import ToolResponse, ToolChunk
from ._skill import SkillLoaderBase, LocalSkillLoader
from ._types import ToolGroup, Skill, RegisteredTool
from .._utils._common import _json_loads_with_repair
-from ..exception import DeveloperOrientedException
+from ..exception import (
+ DeveloperOrientedException,
+ ToolNotFoundError,
+ ToolGroupInactiveError,
+)
from ..mcp import (
MCPClientBase,
StatefulClientBase,
@@ -39,6 +43,7 @@ from ..mcp import (
from ..message import (
ToolCallBlock,
TextBlock,
+ ToolResultState,
)
from .._logging import logger
@@ -584,16 +589,16 @@ class Toolkit:
# Obtain the tool function
tool_func = available_tools[tool_call.name].tool
- # Prepare keyword arguments
- kwargs = _json_loads_with_repair(tool_call.input)
-
- # TODO: we should be build a mechanism to support state injection in
- # the future instead of hard coding here.
- if isinstance(tool_func, (ResetTools, Read, Write, Edit)):
- kwargs["_agent_state"] = state
-
# Async function
try:
+ # Prepare keyword arguments
+ kwargs = _json_loads_with_repair(tool_call.input)
+
+ # TODO: we should be build a mechanism to support state injection
+ # in the future instead of hard coding here.
+ if isinstance(tool_func, (ResetTools, Read, Write, Edit)):
+ kwargs["_agent_state"] = state
+
if inspect.iscoroutinefunction(tool_func.__call__):
res = await tool_func(**kwargs)
else:
@@ -632,7 +637,7 @@ class Toolkit:
text=f"Error occurred when calling MCP tool: {e}",
),
],
- state="error",
+ state=ToolResultState.ERROR,
)
yield chunk
tool_response.append_chunk(chunk)
@@ -647,10 +652,10 @@ class Toolkit:
content=[
TextBlock(
type="text",
- text=f"Error: {e}",
+ text=str(e),
),
],
- state="error",
+ state=ToolResultState.ERROR,
)
yield chunk
tool_response.append_chunk(chunk)
@@ -666,7 +671,7 @@ class Toolkit:
"</system-reminder>",
),
],
- state="interrupted",
+ state=ToolResultState.INTERRUPTED,
)
yield chunk
tool_response.append_chunk(chunk)
@@ -968,3 +973,40 @@ AsyncGenerator[ToolResponse, None]] | AsyncGenerator[ToolResponse, None]]`):
available_tools[tool_name] = tool
return available_tools
+
+ def check_tool_available(
+ self,
+ tool_name: str,
+ activated_groups: list[str],
+ ) -> ToolBase:
+ """Check if the tool is available now. If not, raise the
+ agent-oriented exception.
+
+ Args:
+ tool_name (`str`):
+ The name of the tool to be checked.
+ activated_groups (`list[str]`):
+ The currently activated tool groups.
+
+ Returns:
+ `ToolBase`:
+ If the tool is available, return the corresponding ToolBase
+ object. Otherwise, raise the agent-oriented exception with the
+ error message.
+ """
+ if tool_name not in self.tools:
+ raise ToolNotFoundError(
+ f"ToolNotFoundError: The tool named '{tool_name}' doesn't "
+ f"exist.",
+ )
+
+ group_name = self.tools[tool_name].group
+ if group_name != "basic" and group_name not in activated_groups:
+ raise ToolGroupInactiveError(
+ f"ToolGroupInactiveError: The tool '{tool_name}' in group "
+ f"'{group_name}' is currently inactive. "
+ f"You should first activate the group by calling the "
+ f"'{self.builtin_meta_tool.tool.name}' tool.",
+ )
+
+ return self.tools[tool_name].tool
diff --git a/tests/agent_basic_test.py b/tests/agent_basic_test.py
new file mode 100644
index 000000000..ccde9bd1b
--- /dev/null
+++ b/tests/agent_basic_test.py
@@ -0,0 +1,1255 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=redefined-builtin
+"""The basic test of the agent class."""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString, MockModel
+
+from agentscope.agent import Agent
+from agentscope.model import ChatResponse
+from agentscope.tool import (
+ ToolBase,
+ Toolkit,
+ ToolChunk,
+ PermissionDecision,
+ PermissionBehavior,
+ PermissionContext,
+)
+from agentscope.message import TextBlock, ToolCallBlock, UserMsg
+from agentscope.tool._types import RegisteredTool
+
+
+class MockSequentialTool(ToolBase):
+ """A mock tool that is not concurrency safe (sequential execution)."""
+
+ name: str = "mock_sequential_tool"
+ description: str = "A mock sequential tool for testing"
+ input_schema: dict[str, Any] = {
+ "type": "object",
+ "properties": {
+ "input": {"type": "string", "description": "Input string"},
+ },
+ "required": ["input"],
+ }
+ is_concurrency_safe: bool = False
+ is_read_only: bool = True
+ is_external_tool: bool = False
+ is_mcp: bool = False
+
+ async def check_permissions(
+ self,
+ tool_input: dict[str, Any],
+ context: PermissionContext,
+ ) -> PermissionDecision:
+ """Check permissions for the tool usage."""
+ return PermissionDecision(
+ behavior=PermissionBehavior.ALLOW,
+ decision_reason="Mock tool always allows",
+ message="Mock tool always allows",
+ )
+
+ async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+ """Execute the tool."""
+ return ToolChunk(
+ content=[TextBlock(text=f"Sequential result: {input}")],
+ )
+
+
+class MockConcurrentTool(ToolBase):
+ """A mock tool that is concurrency safe (concurrent execution)."""
+
+ name: str = "mock_concurrent_tool"
+ description: str = "A mock concurrent tool for testing"
+ input_schema: dict[str, Any] = {
+ "type": "object",
+ "properties": {
+ "input": {"type": "string", "description": "Input string"},
+ },
+ "required": ["input"],
+ }
+ is_concurrency_safe: bool = True
+ is_read_only: bool = True
+ is_external_tool: bool = False
+ is_mcp: bool = False
+
+ async def check_permissions(
+ self,
+ tool_input: dict[str, Any],
+ context: PermissionContext,
+ ) -> PermissionDecision:
+ """Check permissions for the tool usage."""
+ return PermissionDecision(
+ behavior=PermissionBehavior.ALLOW,
+ decision_reason="Mock tool always allows",
+ message="Mock tool always allows",
+ )
+
+ async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+ """Execute the tool."""
+ return ToolChunk(
+ content=[TextBlock(text=f"Concurrent result: {input}")],
+ )
+
+
+class AgentBasicTest(IsolatedAsyncioTestCase):
+ """The basic test of the agent class."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.model = MockModel()
+ self.agent = Agent(
+ name="Friday",
+ system_prompt="You are a helpful assistant.",
+ model=self.model,
+ toolkit=Toolkit(),
+ )
+
+ def _get_event_base(self, reply_id: str) -> dict:
+ """Get the dict with the basic fields for event assertion."""
+ return {
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "reply_id": reply_id,
+ }
+
+ def _get_msg_base(self) -> dict:
+ """Get the dict with the basic fields for message assertion."""
+ return {
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "metadata": {},
+ "name": "Friday",
+ "role": "assistant",
+ }
+
+ async def test_streaming_reasoning(self) -> None:
+ """Test the streaming model inference without tool calls generated,
+ only text in model response.
+
+ Test both the reply and replyStream interfaces.
+ """
+ # Set up mock responses for streaming
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=[TextBlock(text="Hello")],
+ is_last=False,
+ ),
+ ChatResponse(
+ content=[TextBlock(text=" world")],
+ is_last=False,
+ ),
+ ChatResponse(content=[TextBlock(text="!")], is_last=False),
+ ChatResponse(
+ content=[TextBlock(text="Hello world!")],
+ is_last=True,
+ ),
+ ],
+ ],
+ )
+
+ # Test replyStream interface
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content="Hi"),
+ ):
+ events.append(event.model_dump())
+
+ # Verify events
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {
+ "type": "MODEL_CALL_START",
+ "model_name": "mock-model",
+ },
+ {
+ "type": "TEXT_BLOCK_START",
+ "block_id": AnyString(),
+ },
+ {
+ "type": "TEXT_BLOCK_DELTA",
+ "block_id": AnyString(),
+ "delta": "Hello",
+ },
+ {
+ "type": "TEXT_BLOCK_DELTA",
+ "block_id": AnyString(),
+ "delta": " world",
+ },
+ {
+ "type": "TEXT_BLOCK_DELTA",
+ "block_id": AnyString(),
+ "delta": "!",
+ },
+ {
+ "type": "TEXT_BLOCK_END",
+ "block_id": AnyString(),
+ },
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ {
+ "type": "REPLY_END",
+ "session_id": session_id,
+ },
+ ]
+
+ basic_dict = self._get_event_base(reply_id)
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ # Assert context after reply_stream
+ msg_base = self._get_msg_base()
+ expected_context = [
+ {
+ **msg_base,
+ "name": "user",
+ "role": "user",
+ "content": "Hi",
+ },
+ {
+ **msg_base,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hello world!",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ # Test reply interface
+ self.model.cnt = 0 # Reset mock model response index
+ msg = await self.agent.reply(UserMsg(name="user", content="Hi again"))
+ self.assertDictEqual(
+ msg.model_dump(),
+ {
+ "name": "Friday",
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hello world!",
+ },
+ ],
+ "created_at": AnyString(),
+ "id": AnyString(),
+ "metadata": {},
+ },
+ )
+
+ # Assert context after reply
+ expected_context_after_reply = [
+ {
+ **msg_base,
+ "name": "user",
+ "role": "user",
+ "content": "Hi",
+ "metadata": {},
+ },
+ {
+ **msg_base,
+ "name": "Friday",
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hello world!",
+ },
+ ],
+ "metadata": {},
+ },
+ {
+ **msg_base,
+ "name": "user",
+ "role": "user",
+ "content": "Hi again",
+ "metadata": {},
+ },
+ {
+ **msg_base,
+ "name": "Friday",
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hello world!",
+ },
+ ],
+ "metadata": {},
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ self.assertListEqual(context_dicts, expected_context_after_reply)
+
+ async def test_non_streaming_reasoning(self) -> None:
+ """Test the non-streaming model inference without tool calls generated,
+ only text in model response.
+
+ Test both the reply and replyStream interfaces.
+ """
+ # Set up mock response for non-streaming
+ self.model.set_responses(
+ [
+ ChatResponse(
+ content=[TextBlock(text="Hello world!")],
+ is_last=True,
+ usage=None,
+ ),
+ ],
+ )
+
+ # Test replyStream interface
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content="Hi"),
+ ):
+ events.append(event.model_dump())
+
+ # Verify events
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {
+ "type": "MODEL_CALL_START",
+ "model_name": "mock-model",
+ },
+ {
+ "type": "TEXT_BLOCK_START",
+ "block_id": AnyString(),
+ },
+ {
+ "type": "TEXT_BLOCK_DELTA",
+ "block_id": AnyString(),
+ "delta": "Hello world!",
+ },
+ {
+ "type": "TEXT_BLOCK_END",
+ "block_id": AnyString(),
+ },
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ {
+ "type": "REPLY_END",
+ "session_id": session_id,
+ },
+ ]
+
+ basic_dict = self._get_event_base(reply_id)
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ # Assert context after reply_stream
+ msg_base = self._get_msg_base()
+ expected_context = [
+ {
+ **msg_base,
+ "name": "user",
+ "role": "user",
+ "content": "Hi",
+ "metadata": {},
+ },
+ {
+ **msg_base,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hello world!",
+ },
+ ],
+ "metadata": {},
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ # Test reply interface
+ self.model.set_responses(
+ [
+ ChatResponse(
+ content=[TextBlock(text="Hello world!")],
+ is_last=True,
+ usage=None,
+ ),
+ ],
+ )
+
+ msg = await self.agent.reply(UserMsg(name="user", content="Hi again"))
+ self.assertDictEqual(
+ msg.model_dump(),
+ {
+ "name": "Friday",
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hello world!",
+ },
+ ],
+ "created_at": AnyString(),
+ "id": AnyString(),
+ "metadata": {},
+ },
+ )
+
+ # Assert context after reply
+ expected_context_after_reply = [
+ {
+ **msg_base,
+ "name": "user",
+ "role": "user",
+ "content": "Hi",
+ "metadata": {},
+ },
+ {
+ **msg_base,
+ "name": "Friday",
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hello world!",
+ },
+ ],
+ "metadata": {},
+ },
+ {
+ **msg_base,
+ "name": "user",
+ "role": "user",
+ "content": "Hi again",
+ "metadata": {},
+ },
+ {
+ **msg_base,
+ "name": "Friday",
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hello world!",
+ },
+ ],
+ "metadata": {},
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ self.assertListEqual(context_dicts, expected_context_after_reply)
+
+ async def test_streaming_sequential_tool_calls(self) -> None:
+ """Test the streaming model inference with tool calls generated.
+
+ Test only the replyStream interface. The `is_concurrent_safe` of the
+ registered tools should be False to make sure the tool calls are
+ executed sequentially.
+
+ To assert:
+ 1. The events (by assert the dict generated by model_dump)
+ 2. The final reply message
+ 3. The agent state (Before and after replyStream)
+ """
+ # Register sequential tools
+ seq_tool = MockSequentialTool()
+ self.agent.toolkit.tools[seq_tool.name] = RegisteredTool(
+ tool=seq_tool,
+ group="basic",
+ )
+
+ # Create tool call IDs
+ tool_call_id_1 = "tool_call_1"
+ tool_call_id_2 = "tool_call_2"
+
+ # Set up mock responses with tool calls
+ text_block = TextBlock(text="I'll call the tool")
+ tool_call_1 = ToolCallBlock(
+ id=tool_call_id_1,
+ name="mock_sequential_tool",
+ input='{"input": "test1"}',
+ )
+ tool_call_1_part1 = ToolCallBlock(
+ id=tool_call_id_1,
+ name="mock_sequential_tool",
+ input='{"input": ',
+ )
+ tool_call_1_part2 = ToolCallBlock(
+ id=tool_call_id_1,
+ name="mock_sequential_tool",
+ input='"test1"}',
+ )
+ tool_call_2 = ToolCallBlock(
+ id=tool_call_id_2,
+ name="mock_sequential_tool",
+ input='{"input": "test2"}',
+ )
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=[text_block, tool_call_1_part1],
+ is_last=False,
+ ),
+ ChatResponse(
+ content=[tool_call_1_part2],
+ is_last=False,
+ ),
+ ChatResponse(
+ content=[tool_call_2],
+ is_last=False,
+ ),
+ ChatResponse(
+ content=[text_block, tool_call_1, tool_call_2],
+ is_last=True,
+ ),
+ ],
+ [
+ ChatResponse(
+ content=[TextBlock(text="ended")],
+ is_last=False,
+ ),
+ ChatResponse(
+ content=[TextBlock(text="ended")],
+ is_last=True,
+ ),
+ ],
+ ],
+ )
+
+ # Collect all events
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content="Test"),
+ ):
+ events.append(event.model_dump(mode="json"))
+
+ # Verify events
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+
+ # Expected events for sequential tool calls
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ {"type": "TEXT_BLOCK_START", "block_id": AnyString()},
+ {
+ "type": "TEXT_BLOCK_DELTA",
+ "block_id": AnyString(),
+ "delta": "I'll call the tool",
+ },
+ {
+ "type": "TOOL_CALL_START",
+ "tool_call_id": tool_call_id_1,
+ "tool_call_name": "mock_sequential_tool",
+ },
+ {
+ "type": "TOOL_CALL_DELTA",
+ "tool_call_id": tool_call_id_1,
+ "delta": '{"input": ',
+ },
+ {"type": "TEXT_BLOCK_END", "block_id": AnyString()},
+ {
+ "type": "TOOL_CALL_DELTA",
+ "tool_call_id": tool_call_id_1,
+ "delta": '"test1"}',
+ },
+ {
+ "type": "TOOL_CALL_START",
+ "tool_call_id": tool_call_id_2,
+ "tool_call_name": "mock_sequential_tool",
+ },
+ {
+ "type": "TOOL_CALL_DELTA",
+ "tool_call_id": tool_call_id_2,
+ "delta": '{"input": "test2"}',
+ },
+ {"type": "TOOL_CALL_END", "tool_call_id": tool_call_id_1},
+ {"type": "TOOL_CALL_END", "tool_call_id": tool_call_id_2},
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ {
+ "type": "TOOL_RESULT_START",
+ "tool_call_id": tool_call_id_1,
+ "tool_call_name": "mock_sequential_tool",
+ },
+ {
+ "type": "TOOL_RESULT_TEXT_DELTA",
+ "tool_call_id": tool_call_id_1,
+ "delta": "Sequential result: test1",
+ },
+ {
+ "type": "TOOL_RESULT_END",
+ "tool_call_id": tool_call_id_1,
+ "state": "success",
+ },
+ {
+ "type": "TOOL_RESULT_START",
+ "tool_call_id": tool_call_id_2,
+ "tool_call_name": "mock_sequential_tool",
+ },
+ {
+ "type": "TOOL_RESULT_TEXT_DELTA",
+ "tool_call_id": tool_call_id_2,
+ "delta": "Sequential result: test2",
+ },
+ {
+ "type": "TOOL_RESULT_END",
+ "tool_call_id": tool_call_id_2,
+ "state": "success",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ {"type": "TEXT_BLOCK_START", "block_id": AnyString()},
+ {
+ "type": "TEXT_BLOCK_DELTA",
+ "block_id": AnyString(),
+ "delta": "ended",
+ },
+ {"type": "TEXT_BLOCK_END", "block_id": AnyString()},
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ {"type": "REPLY_END", "session_id": session_id},
+ ]
+
+ basic_dict = self._get_event_base(reply_id)
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ # Assert context after reply_stream
+ msg_base = self._get_msg_base()
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": "Test",
+ },
+ {
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "I'll call the tool",
+ },
+ {
+ "type": "tool_call",
+ "id": tool_call_id_1,
+ "name": "mock_sequential_tool",
+ "input": '{"input": "test1"}',
+ "state": "finished",
+ },
+ {
+ "type": "tool_call",
+ "id": tool_call_id_2,
+ "name": "mock_sequential_tool",
+ "input": '{"input": "test2"}',
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Sequential result: test1",
+ },
+ ],
+ "name": "mock_sequential_tool",
+ "state": "success",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Sequential result: test2",
+ },
+ ],
+ "name": "mock_sequential_tool",
+ "state": "success",
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "ended",
+ },
+ ],
+ },
+ ]
+
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ async def test_streaming_concurrent_tool_calls(self) -> None:
+ """Test the streaming model inference with tool calls generated.
+
+ Test only the replyStream interface. The `is_concurrent_safe` of the
+ registered tools should be True to make sure the tool calls are
+ executed concurrently.
+
+ To assert:
+ 1. The events (by assert the dict generated by model_dump)
+ 2. The final reply message
+ 3. The agent state (Before and after replyStream)
+ """
+ # Register concurrent tools
+ conc_tool = MockConcurrentTool()
+
+ self.agent.toolkit.tools[conc_tool.name] = RegisteredTool(
+ tool=conc_tool,
+ group="basic",
+ )
+
+ # Create tool call IDs
+ tool_call_id_1 = "tool_call_1"
+ tool_call_id_2 = "tool_call_2"
+
+ # Set up mock responses with tool calls
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=tool_call_id_1,
+ name="mock_concurrent_tool",
+ input='{"input": "test1"}',
+ ),
+ ToolCallBlock(
+ id=tool_call_id_2,
+ name="mock_concurrent_tool",
+ input='{"input": "test2"}',
+ ),
+ ],
+ is_last=True,
+ usage=None,
+ ),
+ ],
+ [
+ ChatResponse(
+ content=[TextBlock(text="All done")],
+ is_last=False,
+ ),
+ ChatResponse(
+ content=[TextBlock(text="All done")],
+ is_last=True,
+ ),
+ ],
+ ],
+ )
+
+ # Collect all events
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content="Test"),
+ ):
+ events.append(event.model_dump())
+
+ # Verify events
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+
+ # For concurrent execution, the order of tool results may vary
+ # Split events into: prefix (before concurrent), concurrent part,
+ # suffix (after concurrent)
+
+ # Expected prefix events (before tool execution)
+ expected_prefix = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ ]
+
+ # Expected concurrent events (order may vary)
+ expected_concurrent = [
+ {
+ "type": "TOOL_RESULT_START",
+ "tool_call_id": tool_call_id_1,
+ "tool_call_name": "mock_concurrent_tool",
+ },
+ {
+ "type": "TOOL_RESULT_TEXT_DELTA",
+ "tool_call_id": tool_call_id_1,
+ "delta": "Concurrent result: test1",
+ },
+ {
+ "type": "TOOL_RESULT_END",
+ "tool_call_id": tool_call_id_1,
+ "state": "success",
+ },
+ {
+ "type": "TOOL_RESULT_START",
+ "tool_call_id": tool_call_id_2,
+ "tool_call_name": "mock_concurrent_tool",
+ },
+ {
+ "type": "TOOL_RESULT_TEXT_DELTA",
+ "tool_call_id": tool_call_id_2,
+ "delta": "Concurrent result: test2",
+ },
+ {
+ "type": "TOOL_RESULT_END",
+ "tool_call_id": tool_call_id_2,
+ "state": "success",
+ },
+ ]
+
+ # Expected suffix events (final model call with pure text)
+ expected_suffix = [
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ {"type": "TEXT_BLOCK_START", "block_id": AnyString()},
+ {
+ "type": "TEXT_BLOCK_DELTA",
+ "block_id": AnyString(),
+ "delta": "All done",
+ },
+ {"type": "TEXT_BLOCK_END", "block_id": AnyString()},
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ {"type": "REPLY_END", "session_id": session_id},
+ ]
+
+ # Assert prefix events (fixed order)
+ basic_dict = self._get_event_base(reply_id)
+ prefix_len = len(expected_prefix)
+ self.assertListEqual(
+ events[:prefix_len],
+ [{**basic_dict, **_} for _ in expected_prefix],
+ )
+
+ # Assert concurrent events (order may vary)
+ concurrent_len = len(expected_concurrent)
+ concurrent_events = events[prefix_len : prefix_len + concurrent_len]
+
+ # Check length matches
+ self.assertEqual(len(concurrent_events), len(expected_concurrent))
+
+ # Check each expected event is in the actual events
+ for expected_event in expected_concurrent:
+ expected_with_base = {**basic_dict, **expected_event}
+ self.assertIn(expected_with_base, concurrent_events)
+
+ # Assert suffix events (fixed order)
+ suffix_events = events[prefix_len + concurrent_len :]
+ self.assertListEqual(
+ suffix_events,
+ [{**basic_dict, **_} for _ in expected_suffix],
+ )
+
+ # Assert context after reply_stream
+ msg_base = self._get_msg_base()
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": "Test",
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": tool_call_id_1,
+ "name": "mock_concurrent_tool",
+ "input": '{"input": "test1"}',
+ "state": "finished",
+ },
+ {
+ "type": "tool_call",
+ "id": tool_call_id_2,
+ "name": "mock_concurrent_tool",
+ "input": '{"input": "test2"}',
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Concurrent result: test1",
+ },
+ ],
+ "name": "mock_concurrent_tool",
+ "state": "success",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Concurrent result: test2",
+ },
+ ],
+ "name": "mock_concurrent_tool",
+ "state": "success",
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "All done",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ async def test_streaming_mixed_tool_calls(self) -> None:
+ """Test the streaming model inference with both sequential and
+ concurrent tool calls generated.
+
+ Test only the replyStream interface.
+
+ To assert:
+ 1. The events (by assert the dict generated by model_dump)
+ 2. The final reply message
+ 3. The agent state (Before and after replyStream)
+ """
+ # Register both sequential and concurrent tools
+ seq_tool = MockSequentialTool()
+ conc_tool = MockConcurrentTool()
+
+ self.agent.toolkit.tools[seq_tool.name] = RegisteredTool(
+ tool=seq_tool,
+ group="basic",
+ )
+
+ self.agent.toolkit.tools[conc_tool.name] = RegisteredTool(
+ tool=conc_tool,
+ group="basic",
+ )
+
+ # Create tool call IDs
+ tool_call_id_1 = "tool_call_1"
+ tool_call_id_2 = "tool_call_2"
+ tool_call_id_3 = "tool_call_3"
+
+ # Set up mock responses with mixed tool calls
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=tool_call_id_1,
+ name="mock_sequential_tool",
+ input='{"input": "seq1"}',
+ ),
+ ToolCallBlock(
+ id=tool_call_id_2,
+ name="mock_concurrent_tool",
+ input='{"input": "conc1"}',
+ ),
+ ToolCallBlock(
+ id=tool_call_id_3,
+ name="mock_concurrent_tool",
+ input='{"input": "conc2"}',
+ ),
+ ],
+ is_last=True,
+ usage=None,
+ ),
+ ],
+ [
+ ChatResponse(
+ content=[TextBlock(text="All done")],
+ is_last=False,
+ ),
+ ChatResponse(
+ content=[TextBlock(text="All done")],
+ is_last=True,
+ ),
+ ],
+ ],
+ )
+
+ # Collect all events
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content="Test"),
+ ):
+ events.append(event.model_dump())
+
+ # Verify events
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+
+ # For mixed execution: sequential tool first, then concurrent tools
+ # Split events into: prefix (before tool execution), sequential part,
+ # concurrent part, suffix (final model call)
+
+ # Expected prefix events (before tool execution)
+ expected_prefix = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ ]
+
+ # Expected sequential tool execution events
+ expected_sequential = [
+ {
+ "type": "TOOL_RESULT_START",
+ "tool_call_id": tool_call_id_1,
+ "tool_call_name": "mock_sequential_tool",
+ },
+ {
+ "type": "TOOL_RESULT_TEXT_DELTA",
+ "tool_call_id": tool_call_id_1,
+ "delta": "Sequential result: seq1",
+ },
+ {
+ "type": "TOOL_RESULT_END",
+ "tool_call_id": tool_call_id_1,
+ "state": "success",
+ },
+ ]
+
+ # Expected concurrent events (order may vary)
+ expected_concurrent = [
+ {
+ "type": "TOOL_RESULT_START",
+ "tool_call_id": tool_call_id_2,
+ "tool_call_name": "mock_concurrent_tool",
+ },
+ {
+ "type": "TOOL_RESULT_TEXT_DELTA",
+ "tool_call_id": tool_call_id_2,
+ "delta": "Concurrent result: conc1",
+ },
+ {
+ "type": "TOOL_RESULT_END",
+ "tool_call_id": tool_call_id_2,
+ "state": "success",
+ },
+ {
+ "type": "TOOL_RESULT_START",
+ "tool_call_id": tool_call_id_3,
+ "tool_call_name": "mock_concurrent_tool",
+ },
+ {
+ "type": "TOOL_RESULT_TEXT_DELTA",
+ "tool_call_id": tool_call_id_3,
+ "delta": "Concurrent result: conc2",
+ },
+ {
+ "type": "TOOL_RESULT_END",
+ "tool_call_id": tool_call_id_3,
+ "state": "success",
+ },
+ ]
+
+ # Expected suffix events (final model call with pure text)
+ expected_suffix = [
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ {"type": "TEXT_BLOCK_START", "block_id": AnyString()},
+ {
+ "type": "TEXT_BLOCK_DELTA",
+ "block_id": AnyString(),
+ "delta": "All done",
+ },
+ {"type": "TEXT_BLOCK_END", "block_id": AnyString()},
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ {"type": "REPLY_END", "session_id": session_id},
+ ]
+
+ # Assert prefix events (fixed order)
+ basic_dict = self._get_event_base(reply_id)
+ prefix_len = len(expected_prefix)
+ self.assertListEqual(
+ events[:prefix_len],
+ [{**basic_dict, **_} for _ in expected_prefix],
+ )
+
+ # Assert sequential events (fixed order)
+ sequential_len = len(expected_sequential)
+ self.assertListEqual(
+ events[prefix_len : prefix_len + sequential_len],
+ [{**basic_dict, **_} for _ in expected_sequential],
+ )
+
+ # Assert concurrent events (order may vary)
+ concurrent_len = len(expected_concurrent)
+ concurrent_events = events[
+ prefix_len
+ + sequential_len : prefix_len
+ + sequential_len
+ + concurrent_len
+ ]
+
+ # Check length matches
+ self.assertEqual(len(concurrent_events), len(expected_concurrent))
+
+ # Check each expected event is in the actual events
+ for expected_event in expected_concurrent:
+ expected_with_base = {**basic_dict, **expected_event}
+ self.assertIn(expected_with_base, concurrent_events)
+
+ # Assert suffix events (fixed order)
+ suffix_events = events[prefix_len + sequential_len + concurrent_len :]
+ self.assertListEqual(
+ suffix_events,
+ [{**basic_dict, **_} for _ in expected_suffix],
+ )
+
+ # Assert context after reply_stream
+ msg_base = self._get_msg_base()
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": "Test",
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": tool_call_id_1,
+ "name": "mock_sequential_tool",
+ "input": '{"input": "seq1"}',
+ "state": "finished",
+ },
+ {
+ "type": "tool_call",
+ "id": tool_call_id_2,
+ "name": "mock_concurrent_tool",
+ "input": '{"input": "conc1"}',
+ "state": "finished",
+ },
+ {
+ "type": "tool_call",
+ "id": tool_call_id_3,
+ "name": "mock_concurrent_tool",
+ "input": '{"input": "conc2"}',
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": "mock_sequential_tool",
+ "state": "success",
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Sequential result: seq1",
+ },
+ ],
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": "mock_concurrent_tool",
+ "state": "success",
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Concurrent result: conc1",
+ },
+ ],
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": "mock_concurrent_tool",
+ "state": "success",
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Concurrent result: conc2",
+ },
+ ],
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "All done",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
diff --git a/tests/event_test.py b/tests/event_test.py
new file mode 100644
index 000000000..24df95ea1
--- /dev/null
+++ b/tests/event_test.py
@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+"""Event test"""
+from unittest.async_case import IsolatedAsyncioTestCase
+from utils import AnyString
+from agentscope.event import ReplyStartEvent
+
+
+class EventTest(IsolatedAsyncioTestCase):
+ """The event test case."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+
+ async def test_model_dump(self) -> None:
+ """Test model dump."""
+ event = ReplyStartEvent(
+ session_id="test_session",
+ reply_id="test_reply",
+ name="Friday",
+ ).model_dump()
+ self.assertDictEqual(
+ event,
+ {
+ "type": "REPLY_START",
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "session_id": "test_session",
+ "reply_id": "test_reply",
+ "name": "Friday",
+ "role": "assistant",
+ },
+ )
+ self.assertIsInstance(event["type"], str)
+
+ async def test_model_validate(self) -> None:
+ """Test model validate."""
+ data = {
+ "type": "REPLY_START",
+ "id": "test_id",
+ "created_at": "2024-01-01T00:00:00",
+ "session_id": "test_session",
+ "reply_id": "test_reply",
+ "name": "Friday",
+ "role": "assistant",
+ }
+ ReplyStartEvent.model_validate(data)
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
diff --git a/tests/hitl_external_execution_test.py b/tests/hitl_external_execution_test.py
new file mode 100644
index 000000000..ad46d3762
--- /dev/null
+++ b/tests/hitl_external_execution_test.py
@@ -0,0 +1,1266 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=redefined-builtin
+"""Test the external execution events in the agent class."""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString, MockModel
+
+from agentscope.agent import Agent
+from agentscope.model import ChatResponse
+from agentscope.tool import (
+ ToolBase,
+ Toolkit,
+ ToolChunk,
+ PermissionDecision,
+ PermissionBehavior,
+ PermissionContext,
+)
+from agentscope.message import (
+ TextBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ UserMsg,
+ ToolResultState,
+)
+from agentscope.tool._types import RegisteredTool
+from agentscope.event import ExternalExecutionResultEvent
+
+
+class MockExternalSequentialTool(ToolBase):
+ """A mock tool that requires external execution (sequential)."""
+
+ name: str = "mock_external_sequential_tool"
+ description: str = "A mock external sequential tool for testing"
+ input_schema: dict[str, Any] = {
+ "type": "object",
+ "properties": {
+ "input": {"type": "string", "description": "Input string"},
+ },
+ "required": ["input"],
+ }
+ is_concurrency_safe: bool = False
+ is_read_only: bool = True
+ is_external_tool: bool = True
+ is_mcp: bool = False
+
+ async def check_permissions(
+ self,
+ tool_input: dict[str, Any],
+ context: PermissionContext,
+ ) -> PermissionDecision:
+ """Check permissions for the tool usage."""
+ return PermissionDecision(
+ behavior=PermissionBehavior.ALLOW,
+ decision_reason="Mock external tool always allows",
+ message="Mock external tool always allows",
+ )
+
+ async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+ """Execute the tool."""
+ return ToolChunk(
+ content=[TextBlock(text=f"External sequential result: {input}")],
+ )
+
+
+class MockExternalConcurrentTool(ToolBase):
+ """A mock tool that requires external execution (concurrent)."""
+
+ name: str = "mock_external_concurrent_tool"
+ description: str = "A mock external concurrent tool for testing"
+ input_schema: dict[str, Any] = {
+ "type": "object",
+ "properties": {
+ "input": {"type": "string", "description": "Input string"},
+ },
+ "required": ["input"],
+ }
+ is_concurrency_safe: bool = True
+ is_read_only: bool = True
+ is_external_tool: bool = True
+ is_mcp: bool = False
+
+ async def check_permissions(
+ self,
+ tool_input: dict[str, Any],
+ context: PermissionContext,
+ ) -> PermissionDecision:
+ """Check permissions for the tool usage."""
+ return PermissionDecision(
+ behavior=PermissionBehavior.ALLOW,
+ decision_reason="Mock external tool always allows",
+ message="Mock external tool always allows",
+ )
+
+ async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+ """Execute the tool."""
+ return ToolChunk(
+ content=[TextBlock(text=f"External concurrent result: {input}")],
+ )
+
+
+class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
+ """Test the external execution events in the agent class."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.model = MockModel()
+ self.agent = Agent(
+ name="Friday",
+ system_prompt="You are a helpful assistant.",
+ model=self.model,
+ toolkit=Toolkit(),
+ )
+ self.tool_call_id_1 = "tool_call_1"
+ self.tool_call_id_2 = "tool_call_2"
+ self.user_input_text = "Test"
+ self.tool_input_1 = '{"input": "test1"}'
+ self.tool_input_2 = '{"input": "test2"}'
+ self.sequential_tool_name = "mock_external_sequential_tool"
+ self.concurrent_tool_name = "mock_external_concurrent_tool"
+ self.sequential_result_1 = "External sequential result: test1"
+ self.sequential_result_2 = "External sequential result: test2"
+ self.concurrent_result_1 = "External concurrent result: test1"
+ self.concurrent_result_2 = "External concurrent result: test2"
+ self.final_response_text = "Final response after external execution"
+ self.final_text_events = [
+ {
+ "type": "MODEL_CALL_START",
+ "model_name": "mock-model",
+ },
+ {
+ "type": "TEXT_BLOCK_START",
+ "block_id": AnyString(),
+ },
+ {
+ "type": "TEXT_BLOCK_DELTA",
+ "block_id": AnyString(),
+ "delta": self.final_response_text,
+ },
+ {
+ "type": "TEXT_BLOCK_END",
+ "block_id": AnyString(),
+ },
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ ]
+ self.final_mock_responses = [
+ ChatResponse(
+ content=[
+ TextBlock(text=self.final_response_text),
+ ],
+ is_last=False,
+ usage=None,
+ ),
+ ChatResponse(
+ content=[
+ TextBlock(text=self.final_response_text),
+ ],
+ is_last=True,
+ usage=None,
+ ),
+ ]
+
+ def _get_event_base(self, reply_id: str) -> dict:
+ """Get the dict with the basic fields for event assertion."""
+ return {
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "reply_id": reply_id,
+ }
+
+ def _get_msg_base(self) -> dict:
+ """Get the dict with the basic fields for message assertion."""
+ return {
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "metadata": {},
+ "name": "Friday",
+ "role": "assistant",
+ }
+
+ def _get_tool_call_events(
+ self,
+ id: str,
+ name: str,
+ delta: str,
+ ) -> list[dict]:
+ """Helper method to get the expected tool call events."""
+ return [
+ {
+ "type": "TOOL_CALL_START",
+ "tool_call_id": id,
+ "tool_call_name": name,
+ },
+ {
+ "type": "TOOL_CALL_DELTA",
+ "tool_call_id": id,
+ "delta": delta,
+ },
+ {
+ "type": "TOOL_CALL_END",
+ "tool_call_id": id,
+ },
+ ]
+
+ def _get_tool_result_events(
+ self,
+ id: str,
+ result: str,
+ state: str = "success",
+ ) -> list[dict]:
+ """Helper method to get the expected tool result events."""
+ return [
+ {
+ "type": "TOOL_RESULT_TEXT_DELTA",
+ "tool_call_id": id,
+ "delta": result,
+ },
+ {
+ "type": "TOOL_RESULT_END",
+ "tool_call_id": id,
+ "state": state,
+ },
+ ]
+
+ def _get_require_external_execution_events(
+ self,
+ reply_id: str,
+ id: str,
+ name: str,
+ tool_input: str,
+ ) -> list[dict]:
+ """Helper method to get the expected external execution events."""
+ return [
+ {
+ "type": "TOOL_RESULT_START",
+ "tool_call_id": id,
+ "tool_call_name": name,
+ },
+ {
+ "type": "REQUIRE_EXTERNAL_EXECUTION",
+ "reply_id": reply_id,
+ "tool_calls": [
+ {
+ "type": "tool_call",
+ "id": id,
+ "name": name,
+ "input": tool_input,
+ "state": "submitted",
+ },
+ ],
+ },
+ ]
+
+ async def test_single_external_execution(self) -> None:
+ """Test single external execution tool call.
+
+ The agent should:
+ 1. Generate a tool call that requires external execution
+ 2. Emit REQUIRE_EXTERNAL_EXECUTION event and pause
+ 3. Resume when ExternalExecutionResultEvent is provided
+ 4. Continue execution without calling the model again
+ """
+ # Register external tool
+ ext_tool = MockExternalSequentialTool()
+ self.agent.toolkit.tools[ext_tool.name] = RegisteredTool(
+ tool=ext_tool,
+ group="basic",
+ )
+
+ # Set up mock response with tool call (no final text response)
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.sequential_tool_name,
+ input=self.tool_input_1,
+ ),
+ ],
+ is_last=False,
+ usage=None,
+ ),
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.sequential_tool_name,
+ input=self.tool_input_1,
+ ),
+ ],
+ is_last=True,
+ usage=None,
+ ),
+ ],
+ self.final_mock_responses,
+ ],
+ )
+
+ # First call: collect events until REQUIRE_EXTERNAL_EXECUTION
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content=self.user_input_text),
+ ):
+ events.append(event.model_dump())
+
+ # Verify events
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ *self._get_tool_call_events(
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ ),
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ *self._get_require_external_execution_events(
+ reply_id,
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ ),
+ ]
+
+ basic_dict = self._get_event_base(reply_id)
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ # Assert context after first call
+ msg_base = self._get_msg_base()
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "submitted",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ # Create external execution result event
+ external_result_event = ExternalExecutionResultEvent(
+ reply_id=reply_id,
+ execution_results=[
+ ToolResultBlock(
+ id=self.tool_call_id_1,
+ name=self.sequential_tool_name,
+ output=[
+ TextBlock(text=self.sequential_result_1),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ )
+
+ # Second call: resume with external execution result
+ events = []
+ async for event in self.agent.reply_stream(
+ event=external_result_event,
+ ):
+ events.append(event.model_dump())
+
+ # Verify events after resumption
+ expected_events_resume = [
+ *self._get_tool_result_events(
+ self.tool_call_id_1,
+ self.sequential_result_1,
+ ),
+ *self.final_text_events,
+ {"type": "REPLY_END", "session_id": session_id},
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_resume],
+ )
+
+ # Assert final context
+ expected_context_final = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.sequential_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.sequential_result_1,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.final_response_text,
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context_final = [
+ {**msg_base, **_} for _ in expected_context_final
+ ]
+ self.assertListEqual(context_dicts, expected_context_final)
+
+ async def test_sequential_external_execution(self) -> None:
+ """Test multiple external execution tool calls in sequential execution.
+
+ The agent should:
+ 1. Generate multiple tool calls that require external execution
+ 2. All tools have is_concurrent_safe=False (sequential)
+ 3. Emit REQUIRE_EXTERNAL_EXECUTION event and pause
+ 4. Resume when ExternalExecutionResultEvent is provided
+ 5. Continue execution without calling the model again
+ """
+ # Register external sequential tool
+ ext_tool = MockExternalSequentialTool()
+ self.agent.toolkit.tools[ext_tool.name] = RegisteredTool(
+ tool=ext_tool,
+ group="basic",
+ )
+
+ # Set up mock response with multiple tool calls
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.sequential_tool_name,
+ input=self.tool_input_1,
+ ),
+ ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.sequential_tool_name,
+ input=self.tool_input_2,
+ ),
+ ],
+ is_last=False,
+ usage=None,
+ ),
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.sequential_tool_name,
+ input=self.tool_input_1,
+ ),
+ ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.sequential_tool_name,
+ input=self.tool_input_2,
+ ),
+ ],
+ is_last=True,
+ usage=None,
+ ),
+ ],
+ self.final_mock_responses,
+ ],
+ )
+
+ # First call: collect events until REQUIRE_EXTERNAL_EXECUTION
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content=self.user_input_text),
+ ):
+ events.append(event.model_dump())
+
+ # Verify events
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+ tool_call_1_events = self._get_tool_call_events(
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ )
+ tool_call_2_events = self._get_tool_call_events(
+ self.tool_call_id_2,
+ self.sequential_tool_name,
+ self.tool_input_2,
+ )
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ *tool_call_1_events[:2],
+ *tool_call_2_events[:2],
+ tool_call_1_events[2],
+ tool_call_2_events[2],
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ *self._get_require_external_execution_events(
+ reply_id,
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ ),
+ ]
+
+ basic_dict = self._get_event_base(reply_id)
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ # Assert context after first call
+ msg_base = self._get_msg_base()
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "submitted",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_2,
+ "state": "pending",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ # Create external execution result event
+ external_result_event = ExternalExecutionResultEvent(
+ reply_id=reply_id,
+ execution_results=[
+ ToolResultBlock(
+ id=self.tool_call_id_1,
+ name=self.sequential_tool_name,
+ output=[
+ TextBlock(text=self.sequential_result_1),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ )
+
+ # Second call: resume with external execution result
+ events = []
+ async for event in self.agent.reply_stream(
+ event=external_result_event,
+ ):
+ events.append(event.model_dump())
+
+ # Verify events after resumption (sequential execution)
+ expected_events_resume = [
+ *self._get_tool_result_events(
+ self.tool_call_id_1,
+ self.sequential_result_1,
+ ),
+ *self._get_require_external_execution_events(
+ reply_id,
+ self.tool_call_id_2,
+ self.sequential_tool_name,
+ self.tool_input_2,
+ ),
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_resume],
+ )
+
+ # Given the external execution result of the second tool call
+ external_result_event = ExternalExecutionResultEvent(
+ reply_id=reply_id,
+ execution_results=[
+ ToolResultBlock(
+ id=self.tool_call_id_2,
+ name=self.sequential_tool_name,
+ output=[
+ TextBlock(text=self.sequential_result_2),
+ ],
+ state=ToolResultState.ERROR,
+ ),
+ ],
+ )
+
+ events = []
+ async for evnt in self.agent.reply_stream(
+ event=external_result_event,
+ ):
+ events.append(evnt.model_dump())
+
+ # Assert the events
+ expected_events_after_second_result = [
+ *self._get_tool_result_events(
+ self.tool_call_id_2,
+ self.sequential_result_2,
+ state="error",
+ ),
+ *self.final_text_events,
+ {"type": "REPLY_END", "session_id": session_id},
+ ]
+
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_after_second_result],
+ )
+
+ # Assert final context
+ expected_context_final = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "finished",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_2,
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.sequential_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.sequential_result_1,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.sequential_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.sequential_result_2,
+ },
+ ],
+ "state": "error",
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.final_response_text,
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context_final = [
+ {**msg_base, **_} for _ in expected_context_final
+ ]
+ self.assertListEqual(context_dicts, expected_context_final)
+
+ async def test_concurrent_external_execution(self) -> None:
+ """Test multiple external execution tool calls in concurrent execution.
+
+ The agent should:
+ 1. Generate multiple tool calls that require external execution
+ 2. All tools have is_concurrent_safe=True (concurrent)
+ 3. Emit REQUIRE_EXTERNAL_EXECUTION event and pause
+ 4. Resume when ExternalExecutionResultEvent is provided
+ 5. Continue execution without calling the model again
+ """
+ # Register external concurrent tool
+ ext_tool = MockExternalConcurrentTool()
+ self.agent.toolkit.tools[ext_tool.name] = RegisteredTool(
+ tool=ext_tool,
+ group="basic",
+ )
+
+ # Set up mock response with multiple tool calls
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_1,
+ ),
+ ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_2,
+ ),
+ ],
+ is_last=False,
+ usage=None,
+ ),
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_1,
+ ),
+ ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_2,
+ ),
+ ],
+ is_last=True,
+ usage=None,
+ ),
+ ],
+ self.final_mock_responses,
+ ],
+ )
+
+ # First call: collect events until REQUIRE_EXTERNAL_EXECUTION
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content=self.user_input_text),
+ ):
+ events.append(event.model_dump())
+
+ # Verify events
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+ tool_call_1_events = self._get_tool_call_events(
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.tool_input_1,
+ )
+ tool_call_2_events = self._get_tool_call_events(
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.tool_input_2,
+ )
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ *tool_call_1_events[:2],
+ *tool_call_2_events[:2],
+ tool_call_1_events[2],
+ tool_call_2_events[2],
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ *self._get_require_external_execution_events(
+ reply_id,
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.tool_input_1,
+ ),
+ *self._get_require_external_execution_events(
+ reply_id,
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.tool_input_2,
+ ),
+ ]
+
+ basic_dict = self._get_event_base(reply_id)
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ # Assert context after first call
+ msg_base = self._get_msg_base()
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_1,
+ "state": "submitted",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_2,
+ "state": "submitted",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ # Create external execution result event
+ external_result_event = ExternalExecutionResultEvent(
+ reply_id=reply_id,
+ execution_results=[
+ ToolResultBlock(
+ id=self.tool_call_id_1,
+ name=self.concurrent_tool_name,
+ output=[
+ TextBlock(text=self.concurrent_result_1),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ )
+
+ # Second call: resume with external execution result
+ events = []
+ async for event in self.agent.reply_stream(
+ event=external_result_event,
+ ):
+ events.append(event.model_dump())
+
+ expected_concurrent = [
+ *self._get_tool_result_events(
+ self.tool_call_id_1,
+ self.concurrent_result_1,
+ ),
+ ]
+
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_concurrent],
+ )
+
+ # The second tool call result
+ external_result_event = ExternalExecutionResultEvent(
+ reply_id=reply_id,
+ execution_results=[
+ ToolResultBlock(
+ id=self.tool_call_id_2,
+ name=self.concurrent_tool_name,
+ output=[
+ TextBlock(text=self.concurrent_result_2),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(
+ event=external_result_event,
+ ):
+ events.append(event.model_dump())
+
+ expected_concurrent = [
+ *self._get_tool_result_events(
+ self.tool_call_id_2,
+ self.concurrent_result_2,
+ ),
+ *self.final_text_events,
+ {
+ "type": "REPLY_END",
+ "session_id": session_id,
+ },
+ ]
+
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_concurrent],
+ )
+
+ # Assert final context
+ expected_context_final = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_1,
+ "state": "finished",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_2,
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.concurrent_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.concurrent_result_1,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.concurrent_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.concurrent_result_2,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.final_response_text,
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context_final = [
+ {**msg_base, **_} for _ in expected_context_final
+ ]
+ self.assertListEqual(context_dicts, expected_context_final)
+
+ async def test_concurrent_external_execution_in_single_event(self) -> None:
+ """Test concurrent external execution when two results arrive together.
+
+ The agent should:
+ 1. Generate multiple external tool calls in concurrent mode
+ 2. Emit one require event per tool call during the initial run
+ 3. Resume when a single ExternalExecutionResultEvent carries both
+ results
+ 4. Continue reasoning only after both results are applied
+ """
+ ext_tool = MockExternalConcurrentTool()
+ self.agent.toolkit.tools[ext_tool.name] = RegisteredTool(
+ tool=ext_tool,
+ group="basic",
+ )
+
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_1,
+ ),
+ ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_2,
+ ),
+ ],
+ is_last=False,
+ usage=None,
+ ),
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_1,
+ ),
+ ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_2,
+ ),
+ ],
+ is_last=True,
+ usage=None,
+ ),
+ ],
+ self.final_mock_responses,
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content=self.user_input_text),
+ ):
+ events.append(event.model_dump())
+
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+ basic_dict = self._get_event_base(reply_id)
+ msg_base = self._get_msg_base()
+ tool_call_1_events = self._get_tool_call_events(
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.tool_input_1,
+ )
+ tool_call_2_events = self._get_tool_call_events(
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.tool_input_2,
+ )
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ *tool_call_1_events[:2],
+ *tool_call_2_events[:2],
+ tool_call_1_events[2],
+ tool_call_2_events[2],
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ *self._get_require_external_execution_events(
+ reply_id,
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.tool_input_1,
+ ),
+ *self._get_require_external_execution_events(
+ reply_id,
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.tool_input_2,
+ ),
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_1,
+ "state": "submitted",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_2,
+ "state": "submitted",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ external_result_event = ExternalExecutionResultEvent(
+ reply_id=reply_id,
+ execution_results=[
+ ToolResultBlock(
+ id=self.tool_call_id_1,
+ name=self.concurrent_tool_name,
+ output=[
+ TextBlock(text=self.concurrent_result_1),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ToolResultBlock(
+ id=self.tool_call_id_2,
+ name=self.concurrent_tool_name,
+ output=[
+ TextBlock(text=self.concurrent_result_2),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(
+ event=external_result_event,
+ ):
+ events.append(event.model_dump())
+
+ expected_events_resume = [
+ *self._get_tool_result_events(
+ self.tool_call_id_1,
+ self.concurrent_result_1,
+ ),
+ *self._get_tool_result_events(
+ self.tool_call_id_2,
+ self.concurrent_result_2,
+ ),
+ *self.final_text_events,
+ {
+ "type": "REPLY_END",
+ "session_id": session_id,
+ },
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_resume],
+ )
+
+ expected_context_final = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_1,
+ "state": "finished",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_2,
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.concurrent_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.concurrent_result_1,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.concurrent_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.concurrent_result_2,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.final_response_text,
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context_final = [
+ {**msg_base, **_} for _ in expected_context_final
+ ]
+ self.assertListEqual(context_dicts, expected_context_final)
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
diff --git a/tests/hitl_mixed_interrupt.py b/tests/hitl_mixed_interrupt.py
new file mode 100644
index 000000000..eb21b26ba
--- /dev/null
+++ b/tests/hitl_mixed_interrupt.py
@@ -0,0 +1,1209 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=redefined-builtin
+"""Test mixed user confirmation and external execution in the agent."""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString, MockModel
+
+from agentscope.event._event import ConfirmResult
+from agentscope.agent import Agent
+from agentscope.model import ChatResponse
+from agentscope.tool import (
+ ToolBase,
+ Toolkit,
+ ToolChunk,
+ PermissionDecision,
+ PermissionBehavior,
+ PermissionContext,
+)
+from agentscope.message import (
+ TextBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ UserMsg,
+ ToolResultState,
+)
+from agentscope.tool._types import RegisteredTool
+from agentscope.event import (
+ UserConfirmResultEvent,
+ ExternalExecutionResultEvent,
+)
+
+
+class MockMixedSequentialTool(ToolBase):
+ """A mock tool that requires confirmation and external execution."""
+
+ name: str = "mock_mixed_sequential_tool"
+ description: str = "A mock mixed sequential tool for testing"
+ input_schema: dict[str, Any] = {
+ "type": "object",
+ "properties": {
+ "input": {"type": "string", "description": "Input string"},
+ },
+ "required": ["input"],
+ }
+ is_concurrency_safe: bool = False
+ is_read_only: bool = False
+ is_external_tool: bool = True
+ is_mcp: bool = False
+
+ async def check_permissions(
+ self,
+ tool_input: dict[str, Any],
+ context: PermissionContext,
+ ) -> PermissionDecision:
+ """Check permissions for the tool usage."""
+ return PermissionDecision(
+ behavior=PermissionBehavior.ASK,
+ decision_reason="Mock mixed tool requires user confirmation",
+ message="Mock mixed tool requires user confirmation",
+ )
+
+ async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+ """Execute the tool."""
+ return ToolChunk(
+ content=[TextBlock(text=f"Mixed sequential result: {input}")],
+ )
+
+
+class MockMixedConcurrentTool(ToolBase):
+ """A mock tool that requires confirmation and external execution."""
+
+ name: str = "mock_mixed_concurrent_tool"
+ description: str = "A mock mixed concurrent tool for testing"
+ input_schema: dict[str, Any] = {
+ "type": "object",
+ "properties": {
+ "input": {"type": "string", "description": "Input string"},
+ },
+ "required": ["input"],
+ }
+ is_concurrency_safe: bool = True
+ is_read_only: bool = False
+ is_external_tool: bool = True
+ is_mcp: bool = False
+
+ async def check_permissions(
+ self,
+ tool_input: dict[str, Any],
+ context: PermissionContext,
+ ) -> PermissionDecision:
+ """Check permissions for the tool usage."""
+ return PermissionDecision(
+ behavior=PermissionBehavior.ASK,
+ decision_reason="Mock mixed tool requires user confirmation",
+ message="Mock mixed tool requires user confirmation",
+ )
+
+ async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+ """Execute the tool."""
+ return ToolChunk(
+ content=[TextBlock(text=f"Mixed concurrent result: {input}")],
+ )
+
+
+class AgentMixTest(IsolatedAsyncioTestCase):
+ """Test mixed user confirmation and external execution."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.model = MockModel()
+ self.agent = Agent(
+ name="Friday",
+ system_prompt="You are a helpful assistant.",
+ model=self.model,
+ toolkit=Toolkit(),
+ )
+ self.tool_call_id_1 = "tool_call_1"
+ self.tool_call_id_2 = "tool_call_2"
+ self.user_input_text = "Test"
+ self.tool_input_1 = '{"input": "test1"}'
+ self.tool_input_2 = '{"input": "test2"}'
+ self.sequential_tool_name = "mock_mixed_sequential_tool"
+ self.concurrent_tool_name = "mock_mixed_concurrent_tool"
+ self.sequential_result_1 = "Mixed sequential result: test1"
+ self.sequential_result_2 = "Mixed sequential result: test2"
+ self.concurrent_result_1 = "Mixed concurrent result: test1"
+ self.concurrent_result_2 = "Mixed concurrent result: test2"
+ self.final_response_text = "Final response after mixed execution"
+ self.final_text_events = [
+ {
+ "type": "MODEL_CALL_START",
+ "model_name": "mock-model",
+ },
+ {
+ "type": "TEXT_BLOCK_START",
+ "block_id": AnyString(),
+ },
+ {
+ "type": "TEXT_BLOCK_DELTA",
+ "block_id": AnyString(),
+ "delta": self.final_response_text,
+ },
+ {
+ "type": "TEXT_BLOCK_END",
+ "block_id": AnyString(),
+ },
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ ]
+ self.final_mock_responses = [
+ ChatResponse(
+ content=[TextBlock(text=self.final_response_text)],
+ is_last=False,
+ usage=None,
+ ),
+ ChatResponse(
+ content=[TextBlock(text=self.final_response_text)],
+ is_last=True,
+ usage=None,
+ ),
+ ]
+
+ def _get_event_base(self, reply_id: str) -> dict:
+ """Get the dict with the basic fields for event assertion."""
+ return {
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "reply_id": reply_id,
+ }
+
+ def _get_msg_base(self) -> dict:
+ """Get the dict with the basic fields for message assertion."""
+ return {
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "metadata": {},
+ "name": "Friday",
+ "role": "assistant",
+ }
+
+ def _get_tool_call_events(
+ self,
+ id: str,
+ name: str,
+ delta: str,
+ ) -> list[dict]:
+ """Helper method to get the expected tool call events."""
+ return [
+ {
+ "type": "TOOL_CALL_START",
+ "tool_call_id": id,
+ "tool_call_name": name,
+ },
+ {
+ "type": "TOOL_CALL_DELTA",
+ "tool_call_id": id,
+ "delta": delta,
+ },
+ {
+ "type": "TOOL_CALL_END",
+ "tool_call_id": id,
+ },
+ ]
+
+ def _get_tool_result_events(
+ self,
+ id: str,
+ result: str,
+ state: str = "success",
+ ) -> list[dict]:
+ """Helper method to get the expected tool result events."""
+ return [
+ {
+ "type": "TOOL_RESULT_TEXT_DELTA",
+ "tool_call_id": id,
+ "delta": result,
+ },
+ {
+ "type": "TOOL_RESULT_END",
+ "tool_call_id": id,
+ "state": state,
+ },
+ ]
+
+ def _get_require_user_confirm_event(
+ self,
+ reply_id: str,
+ id: str,
+ name: str,
+ tool_input: str,
+ ) -> dict:
+ """Helper method to get the expected user confirmation event."""
+ return {
+ "type": "REQUIRE_USER_CONFIRM",
+ "reply_id": reply_id,
+ "tool_calls": [
+ {
+ "type": "tool_call",
+ "id": id,
+ "name": name,
+ "input": tool_input,
+ "state": "asking",
+ },
+ ],
+ }
+
+ def _get_require_external_execution_events(
+ self,
+ reply_id: str,
+ id: str,
+ name: str,
+ tool_input: str,
+ ) -> list[dict]:
+ """Helper method to get the expected external execution events."""
+ return [
+ {
+ "type": "TOOL_RESULT_START",
+ "tool_call_id": id,
+ "tool_call_name": name,
+ },
+ {
+ "type": "REQUIRE_EXTERNAL_EXECUTION",
+ "reply_id": reply_id,
+ "tool_calls": [
+ {
+ "type": "tool_call",
+ "id": id,
+ "name": name,
+ "input": tool_input,
+ "state": "submitted",
+ },
+ ],
+ },
+ ]
+
+ def _get_tool_call_block(
+ self,
+ id: str,
+ name: str,
+ tool_input: str,
+ ) -> ToolCallBlock:
+ """Build a tool call block."""
+ return ToolCallBlock(id=id, name=name, input=tool_input)
+
+ def _get_tool_result_block(
+ self,
+ id: str,
+ name: str,
+ result: str,
+ state: ToolResultState = ToolResultState.SUCCESS,
+ ) -> ToolResultBlock:
+ """Build a tool result block."""
+ return ToolResultBlock(
+ id=id,
+ name=name,
+ output=[TextBlock(text=result)],
+ state=state,
+ )
+
+ def _get_confirm_result(
+ self,
+ id: str,
+ name: str,
+ tool_input: str,
+ ) -> ConfirmResult:
+ """Build a confirmation result."""
+ return ConfirmResult(
+ confirmed=True,
+ tool_call=self._get_tool_call_block(id, name, tool_input),
+ )
+
+ def _build_tool_calls(
+ self,
+ tool_calls: list[tuple[str, str, str]],
+ ) -> list[ToolCallBlock]:
+ """Build tool call blocks for mock model responses."""
+ return [
+ self._get_tool_call_block(id, name, tool_input)
+ for id, name, tool_input in tool_calls
+ ]
+
+ def _set_model_tool_call_responses(
+ self,
+ tool_calls: list[tuple[str, str, str]],
+ ) -> None:
+ """Set mock model responses that emit tool calls then final text."""
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=self._build_tool_calls(tool_calls),
+ is_last=False,
+ usage=None,
+ ),
+ ChatResponse(
+ content=self._build_tool_calls(tool_calls),
+ is_last=True,
+ usage=None,
+ ),
+ ],
+ self.final_mock_responses,
+ ],
+ )
+
+ async def test_single_user_confirmation_and_external_execution(
+ self,
+ ) -> None:
+ """Test one tool call that needs confirmation and external
+ execution."""
+ mixed_tool = MockMixedSequentialTool()
+ self.agent.toolkit.tools[mixed_tool.name] = RegisteredTool(
+ tool=mixed_tool,
+ group="basic",
+ )
+
+ self._set_model_tool_call_responses(
+ [
+ (
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content=self.user_input_text),
+ ):
+ events.append(event.model_dump())
+
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+ basic_dict = self._get_event_base(reply_id)
+ msg_base = self._get_msg_base()
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ *self._get_tool_call_events(
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ ),
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ self._get_require_user_confirm_event(
+ reply_id,
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ ),
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "asking",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ user_confirm_event = UserConfirmResultEvent(
+ reply_id=reply_id,
+ confirm_results=[
+ self._get_confirm_result(
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(event=user_confirm_event):
+ events.append(event.model_dump())
+
+ expected_events_resume = self._get_require_external_execution_events(
+ reply_id,
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ )
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_resume],
+ )
+
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "submitted",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ external_result_event = ExternalExecutionResultEvent(
+ reply_id=reply_id,
+ execution_results=[
+ self._get_tool_result_block(
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.sequential_result_1,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(
+ event=external_result_event,
+ ):
+ events.append(event.model_dump())
+
+ expected_events_after_result = [
+ *self._get_tool_result_events(
+ self.tool_call_id_1,
+ self.sequential_result_1,
+ ),
+ *self.final_text_events,
+ {"type": "REPLY_END", "session_id": session_id},
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_after_result],
+ )
+
+ expected_context_final = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.sequential_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.sequential_result_1,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.final_response_text,
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context_final = [
+ {**msg_base, **_} for _ in expected_context_final
+ ]
+ self.assertListEqual(context_dicts, expected_context_final)
+
+ async def test_sequential_user_confirmation_and_external_execution(
+ self,
+ ) -> None:
+ """Test sequential tool calls that need confirmation and external
+ execution."""
+ mixed_tool = MockMixedSequentialTool()
+ self.agent.toolkit.tools[mixed_tool.name] = RegisteredTool(
+ tool=mixed_tool,
+ group="basic",
+ )
+
+ self._set_model_tool_call_responses(
+ [
+ (
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ ),
+ (
+ self.tool_call_id_2,
+ self.sequential_tool_name,
+ self.tool_input_2,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content=self.user_input_text),
+ ):
+ events.append(event.model_dump())
+
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+ basic_dict = self._get_event_base(reply_id)
+ msg_base = self._get_msg_base()
+ tool_call_1_events = self._get_tool_call_events(
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ )
+ tool_call_2_events = self._get_tool_call_events(
+ self.tool_call_id_2,
+ self.sequential_tool_name,
+ self.tool_input_2,
+ )
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ *tool_call_1_events[:2],
+ *tool_call_2_events[:2],
+ tool_call_1_events[2],
+ tool_call_2_events[2],
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ self._get_require_user_confirm_event(
+ reply_id,
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ ),
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "asking",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_2,
+ "state": "pending",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ user_confirm_event = UserConfirmResultEvent(
+ reply_id=reply_id,
+ confirm_results=[
+ self._get_confirm_result(
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(event=user_confirm_event):
+ events.append(event.model_dump())
+
+ expected_events_resume = self._get_require_external_execution_events(
+ reply_id,
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ )
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_resume],
+ )
+
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "submitted",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_2,
+ "state": "pending",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ external_result_event = ExternalExecutionResultEvent(
+ reply_id=reply_id,
+ execution_results=[
+ self._get_tool_result_block(
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.sequential_result_1,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(
+ event=external_result_event,
+ ):
+ events.append(event.model_dump())
+
+ expected_events_after_first_result = [
+ *self._get_tool_result_events(
+ self.tool_call_id_1,
+ self.sequential_result_1,
+ ),
+ self._get_require_user_confirm_event(
+ reply_id,
+ self.tool_call_id_2,
+ self.sequential_tool_name,
+ self.tool_input_2,
+ ),
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_after_first_result],
+ )
+
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "finished",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_2,
+ "state": "asking",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.sequential_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.sequential_result_1,
+ },
+ ],
+ "state": "success",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ user_confirm_event = UserConfirmResultEvent(
+ reply_id=reply_id,
+ confirm_results=[
+ self._get_confirm_result(
+ self.tool_call_id_2,
+ self.sequential_tool_name,
+ self.tool_input_2,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(event=user_confirm_event):
+ events.append(event.model_dump())
+
+ expected_events_after_second_confirm = (
+ self._get_require_external_execution_events(
+ reply_id,
+ self.tool_call_id_2,
+ self.sequential_tool_name,
+ self.tool_input_2,
+ )
+ )
+ self.assertListEqual(
+ events,
+ [
+ {**basic_dict, **_}
+ for _ in expected_events_after_second_confirm
+ ],
+ )
+
+ external_result_event = ExternalExecutionResultEvent(
+ reply_id=reply_id,
+ execution_results=[
+ self._get_tool_result_block(
+ self.tool_call_id_2,
+ self.sequential_tool_name,
+ self.sequential_result_2,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(
+ event=external_result_event,
+ ):
+ events.append(event.model_dump())
+
+ expected_events_after_second_result = [
+ *self._get_tool_result_events(
+ self.tool_call_id_2,
+ self.sequential_result_2,
+ ),
+ *self.final_text_events,
+ {"type": "REPLY_END", "session_id": session_id},
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_after_second_result],
+ )
+
+ expected_context_final = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "finished",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_2,
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.sequential_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.sequential_result_1,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.sequential_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.sequential_result_2,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.final_response_text,
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context_final = [
+ {**msg_base, **_} for _ in expected_context_final
+ ]
+ self.assertListEqual(context_dicts, expected_context_final)
+
+ async def test_concurrent_user_confirmation_and_external_execution(
+ self,
+ ) -> None:
+ """Test concurrent tool calls that need confirmation and external
+ execution."""
+ mixed_tool = MockMixedConcurrentTool()
+ self.agent.toolkit.tools[mixed_tool.name] = RegisteredTool(
+ tool=mixed_tool,
+ group="basic",
+ )
+
+ self._set_model_tool_call_responses(
+ [
+ (
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.tool_input_1,
+ ),
+ (
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.tool_input_2,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content=self.user_input_text),
+ ):
+ events.append(event.model_dump())
+
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+ basic_dict = self._get_event_base(reply_id)
+ msg_base = self._get_msg_base()
+ tool_call_1_events = self._get_tool_call_events(
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.tool_input_1,
+ )
+ tool_call_2_events = self._get_tool_call_events(
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.tool_input_2,
+ )
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ *tool_call_1_events[:2],
+ *tool_call_2_events[:2],
+ tool_call_1_events[2],
+ tool_call_2_events[2],
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ self._get_require_user_confirm_event(
+ reply_id,
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.tool_input_1,
+ ),
+ self._get_require_user_confirm_event(
+ reply_id,
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.tool_input_2,
+ ),
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_1,
+ "state": "asking",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_2,
+ "state": "asking",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ user_confirm_event = UserConfirmResultEvent(
+ reply_id=reply_id,
+ confirm_results=[
+ self._get_confirm_result(
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.tool_input_1,
+ ),
+ self._get_confirm_result(
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.tool_input_2,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(event=user_confirm_event):
+ events.append(event.model_dump())
+
+ self.assertEqual(len(events), 4)
+ expected_tool_events = {
+ self.tool_call_id_1: [
+ {**basic_dict, **_}
+ for _ in self._get_require_external_execution_events(
+ reply_id,
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.tool_input_1,
+ )
+ ],
+ self.tool_call_id_2: [
+ {**basic_dict, **_}
+ for _ in self._get_require_external_execution_events(
+ reply_id,
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.tool_input_2,
+ )
+ ],
+ }
+ for tool_call_id, expected_tool_event in expected_tool_events.items():
+ self.assertListEqual(
+ [
+ event
+ for event in events
+ if event.get("tool_call_id") == tool_call_id
+ or (
+ event["type"] == "REQUIRE_EXTERNAL_EXECUTION"
+ and event["tool_calls"][0]["id"] == tool_call_id
+ )
+ ],
+ expected_tool_event,
+ )
+
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_1,
+ "state": "submitted",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_2,
+ "state": "submitted",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ external_result_event = ExternalExecutionResultEvent(
+ reply_id=reply_id,
+ execution_results=[
+ self._get_tool_result_block(
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.concurrent_result_1,
+ ),
+ self._get_tool_result_block(
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.concurrent_result_2,
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(
+ event=external_result_event,
+ ):
+ events.append(event.model_dump())
+
+ expected_events_after_result = [
+ *self._get_tool_result_events(
+ self.tool_call_id_1,
+ self.concurrent_result_1,
+ ),
+ *self._get_tool_result_events(
+ self.tool_call_id_2,
+ self.concurrent_result_2,
+ ),
+ *self.final_text_events,
+ {"type": "REPLY_END", "session_id": session_id},
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_after_result],
+ )
+
+ expected_context_final = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_1,
+ "state": "finished",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_2,
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.concurrent_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.concurrent_result_1,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.concurrent_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.concurrent_result_2,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.final_response_text,
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context_final = [
+ {**msg_base, **_} for _ in expected_context_final
+ ]
+ self.assertListEqual(context_dicts, expected_context_final)
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
diff --git a/tests/hitl_user_confirmation_test.py b/tests/hitl_user_confirmation_test.py
new file mode 100644
index 000000000..723bbc971
--- /dev/null
+++ b/tests/hitl_user_confirmation_test.py
@@ -0,0 +1,1291 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=redefined-builtin
+"""Test the user confirmation events in the agent class."""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+from utils import AnyString, MockModel
+
+from agentscope.event._event import ConfirmResult
+from agentscope.agent import Agent
+from agentscope.model import ChatResponse
+from agentscope.tool import (
+ ToolBase,
+ Toolkit,
+ ToolChunk,
+ PermissionDecision,
+ PermissionBehavior,
+ PermissionContext,
+)
+from agentscope.message import (
+ TextBlock,
+ ToolCallBlock,
+ UserMsg,
+)
+from agentscope.tool._types import RegisteredTool
+from agentscope.event import UserConfirmResultEvent
+
+
+class MockUserConfirmSequentialTool(ToolBase):
+ """A mock tool that requires user confirmation (sequential)."""
+
+ name: str = "mock_user_confirm_sequential_tool"
+ description: str = "A mock user confirm sequential tool for testing"
+ input_schema: dict[str, Any] = {
+ "type": "object",
+ "properties": {
+ "input": {"type": "string", "description": "Input string"},
+ },
+ "required": ["input"],
+ }
+ is_concurrency_safe: bool = False
+ is_read_only: bool = False
+ is_external_tool: bool = False
+ is_mcp: bool = False
+
+ async def check_permissions(
+ self,
+ tool_input: dict[str, Any],
+ context: PermissionContext,
+ ) -> PermissionDecision:
+ """Check permissions for the tool usage."""
+ return PermissionDecision(
+ behavior=PermissionBehavior.ASK,
+ decision_reason="Mock tool requires user confirmation",
+ message="Mock tool requires user confirmation",
+ )
+
+ async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+ """Execute the tool."""
+ return ToolChunk(
+ content=[
+ TextBlock(text=f"User confirm sequential result: {input}"),
+ ],
+ )
+
+
+class MockUserConfirmConcurrentTool(ToolBase):
+ """A mock tool that requires user confirmation (concurrent)."""
+
+ name: str = "mock_user_confirm_concurrent_tool"
+ description: str = "A mock user confirm concurrent tool for testing"
+ input_schema: dict[str, Any] = {
+ "type": "object",
+ "properties": {
+ "input": {"type": "string", "description": "Input string"},
+ },
+ "required": ["input"],
+ }
+ is_concurrency_safe: bool = True
+ is_read_only: bool = False
+ is_external_tool: bool = False
+ is_mcp: bool = False
+
+ async def check_permissions(
+ self,
+ tool_input: dict[str, Any],
+ context: PermissionContext,
+ ) -> PermissionDecision:
+ """Check permissions for the tool usage."""
+ return PermissionDecision(
+ behavior=PermissionBehavior.ASK,
+ decision_reason="Mock tool requires user confirmation",
+ message="Mock tool requires user confirmation",
+ )
+
+ async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+ """Execute the tool."""
+ return ToolChunk(
+ content=[
+ TextBlock(text=f"User confirm concurrent result: {input}"),
+ ],
+ )
+
+
+class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
+ """Test the user confirmation events in the agent class."""
+
+ def _get_tool_call_events(
+ self,
+ id: str,
+ name: str,
+ delta: str,
+ ) -> list[dict]:
+ """Helper method to get the expected tool call events."""
+ return [
+ {
+ "type": "TOOL_CALL_START",
+ "tool_call_id": id,
+ "tool_call_name": name,
+ },
+ {
+ "type": "TOOL_CALL_DELTA",
+ "tool_call_id": id,
+ "delta": delta,
+ },
+ {
+ "type": "TOOL_CALL_END",
+ "tool_call_id": id,
+ },
+ ]
+
+ def _get_tool_result_events(
+ self,
+ id: str,
+ name: str,
+ result: str,
+ ) -> list[dict]:
+ """Helper method to get the expected tool result events."""
+ return [
+ {
+ "type": "TOOL_RESULT_START",
+ "tool_call_id": id,
+ "tool_call_name": name,
+ },
+ {
+ "type": "TOOL_RESULT_TEXT_DELTA",
+ "tool_call_id": id,
+ "delta": result,
+ },
+ {
+ "type": "TOOL_RESULT_END",
+ "tool_call_id": id,
+ "state": "success",
+ },
+ ]
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.model = MockModel()
+ self.agent = Agent(
+ name="Friday",
+ system_prompt="You are a helpful assistant.",
+ model=self.model,
+ toolkit=Toolkit(),
+ )
+ self.tool_call_id_1 = "tool_call_1"
+ self.tool_call_id_2 = "tool_call_2"
+ self.user_input_text = "Test"
+ self.tool_input_1 = '{"input": "test1"}'
+ self.tool_input_2 = '{"input": "test2"}'
+ self.sequential_tool_name = "mock_user_confirm_sequential_tool"
+ self.concurrent_tool_name = "mock_user_confirm_concurrent_tool"
+ self.sequential_result_1 = "User confirm sequential result: test1"
+ self.sequential_result_2 = "User confirm sequential result: test2"
+ self.concurrent_result_1 = "User confirm concurrent result: test1"
+ self.concurrent_result_2 = "User confirm concurrent result: test2"
+ self.final_response_text = "Result 1"
+ self.final_text_events = [
+ {
+ "type": "MODEL_CALL_START",
+ "model_name": "mock-model",
+ },
+ {
+ "type": "TEXT_BLOCK_START",
+ "block_id": AnyString(),
+ },
+ {
+ "type": "TEXT_BLOCK_DELTA",
+ "block_id": AnyString(),
+ "delta": self.final_response_text,
+ },
+ {
+ "type": "TEXT_BLOCK_END",
+ "block_id": AnyString(),
+ },
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ ]
+
+ self.final_mock_responses = [
+ ChatResponse(
+ content=[
+ TextBlock(text=self.final_response_text),
+ ],
+ is_last=False,
+ ),
+ ChatResponse(
+ content=[
+ TextBlock(text=self.final_response_text),
+ ],
+ is_last=True,
+ ),
+ ]
+
+ def _get_event_base(self, reply_id: str) -> dict:
+ """Get the dict with the basic fields for event assertion."""
+ return {
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "reply_id": reply_id,
+ }
+
+ def _get_msg_base(self) -> dict:
+ """Get the dict with the basic fields for message assertion."""
+ return {
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "metadata": {},
+ "name": "Friday",
+ "role": "assistant",
+ }
+
+ async def test_single_user_confirmation(self) -> None:
+ """Test single user confirmation tool call.
+
+ The agent should:
+ 1. Generate a tool call that requires user confirmation
+ 2. Emit REQUIRE_USER_CONFIRM event and pause
+ 3. Resume when UserConfirmResultEvent is provided
+ 4. Execute the tool and continue
+ """
+ # Register user confirm tool
+ confirm_tool = MockUserConfirmSequentialTool()
+ self.agent.toolkit.tools[confirm_tool.name] = RegisteredTool(
+ tool=confirm_tool,
+ group="basic",
+ )
+
+ # Set up mock response with tool call (no final text response)
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.sequential_tool_name,
+ input=self.tool_input_1,
+ ),
+ ],
+ is_last=False,
+ ),
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.sequential_tool_name,
+ input=self.tool_input_1,
+ ),
+ ],
+ is_last=True,
+ ),
+ ],
+ self.final_mock_responses,
+ ],
+ )
+
+ # First call: collect events until REQUIRE_USER_CONFIRM
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content=self.user_input_text),
+ ):
+ events.append(event.model_dump())
+
+ # Verify events
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ *self._get_tool_call_events(
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ ),
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ {
+ "type": "REQUIRE_USER_CONFIRM",
+ "reply_id": reply_id,
+ "tool_calls": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "asking",
+ },
+ ],
+ },
+ ]
+
+ basic_dict = self._get_event_base(reply_id)
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ # Assert context after first call
+ msg_base = self._get_msg_base()
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "asking",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ # Create user confirmation result event
+ user_confirm_event = UserConfirmResultEvent(
+ reply_id=reply_id,
+ confirm_results=[
+ ConfirmResult(
+ confirmed=True,
+ tool_call=ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.sequential_tool_name,
+ input=self.tool_input_1,
+ ),
+ ),
+ ],
+ )
+
+ # Second call: resume with user confirmation result
+ events = []
+ async for event in self.agent.reply_stream(event=user_confirm_event):
+ events.append(event.model_dump())
+
+ # Verify events after resumption
+ expected_events_resume = [
+ *self._get_tool_result_events(
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.sequential_result_1,
+ ),
+ *self.final_text_events,
+ {"type": "REPLY_END", "session_id": session_id},
+ ]
+
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_resume],
+ )
+
+ # Assert final context
+ expected_context_final = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.sequential_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.sequential_result_1,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.final_response_text,
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context_final = [
+ {**msg_base, **_} for _ in expected_context_final
+ ]
+ self.assertListEqual(context_dicts, expected_context_final)
+
+ async def test_sequential_user_confirmation(self) -> None:
+ """Test multiple user confirmation tool calls in sequential execution.
+
+ The agent should:
+ 1. Generate multiple tool calls that require user confirmation
+ 2. All tools have is_concurrent_safe=False (sequential)
+ 3. Emit REQUIRE_USER_CONFIRM event and pause
+ 4. Resume when UserConfirmResultEvent is provided
+ 5. Execute the tools and continue
+ """
+ # Register user confirm sequential tool
+ confirm_tool = MockUserConfirmSequentialTool()
+ self.agent.toolkit.tools[confirm_tool.name] = RegisteredTool(
+ tool=confirm_tool,
+ group="basic",
+ )
+
+ # Set up mock response with multiple tool calls
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.sequential_tool_name,
+ input=self.tool_input_1,
+ ),
+ ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.sequential_tool_name,
+ input=self.tool_input_2,
+ ),
+ ],
+ is_last=False,
+ usage=None,
+ ),
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.sequential_tool_name,
+ input=self.tool_input_1,
+ ),
+ ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.sequential_tool_name,
+ input=self.tool_input_2,
+ ),
+ ],
+ is_last=True,
+ usage=None,
+ ),
+ ],
+ self.final_mock_responses,
+ ],
+ )
+
+ # First call: collect events until REQUIRE_USER_CONFIRM
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content=self.user_input_text),
+ ):
+ events.append(event.model_dump())
+
+ # Verify events
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+
+ tool_call_1_events = self._get_tool_call_events(
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.tool_input_1,
+ )
+ tool_call_2_events = self._get_tool_call_events(
+ self.tool_call_id_2,
+ self.sequential_tool_name,
+ self.tool_input_2,
+ )
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ *tool_call_1_events[:2],
+ *tool_call_2_events[:2],
+ tool_call_1_events[2],
+ tool_call_2_events[2],
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ {
+ "type": "REQUIRE_USER_CONFIRM",
+ "reply_id": reply_id,
+ "tool_calls": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "asking",
+ },
+ ],
+ },
+ ]
+
+ basic_dict = self._get_event_base(reply_id)
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ # Assert context after first call
+ msg_base = self._get_msg_base()
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "asking",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_2,
+ "state": "pending",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ # Create user confirmation result event
+ user_confirm_event = UserConfirmResultEvent(
+ reply_id=reply_id,
+ confirm_results=[
+ ConfirmResult(
+ confirmed=True,
+ tool_call=ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.sequential_tool_name,
+ input=self.tool_input_1,
+ ),
+ ),
+ ],
+ )
+
+ # resume with user confirmation result
+ events = []
+ async for event in self.agent.reply_stream(event=user_confirm_event):
+ events.append(event.model_dump())
+
+ # Verify events after resumption (sequential execution)
+ expected_events_resume = [
+ *self._get_tool_result_events(
+ self.tool_call_id_1,
+ self.sequential_tool_name,
+ self.sequential_result_1,
+ ),
+ {
+ "type": "REQUIRE_USER_CONFIRM",
+ "tool_calls": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_2,
+ "state": "asking",
+ },
+ ],
+ },
+ ]
+
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_resume],
+ )
+
+ # Confirm the second tool call
+ user_confirm_event = UserConfirmResultEvent(
+ reply_id=reply_id,
+ confirm_results=[
+ ConfirmResult(
+ confirmed=True,
+ tool_call=ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.sequential_tool_name,
+ input=self.tool_input_2,
+ ),
+ ),
+ ],
+ )
+
+ # Second call: resume with user confirmation result
+ events = []
+ async for event in self.agent.reply_stream(event=user_confirm_event):
+ events.append(event.model_dump())
+
+ expected_events_resume_2 = [
+ *self._get_tool_result_events(
+ self.tool_call_id_2,
+ self.sequential_tool_name,
+ self.sequential_result_2,
+ ),
+ *self.final_text_events,
+ {"type": "REPLY_END", "session_id": session_id},
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events_resume_2],
+ )
+
+ # Assert final context
+ expected_context_final = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_1,
+ "state": "finished",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.sequential_tool_name,
+ "input": self.tool_input_2,
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.sequential_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.sequential_result_1,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.sequential_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.sequential_result_2,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.final_response_text,
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context_final = [
+ {**msg_base, **_} for _ in expected_context_final
+ ]
+ self.assertListEqual(context_dicts, expected_context_final)
+
+ async def test_concurrent_user_confirmation(self) -> None:
+ """Test multiple user confirmation tool calls in concurrent execution.
+
+ The agent should:
+ 1. Generate multiple tool calls that require user confirmation
+ 2. All tools have is_concurrent_safe=True (concurrent)
+ 3. Emit REQUIRE_USER_CONFIRM event and pause
+ 4. Resume when UserConfirmResultEvent is provided
+ 5. Execute the tools and continue
+ """
+ # Register user confirm concurrent tool
+ confirm_tool = MockUserConfirmConcurrentTool()
+ self.agent.toolkit.tools[confirm_tool.name] = RegisteredTool(
+ tool=confirm_tool,
+ group="basic",
+ )
+
+ # Set up mock response with multiple tool calls
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_1,
+ ),
+ ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_2,
+ ),
+ ],
+ is_last=False,
+ ),
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_1,
+ ),
+ ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_2,
+ ),
+ ],
+ is_last=True,
+ ),
+ ],
+ self.final_mock_responses,
+ ],
+ )
+
+ # First call: collect events until REQUIRE_USER_CONFIRM
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content=self.user_input_text),
+ ):
+ events.append(event.model_dump())
+
+ # Verify events
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+
+ tool_call_1_events = self._get_tool_call_events(
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.tool_input_1,
+ )
+ tool_call_2_events = self._get_tool_call_events(
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.tool_input_2,
+ )
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ *tool_call_1_events[:2],
+ *tool_call_2_events[:2],
+ tool_call_1_events[2],
+ tool_call_2_events[2],
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ {
+ "type": "REQUIRE_USER_CONFIRM",
+ "reply_id": reply_id,
+ "tool_calls": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_1,
+ "state": "asking",
+ },
+ ],
+ },
+ {
+ "type": "REQUIRE_USER_CONFIRM",
+ "reply_id": reply_id,
+ "tool_calls": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_2,
+ "state": "asking",
+ },
+ ],
+ },
+ ]
+
+ basic_dict = self._get_event_base(reply_id)
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ # Assert context after first call
+ msg_base = self._get_msg_base()
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_1,
+ "state": "asking",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_2,
+ "state": "asking",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ # Create user confirmation result event
+ user_confirm_event = UserConfirmResultEvent(
+ reply_id=reply_id,
+ confirm_results=[
+ ConfirmResult(
+ confirmed=True,
+ tool_call=ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_1,
+ ),
+ ),
+ ],
+ )
+
+ # resume with user confirmation result
+ events = []
+ async for event in self.agent.reply_stream(event=user_confirm_event):
+ events.append(event.model_dump())
+
+ # Verify events for tool call 1 after resumption
+ expected_events = [
+ *self._get_tool_result_events(
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.concurrent_result_1,
+ ),
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ # The second tool call
+ user_confirm_event = UserConfirmResultEvent(
+ reply_id=reply_id,
+ confirm_results=[
+ ConfirmResult(
+ confirmed=True,
+ tool_call=ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_2,
+ ),
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(event=user_confirm_event):
+ events.append(event.model_dump())
+
+ expected_events = [
+ *self._get_tool_result_events(
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.concurrent_result_2,
+ ),
+ *self.final_text_events,
+ {"type": "REPLY_END", "session_id": session_id},
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ # Assert final context
+ expected_context_final = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_1,
+ "state": "finished",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_2,
+ "state": "finished",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.concurrent_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.concurrent_result_1,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "tool_result",
+ "id": AnyString(),
+ "name": self.concurrent_tool_name,
+ "output": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.concurrent_result_2,
+ },
+ ],
+ "state": "success",
+ },
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.final_response_text,
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context_final = [
+ {**msg_base, **_} for _ in expected_context_final
+ ]
+ self.assertListEqual(context_dicts, expected_context_final)
+
+ async def test_concurrent_user_confirmation_in_single_event(self) -> None:
+ """Test concurrent user confirmation when two approvals arrive
+ together.
+
+ The agent should:
+ 1. Generate multiple tool calls that require user confirmation
+ 2. Pause in concurrent mode with two asking tool calls
+ 3. Resume when one UserConfirmResultEvent carries both confirmations
+ 4. Execute both tools and continue reasoning after both complete
+ """
+ confirm_tool = MockUserConfirmConcurrentTool()
+ self.agent.toolkit.tools[confirm_tool.name] = RegisteredTool(
+ tool=confirm_tool,
+ group="basic",
+ )
+
+ self.model.set_responses(
+ [
+ [
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_1,
+ ),
+ ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_2,
+ ),
+ ],
+ is_last=False,
+ ),
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_1,
+ ),
+ ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_2,
+ ),
+ ],
+ is_last=True,
+ ),
+ ],
+ self.final_mock_responses,
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(
+ UserMsg(name="user", content=self.user_input_text),
+ ):
+ events.append(event.model_dump())
+
+ session_id = self.agent.state.session_id
+ reply_id = self.agent.state.reply_id
+ basic_dict = self._get_event_base(reply_id)
+ msg_base = self._get_msg_base()
+
+ tool_call_1_events = self._get_tool_call_events(
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.tool_input_1,
+ )
+ tool_call_2_events = self._get_tool_call_events(
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.tool_input_2,
+ )
+
+ expected_events = [
+ {
+ "type": "REPLY_START",
+ "session_id": session_id,
+ "name": "Friday",
+ "role": "assistant",
+ },
+ {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+ *tool_call_1_events[:2],
+ *tool_call_2_events[:2],
+ tool_call_1_events[2],
+ tool_call_2_events[2],
+ {
+ "type": "MODEL_CALL_END",
+ "input_tokens": 0,
+ "output_tokens": 0,
+ },
+ {
+ "type": "REQUIRE_USER_CONFIRM",
+ "reply_id": reply_id,
+ "tool_calls": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_1,
+ "state": "asking",
+ },
+ ],
+ },
+ {
+ "type": "REQUIRE_USER_CONFIRM",
+ "reply_id": reply_id,
+ "tool_calls": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_2,
+ "state": "asking",
+ },
+ ],
+ },
+ ]
+ self.assertListEqual(
+ events,
+ [{**basic_dict, **_} for _ in expected_events],
+ )
+
+ expected_context = [
+ {
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ {
+ "content": [
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_1,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_1,
+ "state": "asking",
+ },
+ {
+ "type": "tool_call",
+ "id": self.tool_call_id_2,
+ "name": self.concurrent_tool_name,
+ "input": self.tool_input_2,
+ "state": "asking",
+ },
+ ],
+ },
+ ]
+ context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+ expected_context = [{**msg_base, **_} for _ in expected_context]
+ self.assertListEqual(context_dicts, expected_context)
+
+ user_confirm_event = UserConfirmResultEvent(
+ reply_id=reply_id,
+ confirm_results=[
+ ConfirmResult(
+ confirmed=True,
+ tool_call=ToolCallBlock(
+ id=self.tool_call_id_1,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_1,
+ ),
+ ),
+ ConfirmResult(
+ confirmed=True,
+ tool_call=ToolCallBlock(
+ id=self.tool_call_id_2,
+ name=self.concurrent_tool_name,
+ input=self.tool_input_2,
+ ),
+ ),
+ ],
+ )
+
+ events = []
+ async for event in self.agent.reply_stream(event=user_confirm_event):
+ events.append(event.model_dump())
+
+ tool_events = events[:6]
+ final_events = events[6:]
+ self.assertEqual(len(tool_events), 6)
+
+ expected_tool_events = {
+ self.tool_call_id_1: [
+ {**basic_dict, **_}
+ for _ in self._get_tool_result_events(
+ self.tool_call_id_1,
+ self.concurrent_tool_name,
+ self.concurrent_result_1,
+ )
+ ],
+ self.tool_call_id_2: [
+ {**basic_dict, **_}
+ for _ in self._get_tool_result_events(
+ self.tool_call_id_2,
+ self.concurrent_tool_name,
+ self.concurrent_result_2,
+ )
+ ],
+ }
+ for tool_call_id, expected_tool_event in expected_tool_events.items():
+ self.assertListEqual(
+ [
+ event
+ for event in tool_events
+ if event["tool_call_id"] == tool_call_id
+ ],
+ expected_tool_event,
+ )
+
+ expected_final_events = [
+ *self.final_text_events,
+ {"type": "REPLY_END", "session_id": session_id},
+ ]
+ self.assertListEqual(
+ final_events,
+ [{**basic_dict, **_} for _ in expected_final_events],
+ )
+
+ self.assertEqual(len(self.agent.state.context), 2)
+ self.assertEqual(
+ self.agent.state.context[0].model_dump(),
+ {
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "metadata": {},
+ "name": "user",
+ "role": "user",
+ "content": self.user_input_text,
+ },
+ )
+
+ assistant_msg = self.agent.state.context[-1]
+ self.assertEqual(
+ [
+ _.model_dump()["state"]
+ for _ in assistant_msg.get_content_blocks("tool_call")
+ ],
+ ["finished", "finished"],
+ )
+ self.assertEqual(
+ [
+ _.model_dump()["id"]
+ for _ in assistant_msg.get_content_blocks("tool_call")
+ ],
+ [self.tool_call_id_1, self.tool_call_id_2],
+ )
+ self.assertEqual(
+ {
+ (
+ _.model_dump()["name"],
+ _.model_dump()["state"],
+ _.output[0].text,
+ )
+ for _ in assistant_msg.get_content_blocks("tool_result")
+ },
+ {
+ (
+ self.concurrent_tool_name,
+ "success",
+ self.concurrent_result_1,
+ ),
+ (
+ self.concurrent_tool_name,
+ "success",
+ self.concurrent_result_2,
+ ),
+ },
+ )
+ self.assertEqual(
+ [_.text for _ in assistant_msg.get_content_blocks("text")],
+ [self.final_response_text],
+ )
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
diff --git a/tests/permission_engine_test.py b/tests/permission_engine_test.py
index ccbeb72c8..2645a80fd 100644
--- a/tests/permission_engine_test.py
+++ b/tests/permission_engine_test.py
@@ -1,6 +1,5 @@
# -*- coding: utf-8 -*-
"""Test cases for PermissionEngine."""
-import json
import sys
import unittest
from unittest.async_case import IsolatedAsyncioTestCase
@@ -17,7 +16,6 @@ from agentscope.tool import (
Read,
Edit,
)
-from agentscope.message import ToolCallBlock
class PermissionEngineRulePriorityTest(IsolatedAsyncioTestCase):
@@ -48,12 +46,10 @@ class PermissionEngineRulePriorityTest(IsolatedAsyncioTestCase):
),
)
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "git status"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "git status"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Deny should take precedence over allow
self.assertEqual(decision.behavior, PermissionBehavior.DENY)
@@ -78,12 +74,10 @@ class PermissionEngineRulePriorityTest(IsolatedAsyncioTestCase):
),
)
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "npm install"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "npm install"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Ask should take precedence over allow
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -116,12 +110,10 @@ class PermissionEngineRulePriorityTest(IsolatedAsyncioTestCase):
),
)
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "test command"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "test command"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Deny should win
self.assertEqual(decision.behavior, PermissionBehavior.DENY)
@@ -141,12 +133,10 @@ class PermissionEngineModeTest(IsolatedAsyncioTestCase):
engine = PermissionEngine(context)
# No rules added - should default to ALLOW in BYPASS mode
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "npm install"}),
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": "npm install"},
)
- decision = await engine.check_permission(tool_call, Bash())
# BYPASS mode should allow by default
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
@@ -167,12 +157,10 @@ class PermissionEngineModeTest(IsolatedAsyncioTestCase):
),
)
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "rm -rf /tmp"}),
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": "rm -rf /tmp"},
)
- decision = await engine.check_permission(tool_call, Bash())
# Deny rules have the highest priority, even in BYPASS mode
self.assertEqual(decision.behavior, PermissionBehavior.DENY)
@@ -185,12 +173,10 @@ class PermissionEngineModeTest(IsolatedAsyncioTestCase):
engine = PermissionEngine(context)
# Try to write to a dangerous file
- tool_call = ToolCallBlock(
- id="1",
- name="Write",
- input=json.dumps({"file_path": "/home/user/.bashrc"}),
+ decision = await engine.check_permission(
+ Write(),
+ {"file_path": "/home/user/.bashrc"},
)
- decision = await engine.check_permission(tool_call, Write())
# Safety checks are bypass-immune
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -201,12 +187,10 @@ class PermissionEngineModeTest(IsolatedAsyncioTestCase):
engine = PermissionEngine(context)
# No rules added, should default to ASK in DEFAULT mode
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "npm install"}),
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": "npm install"},
)
- decision = await engine.check_permission(tool_call, Bash())
# DONT_ASK mode should deny instead of ask
self.assertEqual(decision.behavior, PermissionBehavior.DENY)
@@ -226,30 +210,24 @@ class PermissionEngineModeTest(IsolatedAsyncioTestCase):
engine = PermissionEngine(context)
# Write tool within working directory
- tool_call = ToolCallBlock(
- id="1",
- name="Write",
- input=json.dumps({"file_path": "/tmp/project/file.txt"}),
+ decision = await engine.check_permission(
+ Write(),
+ {"file_path": "/tmp/project/file.txt"},
)
- decision = await engine.check_permission(tool_call, Write())
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
# Read tool within working directory
- tool_call = ToolCallBlock(
- id="2",
- name="Read",
- input=json.dumps({"file_path": "/tmp/project/file.txt"}),
+ decision = await engine.check_permission(
+ Read(),
+ {"file_path": "/tmp/project/file.txt"},
)
- decision = await engine.check_permission(tool_call, Read())
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
# Edit tool within working directory
- tool_call = ToolCallBlock(
- id="3",
- name="Edit",
- input=json.dumps({"file_path": "/tmp/project/file.txt"}),
+ decision = await engine.check_permission(
+ Edit(),
+ {"file_path": "/tmp/project/file.txt"},
)
- decision = await engine.check_permission(tool_call, Edit())
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
async def test_accept_edits_mode_outside_working_directory(self) -> None:
@@ -267,12 +245,10 @@ class PermissionEngineModeTest(IsolatedAsyncioTestCase):
engine = PermissionEngine(context)
# Edit tool outside working directory
- tool_call = ToolCallBlock(
- id="1",
- name="Edit",
- input=json.dumps({"file_path": "/home/user/file.txt"}),
+ decision = await engine.check_permission(
+ Edit(),
+ {"file_path": "/home/user/file.txt"},
)
- decision = await engine.check_permission(tool_call, Edit())
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -282,12 +258,10 @@ class PermissionEngineModeTest(IsolatedAsyncioTestCase):
engine = PermissionEngine(context)
# Read operation
- tool_call = ToolCallBlock(
- id="1",
- name="Read",
- input=json.dumps({"file_path": "/tmp/file.txt"}),
+ decision = await engine.check_permission(
+ Read(),
+ {"file_path": "/tmp/file.txt"},
)
- decision = await engine.check_permission(tool_call, Read())
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
@@ -297,12 +271,10 @@ class PermissionEngineModeTest(IsolatedAsyncioTestCase):
engine = PermissionEngine(context)
# Write operation
- tool_call = ToolCallBlock(
- id="1",
- name="Write",
- input=json.dumps({"file_path": "/tmp/file.txt"}),
+ decision = await engine.check_permission(
+ Write(),
+ {"file_path": "/tmp/file.txt"},
)
- decision = await engine.check_permission(tool_call, Write())
self.assertEqual(decision.behavior, PermissionBehavior.DENY)
@@ -331,39 +303,31 @@ class PermissionEngineBashRuleTest(IsolatedAsyncioTestCase):
)
# Test exact command
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "git"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "git"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
# Test command with arguments
- tool_call = ToolCallBlock(
- id="2",
- name="Bash",
- input=json.dumps({"command": "git status"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "git status"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
# Test command with multiple arguments
- tool_call = ToolCallBlock(
- id="3",
- name="Bash",
- input=json.dumps({"command": "git add ."}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "git add ."},
)
- decision = await self.engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
# Test non-matching command
- tool_call = ToolCallBlock(
- id="4",
- name="Bash",
- input=json.dumps({"command": "npm install"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "npm install"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
async def test_bash_substring_pattern_matching(self) -> None:
@@ -378,21 +342,17 @@ class PermissionEngineBashRuleTest(IsolatedAsyncioTestCase):
)
# Test command containing substring
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "npm install package"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "npm install package"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.DENY)
# Test command containing substring in different position
- tool_call = ToolCallBlock(
- id="2",
- name="Bash",
- input=json.dumps({"command": "pip install requests"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "pip install requests"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.DENY)
async def test_bash_multiple_rules(self) -> None:
@@ -415,30 +375,24 @@ class PermissionEngineBashRuleTest(IsolatedAsyncioTestCase):
)
# Test deny rule
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "rm -rf /tmp"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "rm -rf /tmp"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.DENY)
# Test allow rule
- tool_call = ToolCallBlock(
- id="2",
- name="Bash",
- input=json.dumps({"command": "git status"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "git status"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
# Test no matching rule
- tool_call = ToolCallBlock(
- id="3",
- name="Bash",
- input=json.dumps({"command": "npm install"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "npm install"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
async def asyncTearDown(self) -> None:
@@ -467,21 +421,17 @@ class PermissionEngineFileRuleTest(IsolatedAsyncioTestCase):
)
# Test matching file
- tool_call = ToolCallBlock(
- id="1",
- name="Read",
- input=json.dumps({"file_path": "test.py"}),
+ decision = await self.engine.check_permission(
+ Read(),
+ {"file_path": "test.py"},
)
- decision = await self.engine.check_permission(tool_call, Read())
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
# Test non-matching file
- tool_call = ToolCallBlock(
- id="2",
- name="Read",
- input=json.dumps({"file_path": "test.txt"}),
+ decision = await self.engine.check_permission(
+ Read(),
+ {"file_path": "test.txt"},
)
- decision = await self.engine.check_permission(tool_call, Read())
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
async def test_file_directory_pattern_matching(self) -> None:
@@ -496,12 +446,10 @@ class PermissionEngineFileRuleTest(IsolatedAsyncioTestCase):
)
# Test file in directory - glob pattern /tmp/** should match
- tool_call = ToolCallBlock(
- id="1",
- name="Edit",
- input=json.dumps({"file_path": "/tmp/test.txt"}),
+ decision = await self.engine.check_permission(
+ Edit(),
+ {"file_path": "/tmp/test.txt"},
)
- decision = await self.engine.check_permission(tool_call, Edit())
# Note: The current implementation uses fnmatch/pathlib matching
# /tmp/** may not match /tmp/test.txt depending on implementation
# This test verifies the actual behavior
@@ -511,24 +459,20 @@ class PermissionEngineFileRuleTest(IsolatedAsyncioTestCase):
)
# Test file in subdirectory
- tool_call = ToolCallBlock(
- id="2",
- name="Edit",
- input=json.dumps({"file_path": "/tmp/subdir/test.txt"}),
+ decision = await self.engine.check_permission(
+ Edit(),
+ {"file_path": "/tmp/subdir/test.txt"},
)
- decision = await self.engine.check_permission(tool_call, Edit())
self.assertIn(
decision.behavior,
[PermissionBehavior.ALLOW, PermissionBehavior.ASK],
)
# Test file outside directory
- tool_call = ToolCallBlock(
- id="3",
- name="Edit",
- input=json.dumps({"file_path": "/home/user/test.txt"}),
+ decision = await self.engine.check_permission(
+ Edit(),
+ {"file_path": "/home/user/test.txt"},
)
- decision = await self.engine.check_permission(tool_call, Edit())
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
async def asyncTearDown(self) -> None:
@@ -554,12 +498,10 @@ class PermissionEngineDangerousPathTest(IsolatedAsyncioTestCase):
"""Test that Write operations on dangerous files require
confirmation."""
# Try to write a dangerous file
- tool_call = ToolCallBlock(
- id="1",
- name="Write",
- input=json.dumps({"file_path": "/home/user/.bashrc"}),
+ decision = await self.engine.check_permission(
+ Write(),
+ {"file_path": "/home/user/.bashrc"},
)
- decision = await self.engine.check_permission(tool_call, Write())
# Should ask for confirmation (safety check)
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -568,12 +510,10 @@ class PermissionEngineDangerousPathTest(IsolatedAsyncioTestCase):
"""Test that Edit operations on dangerous files require
confirmation."""
# Try to edit a dangerous file
- tool_call = ToolCallBlock(
- id="1",
- name="Edit",
- input=json.dumps({"file_path": "/home/user/.gitconfig"}),
+ decision = await self.engine.check_permission(
+ Edit(),
+ {"file_path": "/home/user/.gitconfig"},
)
- decision = await self.engine.check_permission(tool_call, Edit())
# Should ask for confirmation (safety check)
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -583,12 +523,10 @@ class PermissionEngineDangerousPathTest(IsolatedAsyncioTestCase):
"""Test that Write operations in dangerous directories require
confirmation."""
# Try to write in a dangerous directory
- tool_call = ToolCallBlock(
- id="1",
- name="Write",
- input=json.dumps({"file_path": "/home/user/.ssh/config"}),
+ decision = await self.engine.check_permission(
+ Write(),
+ {"file_path": "/home/user/.ssh/config"},
)
- decision = await self.engine.check_permission(tool_call, Write())
# Should ask for confirmation (safety check)
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -597,12 +535,10 @@ class PermissionEngineDangerousPathTest(IsolatedAsyncioTestCase):
async def test_dangerous_path_in_bash_command(self) -> None:
"""Test that Bash commands on dangerous paths require confirmation."""
# Try to remove a dangerous file
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "rm /home/user/.bashrc"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "rm /home/user/.bashrc"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Should ask for confirmation (safety check)
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -615,12 +551,10 @@ class PermissionEngineDangerousPathTest(IsolatedAsyncioTestCase):
engine = PermissionEngine(context)
# Try to write a dangerous file in BYPASS mode
- tool_call = ToolCallBlock(
- id="1",
- name="Write",
- input=json.dumps({"file_path": "/home/user/.bashrc"}),
+ decision = await engine.check_permission(
+ Write(),
+ {"file_path": "/home/user/.bashrc"},
)
- decision = await engine.check_permission(tool_call, Write())
# Safety checks are bypass-immune
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -640,12 +574,10 @@ class PermissionEngineDangerousPathTest(IsolatedAsyncioTestCase):
engine = PermissionEngine(context)
# Try to write a dangerous file in working directory
- tool_call = ToolCallBlock(
- id="1",
- name="Write",
- input=json.dumps({"file_path": "/home/user/.bashrc"}),
+ decision = await engine.check_permission(
+ Write(),
+ {"file_path": "/home/user/.bashrc"},
)
- decision = await engine.check_permission(tool_call, Write())
# Should ask despite being in working directory
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -653,12 +585,10 @@ class PermissionEngineDangerousPathTest(IsolatedAsyncioTestCase):
async def test_safe_file_allows_write(self) -> None:
"""Test that Write operations on safe files work normally."""
# Try to write a safe file
- tool_call = ToolCallBlock(
- id="1",
- name="Write",
- input=json.dumps({"file_path": "/home/user/test.py"}),
+ decision = await self.engine.check_permission(
+ Write(),
+ {"file_path": "/home/user/test.py"},
)
- decision = await self.engine.check_permission(tool_call, Write())
# Should ask (no allow rule, but not blocked by safety check)
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -682,12 +612,10 @@ class PermissionEngineSuggestionTest(IsolatedAsyncioTestCase):
async def test_bash_suggestions(self) -> None:
"""Test suggestion generation for bash commands."""
# Use a non-read-only command to test suggestions
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "git commit -m 'test'"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "git commit -m 'test'"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Should ask (not read-only)
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -705,12 +633,10 @@ class PermissionEngineSuggestionTest(IsolatedAsyncioTestCase):
async def test_file_suggestions(self) -> None:
"""Test suggestion generation for file operations."""
- tool_call = ToolCallBlock(
- id="1",
- name="Read",
- input=json.dumps({"file_path": "/tmp/test.py"}),
+ decision = await self.engine.check_permission(
+ Read(),
+ {"file_path": "/tmp/test.py"},
)
- decision = await self.engine.check_permission(tool_call, Read())
# Should have suggestions
self.assertGreater(len(decision.suggested_rules), 0)
@@ -741,12 +667,10 @@ class PermissionEngineReadOnlyTest(IsolatedAsyncioTestCase):
async def test_git_status_is_read_only(self) -> None:
"""Test that git status is auto-allowed as read-only."""
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "git status"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "git status"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Should be allowed (read-only command)
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
@@ -754,36 +678,30 @@ class PermissionEngineReadOnlyTest(IsolatedAsyncioTestCase):
async def test_ls_is_read_only(self) -> None:
"""Test that ls is auto-allowed as read-only."""
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "ls -la"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "ls -la"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Should be allowed (read-only command)
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
async def test_cat_is_read_only(self) -> None:
"""Test that cat is auto-allowed as read-only."""
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "cat file.txt"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "cat file.txt"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Should be allowed (read-only command)
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
async def test_git_commit_is_not_read_only(self) -> None:
"""Test that git commit is not auto-allowed (not read-only)."""
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "git commit -m 'test'"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "git commit -m 'test'"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Should ask (not read-only)
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -792,12 +710,10 @@ class PermissionEngineReadOnlyTest(IsolatedAsyncioTestCase):
"""Test compound command with read-only and dangerous path o
perations."""
# ls is read-only, but rm ~/.bashrc is dangerous
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "ls -la && rm ~/.bashrc"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "ls -la && rm ~/.bashrc"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Should ask because of dangerous path (safety check is bypass-immune)
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -806,12 +722,10 @@ class PermissionEngineReadOnlyTest(IsolatedAsyncioTestCase):
async def test_compound_command_all_read_only(self) -> None:
"""Test compound command with all read-only operations."""
# Both ls and cat are read-only
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "ls -la && cat file.txt"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "ls -la && cat file.txt"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Should be allowed (all read-only)
self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
@@ -819,12 +733,10 @@ class PermissionEngineReadOnlyTest(IsolatedAsyncioTestCase):
async def test_compound_command_with_write_operation(self) -> None:
"""Test compound command with read-only and write operations."""
# ls is read-only, but git commit is not
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "ls -la && git commit -m 'test'"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "ls -la && git commit -m 'test'"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Should ask (contains non-read-only command)
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -832,12 +744,10 @@ class PermissionEngineReadOnlyTest(IsolatedAsyncioTestCase):
async def test_output_redirection_to_dangerous_path(self) -> None:
"""Test output redirection to dangerous path."""
# cat is read-only, but redirecting to ~/.bashrc is dangerous
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "cat file.txt > ~/.bashrc"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "cat file.txt > ~/.bashrc"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Should ask because of dangerous path in redirection
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -846,12 +756,10 @@ class PermissionEngineReadOnlyTest(IsolatedAsyncioTestCase):
async def test_output_redirection_to_safe_path(self) -> None:
"""Test output redirection to safe path."""
# cat is read-only, redirecting to safe path
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "cat file.txt > /tmp/output.txt"}),
+ decision = await self.engine.check_permission(
+ Bash(),
+ {"command": "cat file.txt > /tmp/output.txt"},
)
- decision = await self.engine.check_permission(tool_call, Bash())
# Should ask (redirection is not considered read-only)
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
@@ -876,12 +784,10 @@ class PermissionEngineSafetyCheckBypassImmuneTest(IsolatedAsyncioTestCase):
engine = PermissionEngine(context)
# Command substitution should be blocked even in BYPASS mode
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "ls $(rm -rf /)"}),
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": "ls $(rm -rf /)"},
)
- decision = await engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
self.assertIn("command_substitution", decision.message)
@@ -901,12 +807,10 @@ class PermissionEngineSafetyCheckBypassImmuneTest(IsolatedAsyncioTestCase):
)
# ls $(rm -rf /) should still be blocked despite allow rule for ls:*
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "ls $(rm -rf /)"}),
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": "ls $(rm -rf /)"},
)
- decision = await engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
self.assertIn("command_substitution", decision.message)
@@ -915,12 +819,10 @@ class PermissionEngineSafetyCheckBypassImmuneTest(IsolatedAsyncioTestCase):
context = PermissionContext(mode=PermissionMode.BYPASS)
engine = PermissionEngine(context)
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "rm -rf /"}),
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": "rm -rf /"},
)
- decision = await engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
# Can be blocked by either dangerous command pattern or dangerous
# removal path check
@@ -945,12 +847,10 @@ class PermissionEngineSafetyCheckBypassImmuneTest(IsolatedAsyncioTestCase):
)
# rm -rf / should still be blocked despite allow rule for rm:*
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "rm -rf /"}),
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": "rm -rf /"},
)
- decision = await engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
# Can be blocked by either dangerous command pattern or dangerous
# removal path check
@@ -964,12 +864,10 @@ class PermissionEngineSafetyCheckBypassImmuneTest(IsolatedAsyncioTestCase):
context = PermissionContext(mode=PermissionMode.BYPASS)
engine = PermissionEngine(context)
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "sed 's/old/new/e' file.txt"}),
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": "sed 's/old/new/e' file.txt"},
)
- decision = await engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
self.assertIn("safety", decision.decision_reason.lower())
@@ -978,11 +876,9 @@ class PermissionEngineSafetyCheckBypassImmuneTest(IsolatedAsyncioTestCase):
context = PermissionContext(mode=PermissionMode.BYPASS)
engine = PermissionEngine(context)
- tool_call = ToolCallBlock(
- id="1",
- name="Bash",
- input=json.dumps({"command": "rm ~/.bashrc"}),
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": "rm ~/.bashrc"},
)
- decision = await engine.check_permission(tool_call, Bash())
self.assertEqual(decision.behavior, PermissionBehavior.ASK)
self.assertIn("safety", decision.decision_reason.lower())
diff --git a/tests/toolkit_skill_test.py b/tests/toolkit_skill_test.py
index 0e9b66ca1..17509d086 100644
--- a/tests/toolkit_skill_test.py
+++ b/tests/toolkit_skill_test.py
@@ -257,7 +257,7 @@ class ToolkitSkillViewerTest(IsolatedAsyncioTestCase):
"text": "# My Skill\nThis is the skill content.",
},
],
- "state": "finished",
+ "state": "success",
"metadata": {},
"id": "test_call_1",
},
diff --git a/tests/toolkit_test.py b/tests/toolkit_test.py
index 598febc20..f6b326cc6 100644
--- a/tests/toolkit_test.py
+++ b/tests/toolkit_test.py
@@ -222,7 +222,7 @@ class ToolkitTest(IsolatedAsyncioTestCase):
"text": "Hello, world!",
},
],
- "state": "finished",
+ "state": "success",
"metadata": {},
"id": "test_1",
},
@@ -406,7 +406,7 @@ class ToolkitTest(IsolatedAsyncioTestCase):
},
},
],
- "state": "finished",
+ "state": "success",
"metadata": {},
"id": "test_2",
},
@@ -509,7 +509,7 @@ class RegisterFunctionTest(IsolatedAsyncioTestCase):
"text": "Result: 8",
},
],
- "state": "finished",
+ "state": "success",
"metadata": {},
"id": "test_add",
},
@@ -604,7 +604,7 @@ class RegisterFunctionTest(IsolatedAsyncioTestCase):
"text": "123", # All consecutive TextBlocks merged
},
],
- "state": "finished",
+ "state": "success",
"metadata": {},
"id": "test_count",
},
@@ -703,7 +703,7 @@ class RegisterFunctionTest(IsolatedAsyncioTestCase):
"text": "Product: 10.0",
},
],
- "state": "finished",
+ "state": "success",
"metadata": {},
"id": "test_multiply",
},
@@ -807,7 +807,7 @@ class RegisterFunctionTest(IsolatedAsyncioTestCase):
"text": "Number: 5Number: 6Number: 7",
},
],
- "state": "finished",
+ "state": "success",
"metadata": {},
"id": "test_sequence",
},
@@ -958,7 +958,7 @@ The tool instructions are a collection of suggestions, rules and notifications a
},
],
"metadata": {},
- "state": "finished",
+ "state": "success",
},
)
@@ -992,7 +992,7 @@ The tool instructions are a collection of suggestions, rules and notifications a
},
],
"metadata": {},
- "state": "finished",
+ "state": "success",
},
)
@@ -1022,6 +1022,6 @@ The tool instructions are a collection of suggestions, rules and notifications a
},
],
"metadata": {},
- "state": "finished",
+ "state": "success",
},
)
diff --git a/tests/utils.py b/tests/utils.py
index 0c8c38448..f40a04992 100644
--- a/tests/utils.py
+++ b/tests/utils.py
@@ -1,5 +1,8 @@
# -*- coding: utf-8 -*-
"""The utility module for unit tests in agentscope."""
+from typing import Any, AsyncGenerator
+
+from agentscope.model import ChatModelBase, ChatResponse
class AnyString:
@@ -12,3 +15,52 @@ class AnyString:
def __repr__(self) -> str:
"""Return a string representation for debugging purposes."""
return "<AnyString>"
+
+
+class MockModel(ChatModelBase):
+ """A mock model for testing."""
+
+ def __init__(self) -> None:
+ """Initialize the mock model."""
+ super().__init__(
+ model_name="mock-model",
+ stream=True,
+ max_retries=0,
+ fallback_model_name=None,
+ formatter=None,
+ )
+ self.mock_responses = []
+ self.cnt = 0
+
+ def set_responses(
+ self,
+ mock_responses: list[ChatResponse | list[ChatResponse]],
+ ) -> None:
+ """Set the mock responses."""
+ self.mock_responses = mock_responses
+ if all(isinstance(_, ChatResponse) for _ in mock_responses):
+ self.stream = False
+ else:
+ self.stream = True
+ self.cnt = 0
+
+ async def _call_api(
+ self, # pylint: disable=unused-argument
+ *args: Any,
+ **kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Mock the API call."""
+ mock_responses = self.mock_responses[self.cnt]
+ self.cnt += 1
+ if isinstance(mock_responses, list):
+
+ async def _stream() -> AsyncGenerator[ChatResponse, None]:
+ for response in mock_responses:
+ yield response
+
+ return _stream()
+
+ if isinstance(mock_responses, ChatResponse):
+ return mock_responses
+
+ raise AssertionError