aury-agent 0.0.5__py3-none-any.whl → 0.0.7__py3-none-any.whl

aury/agents/core/base.py

@@ -49,8 +49,17 @@ class AgentConfig:
     Note: LLM parameters (temperature, max_tokens, timeout, retries) are
     configured on LLMProvider, not here. Tool timeout is configured on
     each tool's ToolConfig, not here.
+    
+    Agent identity fields (for ActorInfo):
+    - id: Database ID or unique identifier (e.g. "1", "agent_123")
+    - code: Agent code/type (e.g. "super_assistant", "researcher")
+    - name: Display name (e.g. "超级助理", "Researcher Agent")
     """
-    name: str = "default"
+    # Agent identity
+    id: str | None = None  # Database ID
+    code: str | None = None  # Agent code (used as fallback for id)
+    name: str | None = None  # Display name
+    
     max_steps: int = 50
     
     # System prompt configuration

aury/agents/core/context.py

@@ -147,19 +147,31 @@ async def emit(event: "BlockEvent | ActionEvent") -> None:
     Use this when you don't have access to InvocationContext,
     e.g., in tool execute() methods.
     
-    For BlockEvent: automatically fills parent_id from ContextVar if not set.
-    ActionEvent does not have parent_id.
+    For BlockEvent: automatically fills parent_id and actor from ContextVar if not set.
+    ActionEvent does not have parent_id or actor.
     
     Args:
         event: BlockEvent or ActionEvent to emit
     """
     try:
+        # Get current context for auto-fill
+        ctx = get_current_ctx_or_none()
+        
         # Auto-fill parent_id from ContextVar if not explicitly set (BlockEvent only)
         if hasattr(event, 'parent_id') and event.parent_id is None:
             from .types.block import BlockKind
             kind = event.kind.value if isinstance(event.kind, BlockKind) else event.kind
             event.parent_id = resolve_parent_id(kind)
         
+        # Auto-fill actor from context if not explicitly set (BlockEvent only)
+        if hasattr(event, 'actor') and event.actor is None and ctx:
+            from .types.block import ActorInfo
+            event.actor = ActorInfo(
+                id=ctx.agent_id,
+                role="assistant",
+                name=ctx.agent_name,
+            )
+        
         queue = _emit_queue_var.get()
         await queue.put(event)
         # Yield control to event loop to allow consumer to process the queue
@@ -224,6 +236,7 @@ class InvocationContext:
     session: "Session"
     invocation_id: str
     agent_id: str
+    agent_name: str | None = None  # Agent display name (for ActorInfo)
     
     # Backends container (unified backend access)
     backends: "Backends | None" = None
@@ -272,6 +285,10 @@ class InvocationContext:
     config: dict[str, Any] = field(default_factory=dict)
     metadata: dict[str, Any] = field(default_factory=dict)
     
+    # Block schema versions mapping: kind -> schema_version
+    # External can register different schema versions for the same kind
+    block_schema_versions: dict[str, str] = field(default_factory=dict)
+    
     # Depth tracking (for max depth enforcement)
     _depth: int = 0
     
@@ -404,6 +421,7 @@ class InvocationContext:
     def create_child(
         self,
         agent_id: str,
+        agent_name: str | None = None,
         mode: str = "delegated",
         inherit_config: bool = True,
         llm: "LLMProvider | None" = None,
@@ -418,6 +436,7 @@ class InvocationContext:
         
         Args:
             agent_id: Sub-agent ID
+            agent_name: Sub-agent display name (optional)
             mode: Execution mode (delegated)
             inherit_config: Whether to copy config
             llm: Override LLM provider (None = inherit from parent)
@@ -461,6 +480,7 @@ class InvocationContext:
             session=self.session,
             invocation_id=generate_id("inv"),
             agent_id=agent_id,
+            agent_name=agent_name,
             backends=self.backends,  # Inherit backends
             bus=self.bus,
             llm=llm if llm is not None else self.llm,
@@ -476,6 +496,7 @@ class InvocationContext:
             abort_chain=self.abort_chain,  # Shared abort_chain
             config=self.config.copy() if inherit_config else {},
             metadata={"parent_block_id": parent_block_id} if parent_block_id else {},
+            block_schema_versions=self.block_schema_versions.copy() if inherit_config else {},
             _depth=self._depth + 1,
         )
     
