zero-agent-core-multi-agent 0.1.0__py3-none-any.whl

agent_core_multi_agent/__init__.py

@@ -0,0 +1,68 @@
+"""Handwritten Agent Core 的多 Agent 编排扩展。"""
+
+from agent_core_multi_agent.adapters import (
+    AgentFunction,
+    CallableAgentInvoker,
+    RuntimeAgentInvoker,
+    RuntimeResultMapper,
+)
+from agent_core_multi_agent.errors import (
+    AgentAccessDeniedError,
+    AgentInvocationError,
+    AgentNotFoundError,
+    AgentRegistrationError,
+    AgentRoutingError,
+    CoordinationBudgetExceededError,
+    CoordinationBusyError,
+    CoordinationLeaseLostError,
+    MultiAgentError,
+)
+from agent_core_multi_agent.protocols import AgentInvoker, AgentRouter, CoordinationStore
+from agent_core_multi_agent.registry import AgentRegistry
+from agent_core_multi_agent.routing import CapabilityRouter, ModelAgentRouter
+from agent_core_multi_agent.storage import WorkflowCoordinationStore
+from agent_core_multi_agent.supervisor import SupervisorAgent
+from agent_core_multi_agent.types import (
+    AgentDescriptor,
+    AgentResult,
+    AgentResultStatus,
+    AgentTask,
+    CoordinationExecution,
+    CoordinationPolicy,
+    CoordinationStatus,
+    HandoffRequest,
+    RoutingDecision,
+)
+
+__all__ = [
+    "AgentAccessDeniedError",
+    "AgentDescriptor",
+    "AgentFunction",
+    "AgentInvocationError",
+    "AgentInvoker",
+    "AgentNotFoundError",
+    "AgentRegistrationError",
+    "AgentRegistry",
+    "AgentResult",
+    "AgentResultStatus",
+    "AgentRouter",
+    "AgentRoutingError",
+    "AgentTask",
+    "CallableAgentInvoker",
+    "CapabilityRouter",
+    "CoordinationBudgetExceededError",
+    "CoordinationBusyError",
+    "CoordinationExecution",
+    "CoordinationLeaseLostError",
+    "CoordinationPolicy",
+    "CoordinationStatus",
+    "CoordinationStore",
+    "HandoffRequest",
+    "ModelAgentRouter",
+    "MultiAgentError",
+    "RoutingDecision",
+    "RuntimeAgentInvoker",
+    "RuntimeResultMapper",
+    "SupervisorAgent",
+    "WorkflowCoordinationStore",
+]

agent_core_multi_agent/adapters.py

