import asyncio from abc import ABC, abstractmethod from collections.abc import AsyncIterator from app.core.contracts import ( AgentDefinition, AgentRequest, AgentResult, CoreResult, IntentResult, RecalledMemory, RequestContext, ResolvedAgentConfig, RunProgressEvent, SourceReference, ToolCallRecord, ) from app.core.errors import RecoverableAgentError, UpstreamTimeoutError from app.service.agent.authorizer import AgentAuthorizer from app.service.agent.governance import AgentGovernance from app.service.intent_classifier import IntentClassifier, IntentEndpointResolver from app.service.model_gateway import ModelExecution, ModelGenerationService from app.service.tool_executor import ToolExecutor class BaseAgent(ABC): definition: AgentDefinition def __init__(self, definition: AgentDefinition) -> None: self.definition = definition self._governance: AgentGovernance | None = None self.config: ResolvedAgentConfig | None = None self.memories: tuple[RecalledMemory, ...] = () self._model_service: ModelGenerationService | None = None self._tool_executor: ToolExecutor | None = None self._tool_records: list[ToolCallRecord] = [] self._tool_references: list[SourceReference] = [] self._intent_classifier: IntentClassifier | None = None self._intent_endpoint_resolver: IntentEndpointResolver | None = None self._classified_intent: IntentResult | None = None def bind_governance(self, governance: AgentGovernance) -> None: if self._governance is not None: raise TypeError("Agent instances must not be reused") self._governance = governance def bind_model_service(self, service: ModelGenerationService) -> None: if self._model_service is not None: raise TypeError("model service is already bound") self._model_service = service def bind_tool_executor(self, executor: ToolExecutor) -> None: if self._tool_executor is not None: raise TypeError("tool executor is already bound") self._tool_executor = executor def bind_intent_classifier( self, classifier: IntentClassifier, resolver: IntentEndpointResolver ) -> None: if self._intent_classifier is not None: raise TypeError("intent classifier is already bound") self._intent_classifier = classifier self._intent_endpoint_resolver = resolver async def call_tool( self, name: str, arguments: dict[str, object], *, intent: str, context: RequestContext, ) -> object: if self._tool_executor is None or self.config is None: raise RecoverableAgentError("工具执行器未由工厂注入") execution = await self._tool_executor.execute( name=name, arguments=arguments, intent=intent, configured_tools=self.config.allowed_tools_by_intent, context=context, ) self._tool_records.append(execution.record) self._tool_references.extend(execution.references) return execution.output async def generate_with_model( self, endpoints: list[object], prompt: str, *, max_attempts: int = 2 ) -> ModelExecution: if self._model_service is None: raise RecoverableAgentError("模型服务未由工厂注入") return await self._model_service.generate(endpoints, prompt, max_attempts=max_attempts) def __init_subclass__(cls, **kwargs: object) -> None: super().__init_subclass__(**kwargs) forbidden = {"execute", "validate_input", "validate_access", "resolve_config", "recall_memory", "check_compliance", "_execute_governed", "bind_governance", "bind_model_service", "generate_with_model", "bind_tool_executor", "call_tool", "bind_intent_classifier", "classify_intent"} overridden = forbidden.intersection(cls.__dict__) if overridden: raise TypeError(f"Agent cannot override governance methods: {sorted(overridden)}") async def execute( self, request: AgentRequest, context: RequestContext, run_id: str ) -> AsyncIterator[RunProgressEvent]: self.validate_input(request) await self.validate_access(request, context) await self.resolve_config(context) await self.recall_memory(request, context) await self.classify_intent(request) governance, config, memories = self._governance, self.config, self.memories if governance is None or config is None: raise RecoverableAgentError("治理初始化失败") yield RunProgressEvent(event_type="start", run_id=run_id) result = await self._execute_governed(request, context, run_id) # Capture the trusted snapshot before entering business code. result = await governance.review(result, context, config, memories) yield RunProgressEvent( event_type="done", run_id=run_id, payload={"result": result.model_dump(mode="json")}, ) def validate_input(self, request: AgentRequest) -> None: if request.agent_type != self.definition.agent_type: raise ValueError("request agent_type does not match definition") async def validate_access(self, request: AgentRequest, context: RequestContext) -> None: AgentAuthorizer.ensure_allowed(self.definition, context) async def resolve_config(self, context: RequestContext) -> None: if self._governance is None: raise RecoverableAgentError("Agent 未由工厂注入治理依赖") self.config = await self._governance.resolve(self.definition, context) async def recall_memory(self, request: AgentRequest, context: RequestContext) -> None: if self._governance is None: raise RecoverableAgentError("缺少记忆治理依赖") self.memories = await self._governance.recall(context) if any(memory.customer_id != context.user_id for memory in self.memories): raise RecoverableAgentError("记忆召回越过客户范围") async def classify_intent(self, request: AgentRequest) -> IntentResult | None: if self._intent_classifier is None or self._intent_endpoint_resolver is None: return None endpoints = await self._intent_endpoint_resolver.resolve( agent_type=self.definition.agent_type, task_type="intent_classification" ) self._classified_intent = await self._intent_classifier.classify( message=request.message, supported_intents=self.definition.supported_intents, endpoints=endpoints, # 按 agent_type 读取该 Agent 当前生效的意图配置（描述/示例/阈值）。 agent_type=self.definition.agent_type, ) return self._classified_intent async def check_compliance(self, result: AgentResult, context: RequestContext) -> AgentResult: if self._governance is None or self.config is None: raise RecoverableAgentError("缺少合规治理依赖") return await self._governance.review(result, context, self.config, self.memories) async def _execute_governed( self, request: AgentRequest, context: RequestContext, run_id: str ) -> AgentResult: if self.config is None: raise RecoverableAgentError("缺少运行配置") try: async with asyncio.timeout(self.config.timeout_seconds): result = await self.handle(request, context) except TimeoutError as exc: raise UpstreamTimeoutError("Agent 执行超时") from exc result = result.model_copy(update={ "intent": result.intent or self._classified_intent, "tool_calls": tuple(self._tool_records), "source_references": tuple(result.source_references) + tuple(self._tool_references), }) return AgentResult(run_id=run_id, result=result) @abstractmethod async def handle(self, request: AgentRequest, context: RequestContext) -> CoreResult: """Implement domain-specific intent handling here."""