from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any


class BaseAgent(ABC):
    """
    智能体基类。

    该类定义了系统中所有智能体的统一接口与基础属性，便于在编排层中进行
    标准化调用、日志追踪、配置注入和生命周期管理。

    Attributes:
        agent_name: 智能体名称，用于日志与监控标识。
        config: 智能体配置字典，存放模型路径、阈值、API 参数等。
    """

    def __init__(self, agent_name: str, config: dict[str, Any] | None = None) -> None:
        """
        初始化智能体基类。

        Args:
            agent_name: 智能体名称。
            config: 可选配置项；若不提供，默认初始化为空字典。
        """
        self.agent_name = agent_name
        self.config = config or {}

    @abstractmethod
    def run(self, **kwargs: Any) -> Any:
        """
        智能体统一执行入口（抽象方法）。

        子类必须实现该方法，并根据自身职责定义 kwargs 的输入结构与返回值类型。

        Args:
            **kwargs: 子类自定义参数。

        Returns:
            任意类型结果，由子类具体约定。
        """
        raise NotImplementedError