@@ -0,0 +1,139 @@
+"""函数和 Core AgentRuntime 的调用适配器。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+
+from agent_core import AgentRuntime, RunContext
+
+from agent_core_multi_agent.types import AgentResult, AgentResultStatus, AgentTask
+
+AgentFunction = Callable[
+    [AgentTask],
+    AgentResult | str | Awaitable[AgentResult | str],
+]
+RuntimeResultMapper = Callable[
+    [RunContext, AgentTask],
+    AgentResult | Awaitable[AgentResult],
+]
+
+
+class CallableAgentInvoker:
+    """把一个异步函数包装成 AgentInvoker。"""
+
+    def __init__(self, agent_id: str, function: AgentFunction) -> None:
+        if not agent_id.strip():
+            raise ValueError("agent_id 不能为空")
+        self._agent_id = agent_id
+        self._function = function
+
+    async def invoke(self, task: AgentTask) -> AgentResult:
+        called = self._function(task)
+        value = await called if inspect.isawaitable(called) else called
+        if isinstance(value, AgentResult):
+            return value
+        return AgentResult(
+            task_id=task.task_id,
+            agent_id=self._agent_id,
+            status="completed",
+            output=str(value),
+        )
+
+
+class RuntimeAgentInvoker:
+    """把现有 ``AgentRuntime`` 接入多 Agent 注册表。"""
+
+    def __init__(
+        self,
+        agent_id: str,
+        runtime: AgentRuntime,
+        *,
+        result_mapper: RuntimeResultMapper | None = None,
+    ) -> None:
+        if not agent_id.strip():
+            raise ValueError("agent_id 不能为空")
+        self._agent_id = agent_id
+        self._runtime = runtime
+        self._result_mapper = result_mapper
+
+    async def invoke(self, task: AgentTask) -> AgentResult:
+        access = task.access
+        context = await self._runtime.run(
+            task.thread_id,
+            task.input,
+            user_id=access.user_id if access else None,
+            tenant_id=access.tenant_id if access else None,
+            parent_run_id=task.parent_run_id or task.coordination_id,
+            idempotency_key=task.idempotency_key,
+            metadata={
+                **task.metadata,
+                "multi_agent_execution_id": task.coordination_id,
+                "multi_agent_task_id": task.task_id,
+                "multi_agent_context": task.context,
+                "multi_agent_lineage": list(task.lineage),
+            },
+        )
+        if (
+            task.resume_requested
+            and context.status not in {"completed", "cancelled"}
+            and context.checkpoint
+        ):
+            await self._runtime.resume(
+                task.thread_id,
+                context.run_id,
+                access=access,
+            )
+            context = await self._runtime.wait(
+                task.thread_id,
+                context.run_id,
+                access=access,
+            )
+        if self._result_mapper is not None:
+            mapped = self._result_mapper(context, task)
+            return await mapped if inspect.isawaitable(mapped) else mapped
+        return self._default_result(context, task)
+
+    def _default_result(self, context: RunContext, task: AgentTask) -> AgentResult:
+        status = _runtime_status(context.status)
+        output = ""
+        error: str | None = None
+        usage: dict[str, float] = {}
+        for event in context.events:
+            for key, value in event.usage.items():
+                if isinstance(value, int | float) and not isinstance(value, bool):
+                    usage[key] = usage.get(key, 0.0) + float(value)
+            if event.event_type == "run_completed":
+                output = str(event.payload.get("answer", ""))
+            if event.event_type == "run_failed":
+                error = event.error or str(event.payload.get("error", "Agent 运行失败"))
+        if status == "failed" and not error:
+            error = "Agent 运行失败"
+        return AgentResult(
+            task_id=task.task_id,
+            agent_id=self._agent_id,
+            status=status,
+            output=output,
+            run_id=context.run_id,
+            error=error,
+            usage=usage,
+            metadata={"runtime_status": context.status},
+        )
+
+
+def _runtime_status(status: str) -> AgentResultStatus:
+    if status == "completed":
+        return "completed"
+    if status == "failed":
+        return "failed"
+    if status == "cancelled":
+        return "cancelled"
+    return "interrupted"
+
+
+__all__ = [
+    "AgentFunction",
+    "CallableAgentInvoker",
+    "RuntimeAgentInvoker",
+    "RuntimeResultMapper",
+]

agent_core_multi_agent/errors.py

@@ -0,0 +1,39 @@
+"""多 Agent 编排扩展错误。"""
+
+from agent_core import AgentError
+
+
+class MultiAgentError(AgentError):
+    """多 Agent 扩展基础错误。"""
+
+
+class AgentRegistrationError(MultiAgentError):
+    """Agent 注册信息无效或发生名称冲突。"""
+
+
+class AgentNotFoundError(MultiAgentError):
+    """注册表中不存在目标 Agent。"""
+
+
+class AgentAccessDeniedError(MultiAgentError):
+    """当前访问身份无权调用目标 Agent。"""
+
+
+class AgentRoutingError(MultiAgentError):
+    """无法为任务选择唯一且可访问的 Agent。"""
+
+
+class AgentInvocationError(MultiAgentError):
+    """子 Agent 调用失败或返回了无效结果。"""
+
+
+class CoordinationBudgetExceededError(MultiAgentError):
+    """协调实例超过 handoff、调用次数、访问次数或使用量预算。"""
+
+
+class CoordinationBusyError(MultiAgentError):
+    """协调实例已经由其他 Worker 持有。"""
+
+
+class CoordinationLeaseLostError(MultiAgentError):
+    """执行过程中失去协调实例租约。"""

agent_core_multi_agent/protocols.py

@@ -0,0 +1,49 @@
+"""多 Agent 扩展的依赖倒置协议。"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from agent_core import AccessContext
+
+from agent_core_multi_agent.types import AgentResult, AgentTask, CoordinationExecution, RoutingDecision
+
+if TYPE_CHECKING:
+    from agent_core_multi_agent.registry import AgentRegistry
+
+
+@runtime_checkable
+class AgentInvoker(Protocol):
+    """任何可由 Supervisor 调用的 Agent 最小接口。"""
+
+    async def invoke(self, task: AgentTask) -> AgentResult: ...
+
+
+@runtime_checkable
+class AgentRouter(Protocol):
+    """根据任务和当前可访问注册表选择 Agent。"""
+
+    async def route(self, task: AgentTask, registry: AgentRegistry) -> RoutingDecision: ...
+
+
+@runtime_checkable
+class CoordinationStore(Protocol):
+    """协调实例持久化协议。"""
+
+    async def save(self, execution: CoordinationExecution) -> None: ...
+
+    async def load(
+        self,
+        execution_id: str,
+        *,
+        access: AccessContext | None = None,
+    ) -> CoordinationExecution | None: ...
+
+    async def list(
+        self,
+        *,
+        access: AccessContext | None = None,
+    ) -> list[CoordinationExecution]: ...
+
+
+__all__ = ["AgentInvoker", "AgentRouter", "CoordinationStore"]