@@ -485,6 +506,7 @@ class InvocationContext:
             session=self.session,
             invocation_id=self.invocation_id,
             agent_id=self.agent_id,
+            agent_name=self.agent_name,
             backends=self.backends,  # Inherit backends
             bus=self.bus,
             llm=self.llm,
@@ -499,6 +521,7 @@ class InvocationContext:
             abort_chain=self.abort_chain,
             config=self.config,
             metadata=self.metadata.copy(),
+            block_schema_versions=self.block_schema_versions,
             _depth=self._depth,
         )
     
@@ -574,13 +597,17 @@ class InvocationContext:
         - Tool outputs
         - BlockHandle operations
         
-        The block's session_id, invocation_id, and parent_id are automatically filled.
-        Uses ContextVar to find the queue set by BaseAgent.run().
-        Parent_id respects the apply_to_kinds filter set via set_parent_id().
+        The block's session_id, invocation_id, parent_id, actor, and schema_version 
+        are automatically filled. Uses ContextVar to find the queue set by 
+        BaseAgent.run(). Parent_id respects the apply_to_kinds filter set 
+        via set_parent_id().
         
         Args:
             block: BlockEvent to emit
         """
+        from .types.block import BlockKind, ActorInfo
+        kind = block.kind.value if isinstance(block.kind, BlockKind) else block.kind
+        
         # Fill in IDs if not set
         if not block.session_id:
             block.session_id = self.session_id
@@ -589,10 +616,21 @@ class InvocationContext:
         # Auto-fill parent_id from ContextVar if not explicitly set
         # Uses resolve_parent_id to respect apply_to_kinds filter
         if block.parent_id is None:
-            from .types.block import BlockKind
-            kind = block.kind.value if isinstance(block.kind, BlockKind) else block.kind
             block.parent_id = resolve_parent_id(kind)
         
+        # Auto-fill actor if not explicitly set
+        # Actor represents the agent that emitted this block
+        if block.actor is None:
+            block.actor = ActorInfo(
+                id=self.agent_id,
+                role="assistant",
+                name=self.agent_name,
+            )
+        
+        # Auto-fill schema_version from config if not explicitly set
+        if block.schema_version is None and kind in self.block_schema_versions:
+            block.schema_version = self.block_schema_versions[kind]
+        
         # Put into the current run's queue (via ContextVar)
         try:
             queue = _emit_queue_var.get()
@@ -639,17 +677,9 @@ class InvocationContext:
             **kwargs,
         }
         
-        # Build context for middleware
-        mw_context = {
-            "session_id": self.session_id,
-            "invocation_id": self.invocation_id,
-            "agent_id": self.agent_id,
-            "step": self.step,
-        }
-        
         # Process through middleware (on_request)
         if self.middleware:
-            processed = await self.middleware.process_request(request, mw_context)
+            processed = await self.middleware.process_request(request)
             if processed is None:
                 logger.debug("Request blocked by middleware")
                 return None
@@ -658,7 +688,7 @@ class InvocationContext:
         try:
             # Call LLM
             if stream:
-                return self._stream_llm_with_middleware(provider, request, mw_context)
+                return self._stream_llm_with_middleware(provider, request)
             else:
                 response = await provider.generate(
                     messages=request["messages"],
@@ -668,7 +698,7 @@ class InvocationContext:
                 # Process through middleware (on_response)
                 if self.middleware:
                     response_dict = {"response": response}
-                    processed = await self.middleware.process_response(response_dict, mw_context)
+                    processed = await self.middleware.process_response(response_dict)
                     if processed is None:
                         return None
                     response = processed.get("response", response)
@@ -677,7 +707,7 @@ class InvocationContext:
                 
         except Exception as e:
             if self.middleware:
-                processed_error = await self.middleware.process_error(e, mw_context)
+                processed_error = await self.middleware.process_error(e)
                 if processed_error is None:
                     return None
                 raise processed_error
@@ -687,7 +717,6 @@ class InvocationContext:
         self,
         provider: "LLMProvider",
         request: dict[str, Any],
-        mw_context: dict[str, Any],
     ) -> AsyncIterator[Any]:
         """Stream LLM response with middleware processing."""
         if self.middleware:
@@ -700,7 +729,7 @@ class InvocationContext:
             ):
                 if self.middleware:
                     chunk_dict = {"chunk": chunk}
-                    processed = await self.middleware.process_stream_chunk(chunk_dict, mw_context)
+                    processed = await self.middleware.process_stream_chunk(chunk_dict)
                     if processed is None:
                         continue
                     chunk = processed.get("chunk", chunk)
@@ -708,7 +737,7 @@ class InvocationContext:
                 
         except Exception as e:
             if self.middleware:
-                processed_error = await self.middleware.process_error(e, mw_context)
+                processed_error = await self.middleware.process_error(e)
                 if processed_error is None:
                     return
                 raise processed_error
@@ -733,19 +762,11 @@ class InvocationContext:
         """
         from ..middleware import HookAction
         
-        # Build context for middleware
-        mw_context = {
-            "session_id": self.session_id,
-            "invocation_id": self.invocation_id,
-            "agent_id": self.agent_id,
-            "step": self.step,
-        }
-        
         current_args = arguments
         
         # Process through middleware (on_tool_call)
         if self.middleware:
-            result = await self.middleware.process_tool_call(tool, current_args, mw_context)
+            result = await self.middleware.process_tool_call(tool, current_args)
             if result.action == HookAction.SKIP:
                 logger.debug(f"Tool {tool.name} skipped by middleware")
                 from ..tool import ToolResult
@@ -768,7 +789,7 @@ class InvocationContext:
         
         # Process through middleware (on_tool_end)
         if self.middleware:
-            result = await self.middleware.process_tool_end(tool, tool_result, mw_context)
+            result = await self.middleware.process_tool_end(tool, tool_result)
             if result.action == HookAction.RETRY and result.modified_data:
                 # Re-execute with modified args
                 tool_result = await tool.execute(**result.modified_data)

aury/agents/core/event_bus/bus.py

@@ -94,8 +94,6 @@ class EventBus:
             # Wildcard match
             handlers.extend(self._subscriptions.get("*", []))
         
-        logger.debug("Publishing event", extra={"event_type": event_type})
-        
         for handler in handlers:
             try:
                 if asyncio.iscoroutinefunction(handler):

aury/agents/core/factory.py

@@ -129,7 +129,12 @@ class AgentFactory:
             Agent instance with child context
         """
         logger.debug(f"AgentFactory.create_subagent: creating subagent, type={agent_type}, mode={mode}, parent_invocation_id={parent_ctx.invocation_id}")
-        child_ctx = parent_ctx.create_child(agent_id=agent_type, mode=mode)
+        
+        # Get agent name from class if available
+        agent_class = self._registry.get(agent_type)
+        agent_name = getattr(agent_class, 'name', agent_type) if agent_class else agent_type
+        
+        child_ctx = parent_ctx.create_child(agent_id=agent_type, agent_name=agent_name, mode=mode)
         logger.debug(f"AgentFactory.create_subagent: child context created, child_invocation_id={child_ctx.invocation_id}")
         return self.create(agent_type, child_ctx, config)
     

aury/agents/core/logging.py

@@ -21,7 +21,29 @@ Pre-defined loggers:
     - session: aury.agents.session
 """
 import logging