agent_core_multi_agent/py.typed

@@ -0,0 +1 @@
+

agent_core_multi_agent/registry.py

@@ -0,0 +1,133 @@
+"""Agent 注册、能力发现、权限过滤和并发限制。"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from agent_core import AccessContext
+
+from agent_core_multi_agent.errors import (
+    AgentAccessDeniedError,
+    AgentInvocationError,
+    AgentNotFoundError,
+    AgentRegistrationError,
+)
+from agent_core_multi_agent.protocols import AgentInvoker
+from agent_core_multi_agent.types import AgentDescriptor, AgentResult, AgentTask
+
+
+@dataclass(frozen=True)
+class _RegisteredAgent:
+    descriptor: AgentDescriptor
+    invoker: AgentInvoker
+    semaphore: asyncio.Semaphore | None
+
+
+class AgentRegistry:
+    """保存 Agent 描述和调用器，并在调用前执行权限与并发检查。"""
+
+    def __init__(self) -> None:
+        self._agents: dict[str, _RegisteredAgent] = {}
+        self._aliases: dict[str, str] = {}
+
+    def register(
+        self,
+        descriptor: AgentDescriptor,
+        invoker: AgentInvoker,
+        *,
+        replace: bool = False,
+    ) -> None:
+        agent_id = descriptor.agent_id
+        collisions = {
+            name
+            for name in (agent_id, *descriptor.aliases)
+            if name in self._aliases and self._aliases[name] != agent_id
+        }
+        if collisions:
+            raise AgentRegistrationError(f"Agent 名称或别名冲突：{', '.join(sorted(collisions))}")
+        if agent_id in self._agents and not replace:
+            raise AgentRegistrationError(f"Agent 已注册：{agent_id}")
+        if replace:
+            self.unregister(agent_id)
+        semaphore = (
+            asyncio.Semaphore(descriptor.max_concurrency) if descriptor.max_concurrency is not None else None
+        )
+        self._agents[agent_id] = _RegisteredAgent(descriptor, invoker, semaphore)
+        self._aliases[agent_id] = agent_id
+        for alias in descriptor.aliases:
+            self._aliases[alias] = agent_id
+
+    def unregister(self, agent_id: str) -> bool:
+        normalized = self._aliases.get(agent_id, agent_id)
+        registered = self._agents.pop(normalized, None)
+        if registered is None:
+            return False
+        for name, owner in tuple(self._aliases.items()):
+            if owner == normalized:
+                del self._aliases[name]
+        return True
+
+    def get_descriptor(
+        self,
+        agent_id: str,
+        *,
+        access: AccessContext | None = None,
+    ) -> AgentDescriptor:
+        registered = self._resolve(agent_id)
+        self._check_access(registered.descriptor, access)
+        return registered.descriptor
+
+    def descriptors(self, *, access: AccessContext | None = None) -> tuple[AgentDescriptor, ...]:
+        values = [item.descriptor for item in self._agents.values() if item.descriptor.can_invoke(access)]
+        return tuple(sorted(values, key=lambda item: (-item.priority, item.agent_id)))
+
+    def candidates(
+        self,
+        capability: str,
+        *,
+        access: AccessContext | None = None,
+    ) -> tuple[AgentDescriptor, ...]:
+        normalized = capability.strip()
+        return tuple(
+            descriptor
+            for descriptor in self.descriptors(access=access)
+            if normalized in descriptor.capabilities
+        )
+
+    async def invoke(self, agent_id: str, task: AgentTask) -> AgentResult:
+        registered = self._resolve(agent_id)
+        self._check_access(registered.descriptor, task.access)
+
+        async def execute() -> AgentResult:
+            result = await registered.invoker.invoke(task)
+            if result.task_id != task.task_id:
+                raise AgentInvocationError(
+                    f"Agent {registered.descriptor.agent_id} 返回了错误的 task_id：{result.task_id}"
+                )
+            if result.agent_id != registered.descriptor.agent_id:
+                raise AgentInvocationError(
+                    f"Agent 返回 ID {result.agent_id} 与注册 ID {registered.descriptor.agent_id} 不一致"
+                )
+            return result
+
+        if registered.semaphore is None:
+            return await execute()
+        async with registered.semaphore:
+            return await execute()
+
+    def _resolve(self, name: str) -> _RegisteredAgent:
+        agent_id = self._aliases.get(name)
+        if agent_id is None:
+            available = ", ".join(sorted(self._agents)) or "无"
+            raise AgentNotFoundError(f"Agent 不存在：{name}；已注册：{available}")
+        return self._agents[agent_id]
+
+    @staticmethod
+    def _check_access(descriptor: AgentDescriptor, access: AccessContext | None) -> None:
+        if not descriptor.can_invoke(access):
+            roles = ", ".join(sorted(descriptor.required_roles))
+            raise AgentAccessDeniedError(f"调用 Agent {descriptor.agent_id} 需要角色：{roles}")
+
+
+__all__ = ["AgentRegistry"]

agent_core_multi_agent/routing.py

@@ -0,0 +1,124 @@
+"""确定性能力路由和可选模型路由。"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from agent_core import ModelAdapter, StructuredOutputSpec, chat_structured, system_message, user_message
+
+from agent_core_multi_agent.errors import AgentRoutingError
+from agent_core_multi_agent.registry import AgentRegistry
+from agent_core_multi_agent.types import AgentTask, RoutingDecision
+
+
+class CapabilityRouter:
+    """优先显式目标，其次能力匹配，最后使用可选默认 Agent。"""
+
+    def __init__(self, default_agent_id: str | None = None) -> None:
+        self._default_agent_id = default_agent_id
+
+    async def route(self, task: AgentTask, registry: AgentRegistry) -> RoutingDecision:
+        if task.target_agent_id:
+            descriptor = registry.get_descriptor(task.target_agent_id, access=task.access)
+            if (
+                task.required_capability
+                and task.required_capability not in descriptor.capabilities
+            ):
+                raise AgentRoutingError(
+                    f"Agent {descriptor.agent_id} 不提供能力：{task.required_capability}"
+                )
+            return RoutingDecision(descriptor.agent_id, "任务显式指定目标 Agent")
+
+        if task.required_capability:
+            candidates = registry.candidates(task.required_capability, access=task.access)
+            if not candidates:
+                raise AgentRoutingError(f"没有可访问的 Agent 提供能力：{task.required_capability}")
+            selected = candidates[0]
+            return RoutingDecision(
+                selected.agent_id,
+                f"按能力 {task.required_capability} 和优先级选择",
+            )
+
+        if self._default_agent_id:
+            descriptor = registry.get_descriptor(self._default_agent_id, access=task.access)
+            return RoutingDecision(descriptor.agent_id, "使用默认 Agent")
+
+        candidates = registry.descriptors(access=task.access)
+        if len(candidates) == 1:
+            return RoutingDecision(candidates[0].agent_id, "只有一个可访问的 Agent")
+        raise AgentRoutingError("任务没有指定目标或能力，且无法唯一选择 Agent")
+
+
+class ModelAgentRouter:
+    """让模型在权限过滤后的候选集合中选择 Agent。"""
+
+    def __init__(
+        self,
+        model: ModelAdapter,
+        *,
+        fallback: CapabilityRouter | None = None,
+        max_retries: int = 1,
+    ) -> None:
+        self._model = model
+        self._fallback = fallback or CapabilityRouter()
+        self._max_retries = max_retries
+
+    async def route(self, task: AgentTask, registry: AgentRegistry) -> RoutingDecision:
+        if task.target_agent_id or task.required_capability:
+            return await self._fallback.route(task, registry)
+
+        candidates = registry.descriptors(access=task.access)
+        if not candidates:
+            raise AgentRoutingError("没有可访问的 Agent")
+        if len(candidates) == 1:
+            return RoutingDecision(candidates[0].agent_id, "只有一个可访问的 Agent")
+
+        agent_ids = [item.agent_id for item in candidates]
+        candidate_payload = [
+            {
+                "agent_id": item.agent_id,
+                "description": item.description,
+                "capabilities": sorted(item.capabilities),
+            }
+            for item in candidates
+        ]
+        spec = StructuredOutputSpec[RoutingDecision](
+            name="agent_routing_decision",
+            schema={
+                "type": "object",
+                "properties": {
+                    "agent_id": {"type": "string", "enum": agent_ids},
+                    "reason": {"type": "string", "minLength": 1},
+                },
+                "required": ["agent_id", "reason"],
+                "additionalProperties": False,
+            },
+            decoder=self._decode,
+            max_retries=self._max_retries,
+        )
+        result = await chat_structured(
+            self._model,
+            [
+                system_message(
+                    "你是多 Agent 路由器。只能从候选 Agent 中选择一个最适合当前任务的 Agent。"
+                ),
+                user_message(
+                    "任务："
+                    f"{task.input}\n上下文：{json.dumps(task.context, ensure_ascii=False, default=str)}"
+                    f"\n候选：{json.dumps(candidate_payload, ensure_ascii=False)}"
+                ),
+            ],
+            spec,
+            temperature=0,
+        )
+        return result.value
+
+    @staticmethod
+    def _decode(value: Any) -> RoutingDecision:
+        if not isinstance(value, dict):
+            raise TypeError("路由结果必须是对象")
+        return RoutingDecision(agent_id=str(value["agent_id"]), reason=str(value["reason"]))
+
+
+__all__ = ["CapabilityRouter", "ModelAgentRouter"]