-from typing import Literal
+from typing import Any, Literal
+
+# =============================================================================
+# TRACE Level 支持
+# =============================================================================
+# TRACE (5) < DEBUG (10)，用于超细粒度调试
+TRACE = 5
+if logging.getLevelName(TRACE) == "Level 5":
+    logging.addLevelName(TRACE, "TRACE")
+
+
+def _ensure_trace_method() -> None:
+    """确保 logging.Logger 有 trace() 方法。"""
+    if hasattr(logging.Logger, "trace"):
+        return
+    
+    def trace(self: logging.Logger, msg: str, *args: Any, **kwargs: Any) -> None:
+        if self.isEnabledFor(TRACE):
+            self._log(TRACE, msg, args, **kwargs)
+    
+    logging.Logger.trace = trace  # type: ignore[attr-defined]
+
+_ensure_trace_method()
 
 # Root namespace
 ROOT_NAMESPACE = "aury.agents"
@@ -79,6 +101,7 @@ LoggerName = Literal[
 
 
 __all__ = [
+    "TRACE",
     "get_logger",
     "logger",
     "react_logger",

aury/agents/core/types/block.py

@@ -110,6 +110,7 @@ class BlockEvent:
     op: BlockOp = BlockOp.APPLY
     data: dict[str, Any] | None = None
     branch: str | None = None  # For sub-agent isolation (e.g. "agent1.agent2")
+    schema_version: str | None = None  # Schema version for external rendering/handling
     
     # Protocol envelope
     protocol_version: str = "1.0"
@@ -130,6 +131,7 @@ class BlockEvent:
             "op": self.op.value,
             "data": self.data,
             "branch": self.branch,
+            "schema_version": self.schema_version,
             "protocol_version": self.protocol_version,
             "event_id": self.event_id,
             "timestamp": self.timestamp,
@@ -154,6 +156,7 @@ class BlockEvent:
             op=BlockOp(data["op"]),
             data=data.get("data"),
             branch=data.get("branch"),
+            schema_version=data.get("schema_version"),
             protocol_version=data.get("protocol_version", "1.0"),
             event_id=data.get("event_id", ""),
             timestamp=data.get("timestamp", 0),
@@ -310,8 +313,7 @@ class PersistedBlock:
     # From protocol envelope
     session_id: str = ""
     invocation_id: str = ""
-    actor_id: str = ""
-    actor_role: str = "assistant"
+    actor: ActorInfo | None = None
     
     # Branch for sub-agent isolation
     branch: str | None = None
@@ -332,8 +334,7 @@ class PersistedBlock:
             "data": self.data,
             "session_id": self.session_id,
             "invocation_id": self.invocation_id,
-            "actor_id": self.actor_id,
-            "actor_role": self.actor_role,
+            "actor": self.actor.to_dict() if self.actor else None,
             "branch": self.branch,
             "created_at": self.created_at.isoformat(),
             "updated_at": self.updated_at.isoformat() if self.updated_at else None,
@@ -355,8 +356,7 @@ class PersistedBlock:
             data=data.get("data"),
             session_id=data.get("session_id", ""),
             invocation_id=data.get("invocation_id", ""),
-            actor_id=data.get("actor_id", ""),
-            actor_role=data.get("actor_role", "assistant"),
+            actor=ActorInfo.from_dict(data["actor"]) if data.get("actor") else None,
             branch=data.get("branch"),
             created_at=datetime.fromisoformat(data["created_at"]),
             updated_at=datetime.fromisoformat(data["updated_at"]) if data.get("updated_at") else None,
@@ -395,8 +395,7 @@ class PersistedBlock:
             branch=first.branch,
             session_id=first.session_id,
             invocation_id=first.invocation_id,
-            actor_id=first.actor.id if first.actor else "",
-            actor_role=first.actor.role if first.actor else "assistant",
+            actor=first.actor,
             updated_at=datetime.fromtimestamp(last_timestamp / 1000) if len(events) > 1 else None,
         )
     
@@ -471,8 +470,7 @@ class BlockAggregator:
                 branch=event.branch,
                 session_id=event.session_id,
                 invocation_id=event.invocation_id,
-                actor_id=event.actor.id if event.actor else "",
-                actor_role=event.actor.role if event.actor else "assistant",
+                actor=event.actor,
             )
             self._blocks[block_id] = block
             self._order.append(block_id)
@@ -533,6 +531,7 @@ class BlockHandle:
         parent: "BlockHandle | str | None" = None,
         persistence: Persistence = Persistence.PERSISTENT,
         branch: str | None = None,
+        schema_version: str | None = None,
     ):
         self.ctx = ctx
         self.kind = kind
@@ -541,6 +540,8 @@ class BlockHandle:
         self.persistence = persistence
         # Use provided branch or get from context
         self.branch = branch or getattr(ctx, 'branch', None)
+        # Schema version (None = auto-fill from ctx.block_schema_versions)
+        self.schema_version = schema_version
     
     async def apply(self, data: dict[str, Any], **kwargs: Any) -> None:
         """Create or completely replace the Block."""
@@ -552,6 +553,7 @@ class BlockHandle:
             op=BlockOp.APPLY,
             data=data,
             branch=self.branch,
+            schema_version=self.schema_version,
             **kwargs,
         ))
     
@@ -565,6 +567,7 @@ class BlockHandle:
             op=BlockOp.DELTA,
             data=data,
             branch=self.branch,
+            schema_version=self.schema_version,
         ))
     
     async def patch(self, data: dict[str, Any]) -> None:
@@ -577,6 +580,7 @@ class BlockHandle:
             op=BlockOp.PATCH,
             data=data,
             branch=self.branch,
+            schema_version=self.schema_version,
         ))
     
     def child(
@@ -584,6 +588,7 @@ class BlockHandle:
         kind: BlockKind | str,
         block_id: str | None = None,
         persistence: Persistence = Persistence.PERSISTENT,
+        schema_version: str | None = None,
     ) -> "BlockHandle":
         """Create a child BlockHandle nested under this Block."""
         return BlockHandle(
@@ -593,6 +598,7 @@ class BlockHandle:
             parent=self,
             persistence=persistence,
             branch=self.branch,  # Inherit branch from parent
+            schema_version=schema_version,  # Child can have different schema_version
         )
 
 

aury/agents/llm/adapter.py

@@ -58,6 +58,7 @@ class ModelClientProvider:
         api_key: str | None = None,
         base_url: str | None = None,
         capabilities: Capabilities | None = None,
+        timeout: float | None = None,
         **kwargs: Any,
     ):
         """Initialize ModelClient provider.
@@ -68,6 +69,7 @@ class ModelClientProvider:
             api_key: API key (optional, uses env if not provided)
             base_url: Base URL override
             capabilities: Model capabilities
+            timeout: Request timeout in seconds (None = use provider default, typically 600s)
             **kwargs: Additional ModelClient options
         """
         if not HAS_MODEL_CLIENT:
@@ -90,6 +92,8 @@ class ModelClientProvider:
             client_kwargs["api_key"] = api_key
         if base_url:
             client_kwargs["base_url"] = base_url
+        if timeout is not None:
+            client_kwargs["timeout"] = timeout
         
         # Pass through additional options
         for key in ("default_max_tokens", "default_temperature", "default_top_p"):
@@ -381,6 +385,7 @@ class ModelClientProvider:
 def create_provider(
     provider: str,
     model: str,
+    timeout: float | None = None,
     **kwargs: Any,
 ) -> LLMProvider:
     """Create an LLM provider.
@@ -388,9 +393,10 @@ def create_provider(
     Args:
         provider: Provider name (openai, anthropic, doubao, etc.)
         model: Model name
+        timeout: Request timeout in seconds (None = use provider default)
         **kwargs: Additional options
     
     Returns:
         LLMProvider instance
     """
-    return ModelClientProvider(provider=provider, model=model, **kwargs)
+    return ModelClientProvider(provider=provider, model=model, timeout=timeout, **kwargs)