agent_core_multi_agent/storage.py

@@ -0,0 +1,110 @@
+"""复用 Core Workflow Store 的协调实例存储适配器。"""
+
+from __future__ import annotations
+
+import json
+
+from agent_core import (
+    AccessContext,
+    MemoryWorkflowExecutionStore,
+    WorkflowExecution,
+    WorkflowExecutionStore,
+)
+
+from agent_core_multi_agent.types import CoordinationExecution
+
+
+class WorkflowCoordinationStore:
+    """把协调快照保存到 Core 的 Memory/SQLite/PostgreSQL Workflow Store。"""
+
+    def __init__(
+        self,
+        store: WorkflowExecutionStore | None = None,
+        *,
+        definition_id: str = "multi-agent-supervisor",
+        require_access: bool = False,
+    ) -> None:
+        self._store = store or MemoryWorkflowExecutionStore()
+        self._definition_id = definition_id
+        self._require_access = require_access
+
+    async def save(self, execution: CoordinationExecution) -> None:
+        access = execution.access
+        if self._require_access and access is None:
+            raise PermissionError("该 CoordinationStore 要求提供 AccessContext")
+        payload = execution.to_dict()
+        try:
+            json.dumps(payload, ensure_ascii=False)
+        except (TypeError, ValueError) as exc:
+            raise TypeError("协调实例包含不可 JSON 序列化的数据") from exc
+        record = WorkflowExecution(
+            execution_id=execution.execution_id,
+            definition_id=self._definition_id,
+            execution_type="multi_agent",
+            user_id=access.user_id if access else None,
+            tenant_id=access.tenant_id if access else None,
+            status=execution.status,
+            current_step=execution.current_agent_id,
+            steps_completed=len(execution.results),
+            total_steps=execution.agent_calls,
+            input_data=execution.root_task.to_dict(),
+            result_data=payload,
+            events=[event.to_dict() for event in execution.events],
+            version=execution.version,
+            created_at=execution.created_at,
+            updated_at=execution.updated_at,
+        )
+        await self._store.save(record)
+        execution.version = record.version
+        execution.updated_at = record.updated_at
+
+    async def load(
+        self,
+        execution_id: str,
+        *,
+        access: AccessContext | None = None,
+    ) -> CoordinationExecution | None:
+        record = await self._store.load(execution_id)
+        if record is None or record.execution_type != "multi_agent":
+            return None
+        self._check_access(record, access)
+        execution = CoordinationExecution.from_dict(record.result_data)
+        execution.version = record.version
+        execution.updated_at = record.updated_at
+        return execution
+
+    async def list(
+        self,
+        *,
+        access: AccessContext | None = None,
+    ) -> list[CoordinationExecution]:
+        if self._require_access and access is None:
+            raise PermissionError("该 CoordinationStore 要求提供 AccessContext")
+        tenant_id = access.tenant_id if access else None
+        records = await self._store.list(self._definition_id, tenant_id)
+        executions: list[CoordinationExecution] = []
+        for record in records:
+            if record.execution_type != "multi_agent":
+                continue
+            if access is not None and not access.can_access(record.user_id, record.tenant_id):
+                continue
+            execution = CoordinationExecution.from_dict(record.result_data)
+            execution.version = record.version
+            execution.updated_at = record.updated_at
+            executions.append(execution)
+        return executions
+
+    def _check_access(
+        self,
+        record: WorkflowExecution,
+        access: AccessContext | None,
+    ) -> None:
+        if self._require_access and access is None:
+            raise PermissionError("该 CoordinationStore 要求提供 AccessContext")
+        if self._require_access and (record.user_id is None or record.tenant_id is None):
+            raise PermissionError("该协调实例尚未绑定用户和租户")
+        if access is not None and not access.can_access(record.user_id, record.tenant_id):
+            raise PermissionError("无权访问该协调实例")
+
+
+__all__ = ["WorkflowCoordinationStore"]