agent-os-base 0.1.2__py3-none-any.whl

agent_base/__init__.py

@@ -0,0 +1,40 @@
+from ag_ui_adk import ADKAgent
+from .kernel.agent_config import AgentConfig, ModelProvider
+from .kernel import Kernel
+
+def create_agent(
+        agent_root_path: str,
+        agent_framework: str,
+        agent_name:str,
+        agent_description:str,
+        agent_instruction: str,
+        model_name: str,
+        model_base_url: str,
+        model_api_key: str,
+        model_temperature: float,
+        is_entrypoint: bool = False,
+        use_memory: bool = False
+):
+    # 生成agent配置文件
+    agent_config = AgentConfig(
+        agent_root_path=agent_root_path if not (agent_root_path is None or agent_root_path == "") else "./",
+        agent_framework=agent_framework if agent_framework in ["adk"] else "adk",
+        agent_name=agent_name if not (agent_name is None or agent_name == "") else "default_agent",
+        description=agent_description if not (
+                    agent_description is None or agent_description == "") else "这是一个默认的智能体",
+        instruction=agent_instruction if not (
+                    agent_instruction is None or agent_instruction == "") else "你是一个乐于助人的智能体助手",
+        provider=ModelProvider(
+            model_name=model_name if not (model_name is None or model_name == "") else "qwen3",
+            model_base_url=model_base_url if not (
+                        model_base_url is None or model_base_url == "") else "http://localhost:8080/v1",
+            model_api_key=model_api_key if not (model_base_url is None or model_base_url == "") else "sk-test",
+            model_temperature=model_temperature
+        ),
+        is_entrypoint=is_entrypoint,
+        use_memory=use_memory
+    )
+
+    # 生成Agent
+    agent_kernel = Kernel(agent_config=agent_config)
+    return agent_kernel.agent

agent_base/kernel/__init__.py

@@ -0,0 +1,12 @@
+from .adk_agent import ADKAgent
+from .agent_config import AgentConfig
+
+
+class Kernel(object):
+    def __init__(self, agent_config: AgentConfig) -> None:
+        if agent_config.agent_framework == "adk":
+            self.agent = ADKAgent(agent_config=agent_config)
+        elif agent_config.agent_framework == "maf":
+            raise ValueError("Microsoft Agent Framework is not yet supported")
+        else:
+            raise ValueError(f"No such framework {agent_config.agent_framework}")

agent_base/kernel/adk_agent.py

@@ -0,0 +1,188 @@
+# !/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Router
+
+Authors: fubo
+Date: 2026/03/19 00:00:00
+"""
+import os
+import sys
+import logging
+import pathlib
+from typing import List, Dict
+import importlib.util
+import inspect
+
+from google.adk.agents.llm_agent import Agent
+from google.adk.models.lite_llm import LiteLlm
+from google.adk.skills import load_skill_from_dir
+from google.adk.tools import skill_toolset, mcp_tool, load_memory
+from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor
+
+from .agent_config import AgentConfig, AgentMCPToolConfig
+
+class ADKAgent(Agent):
+    def __init__(self, agent_config: AgentConfig):
+        super().__init__(
+            model=LiteLlm(
+                model=agent_config.provider.model_name,
+                api_key=agent_config.provider.model_api_key,
+                base_url=agent_config.provider.model_base_url,
+                temperature=agent_config.provider.model_temperature
+            ),
+            name=agent_config.agent_name,
+            description=agent_config.description,
+            instruction=agent_config.instruction,
+            tools=ADKAgent.load_local_function_toolsets(
+                f"{agent_config.agent_root_path}/{agent_config.agent_name}/local-functions"
+            ) + ADKAgent.load_skills(
+                f"{agent_config.agent_root_path}/{agent_config.agent_name}/skills"
+            ) + ADKAgent.load_remote_mcp_toolsets(
+                f"{agent_config.agent_root_path}/{agent_config.agent_name}/mcp-toolsets"
+            ) + [load_memory] if agent_config.use_memory else [],
+            output_key=f"{agent_config.agent_name}-result"
+        )
+
+    @staticmethod
+    def load_functions_from_py_code(code_file_path: str) -> Dict:
+        # 1. 检查文件是否存在
+        if not os.path.isfile(code_file_path):
+            raise FileNotFoundError(f"No such file: {code_file_path}")
+
+        # 2. 生成一个唯一的模块名（避免与已加载模块冲突）
+        base_name = os.path.splitext(os.path.basename(code_file_path))[0]
+        unique_suffix = str(hash(os.path.abspath(code_file_path))).replace('-', '_')
+        module_name = f"{base_name}_{unique_suffix}"
+
+        # 3. 创建模块 spec
+        spec = importlib.util.spec_from_file_location(module_name, code_file_path)
+        if spec is None:
+            raise ImportError(f"Create sepc from {code_file_path}")
+
+        # 4. 创建模块对象并加入 sys.modules
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+
+        # 5. 执行模块代码
+        try:
+            spec.loader.exec_module(module)
+        except Exception as e:
+            raise ImportError(f"Error when load module {module_name}: {e}")
+
+        # 6. 收集模块中定义的顶层函数
+        functions = {}
+        for name, obj in inspect.getmembers(module, inspect.isfunction):
+            # 只取 __module__ 等于当前模块名的函数（即在该模块内定义，非导入）
+            if obj.__module__ == module.__name__:
+                functions[name] = obj
+
+        return functions
+
+    @staticmethod
+    def load_skills(skills_path: str = None) -> List[skill_toolset.SkillToolset]:
+        """Load skills from the skills path."""
+        if skills_path is None:
+            logging.warning(f"The skills path is {skills_path}. No skills will be loaded.")
+            return []
+
+        if not os.path.exists(skills_path):
+            logging.warning(f"No such path named {skills_path}. No skills will be loaded.")
+            return []
+
+        logging.info(f"Loading skills from {skills_path}")
+        skills = []
+        for skill in os.listdir(skills_path):
+            if skill.startswith("."):
+                continue
+            logging.info(f"Loading Skill {skill}")
+            skills.append(load_skill_from_dir(pathlib.Path(skills_path) / skill))
+        skills_toolsets = [
+            skill_toolset.SkillToolset(skills=skills, code_executor=UnsafeLocalCodeExecutor())
+        ]
+        logging.info(f"All skills were loaded count {len(skills)}")
+
+        return skills_toolsets
+
+    @staticmethod
+    def load_local_function_toolsets(local_function_path: str = None) -> List:
+        """加载本地代码函数工具"""
+        functions = []
+        if local_function_path is None:
+            logging.warning(f"The local function code file is {local_function_path}. No function will be loaded.")
+            return []
+
+        if not os.path.exists(local_function_path):
+            logging.warning(f"No such path named {local_function_path}. No functions will be loaded.")
+            return []
+        logging.info(f"Loading local functions from {local_function_path}")
+        for code_file in os.listdir(local_function_path):
+            if not code_file.endswith(".py"):
+                continue
+            functions = functions + list(
+                ADKAgent.load_functions_from_py_code(f"{local_function_path}/{code_file}").values()
+            )
+        logging.info(f"All local functions were loaded function count {len(functions)}")
+        return functions
+
+    @staticmethod
+    def load_remote_mcp_toolsets(mcp_toolset_path: str = None) -> List[mcp_tool.McpToolset]:
+        """加载远端的MCP服务"""
+        toolsets = []
+        if mcp_toolset_path is None:
+            logging.warning(f"The mcp-toolsets is {mcp_toolset_path}. No remote MCP tools will be loaded.")
+            return []
+
+        if not os.path.exists(mcp_toolset_path):
+            logging.warning(f"No such path named {mcp_toolset_path}. No remote MCP tools will be loaded.")
+            return []
+
+        logging.info(f"Loading remote mcp toolsets from {mcp_toolset_path}")
+        for toolset_config_file in os.listdir(mcp_toolset_path):
+            if not toolset_config_file.endswith(".json"):
+                continue
+            # 解析工具集参数
+            logging.info(f"Loading MCP toolset files {toolset_config_file}")
+            toolset_config = AgentMCPToolConfig.parse_file(f"{mcp_toolset_path}/{toolset_config_file}")
+            # 构建mcp工具集
+            if toolset_config.server_type.lower() == "sse":
+                if toolset_config.auth_token is not None and toolset_config.auth_token != "":
+                    toolset = mcp_tool.McpToolset(
+                        connection_params=mcp_tool.mcp_session_manager.SseServerParams(
+                            url=toolset_config.url,
+                            headers=dict(Authorization=f'Bearer {toolset_config.auth_token}')
+                        ),
+                        errlog=None
+                    )
+                else:
+                    toolset = mcp_tool.McpToolset(
+                        connection_params=mcp_tool.mcp_session_manager.SseServerParams(url=toolset_config.url),
+                        errlog=None
+                    )
+
+            elif toolset_config.server_type.lower() == "streamablehttp":
+                if toolset_config.auth_token is not None and toolset_config.auth_token != "":
+                    toolset = mcp_tool.McpToolset(
+                        connection_params=mcp_tool.mcp_session_manager.StreamableHTTPServerParams(
+                            url=toolset_config.url,
+                            headers=dict(Authorization=f'Bearer {toolset_config.auth_token}')
+                        ),
+                        errlog=None
+                    )
+                else:
+                    toolset = mcp_tool.McpToolset(
+                        connection_params=mcp_tool.mcp_session_manager.StreamableHTTPServerParams(
+                            url=toolset_config.url
+                        ),
+                        errlog=None
+                    )
+            else:
+                toolset = None
+
+            if toolset is not None:
+                toolsets.append(toolset)
+
+        logging.info(f"All MCP toolsets were loaded count {len(toolsets)}")
+
+        return toolsets

agent_base/kernel/agent_config.py

@@ -0,0 +1,48 @@
+# !/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Router
+
+Authors: fubo
+Date: 2026/03/19 00:00:00
+"""
+from pydantic import BaseModel
+
+class AgentMCPToolConfig(BaseModel):
+    # toolse name
+    name: str
+    # Server URL
+    url: str
+    # 服务类型
+    server_type: str = "StreamableHTTP"
+    # Auth
+    auth_token: str = ""
+
+class ModelProvider(BaseModel):
+    # 使用的模型名
+    model_name: str
+    # 模型api key
+    model_api_key: str
+    # 模型base url
+    model_base_url: str
+    # 模型参数温度
+    model_temperature: float = 0.0
+
+class AgentConfig(BaseModel):
+    # 智能体所在路径
+    agent_root_path: str
+    # 智能体框架
+    agent_framework: str
+    # 智能体名
+    agent_name: str
+    # 智能体描述
+    description: str = ""
+    # 智能体instruction
+    instruction: str = ""
+    # LLM配置
+    provider: ModelProvider
+    # 是否智能体入口
+    is_entrypoint: bool = False
+    # 是否使用memory
+    use_memory: bool = False

agent_base/main.py

@@ -0,0 +1,144 @@
+# !/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Router
+
+Authors: fubo
+Date: 2026/03/19 00:00:00
+"""
+
+import sys
+import argparse
+
+from .kernel.agent_config import AgentConfig, ModelProvider, AgentMCPToolConfig
+from .operator import Operator
+
+def commander():
+    parser = argparse.ArgumentParser(description="智能体系统构建")
+    parser.add_argument("-an", "--agent-name", required=True, help="智能体名称")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # create-agent 子命令
+    parser_create_agent = subparsers.add_parser("create-agent", help="创建智能体")
+    parser_create_agent.add_argument(
+        "-af", "--agent_framework",
+        required=True, help="智能体框架（adk/maf）"
+    )
+    parser_create_agent.add_argument(
+        "-ad", "--agent-description",
+        required=True, help="智能体描述信息"
+    )
+    parser_create_agent.add_argument(
+        "-ai", "--agent-instruction",
+        required=True, help="智能体instruction"
+    )
+    parser_create_agent.add_argument(
+        "-mdu", "--model-url",
+        required=True, help="智能体使用的模型base url"
+    )
+    parser_create_agent.add_argument(
+        "-mdn", "--model-name",
+        required=True, help="智能体使用的模型名称"
+    )
+    parser_create_agent.add_argument(
+        "-mdk", "--model-api-key",
+        required=True, help="智能体使用的模型服务API-KEY"
+    )
+    parser_create_agent.add_argument(
+        "-mdt", "--model-temperature",
+        type=float, required=False, default=0.0, help="智能体使用的模型温度"
+    )
+    parser_create_agent.add_argument(
+        "-ie", "--is-entrypoint",
+        type=bool, required=True, default=False, help="该智能体是否入口智能体"
+    )
+    parser_create_agent.add_argument(
+        "-um", "--use-memory",
+        type=bool, required=True, default=False, help="智能体是否使用长期记忆"
+    )
+
+    # create-skill 子命令
+    parser_create_skill_tool = subparsers.add_parser("create-skill", help="创建智能体skill")
+    parser_create_skill_tool.add_argument(
+        "-c", "--config",
+        required=True, help="智能体配置文件agent_config.yml"
+    )
+
+    # create-local-function-tools 子命令
+    parser_create_local_function_tool = subparsers.add_parser(
+        "create-local-function-tool",
+        help="创建智能体本地函数工具"
+    )
+    parser_create_local_function_tool.add_argument(
+        "-c", "--config",
+        required=True, help="智能体配置文件agent_config.yml"
+    )
+
+    # create-mcp-toolset 子命令
+    parser_create_mcp_tool = subparsers.add_parser("create-mcp-toolset", help="创建智能体mcp工具集")
+    parser_create_mcp_tool.add_argument(
+        "-mpn", "--mcp-name",
+        required=True, help="MCP工具集名"
+    )
+    parser_create_mcp_tool.add_argument(
+        "-mpu", "--mcp-url",
+        required=True, help="MCP工具集url"
+    )
+    parser_create_mcp_tool.add_argument(
+        "-mpst", "--mcp-server-type",
+        required=True, help="MCP工具集服务类型SSE/StreamableHTTP"
+    )
+    parser_create_mcp_tool.add_argument(
+        "-mpat", "--mcp-auth-token",
+        required=False, default="", help="MCP工具集auth token"
+    )
+
+    return parser
+
+
+def command_parser(parser: argparse.ArgumentParser):
+    # main_args_parser: argparse.ArgumentParser,
+    args = parser.parse_args()
+    if args.command == "create-agent":
+        Operator.create_agent(
+            AgentConfig(
+                agent_root_path="./",
+                agent_framework=args.agent_framework,
+                agent_name=args.agent_name,
+                description=args.agent_description,
+                instruction=args.agent_instruction,
+                provider=ModelProvider(
+                    model_base_url=args.model_url,
+                    model_name=args.model_name,
+                    model_api_key=args.model_api_key,
+                    model_temperature=args.model_temperature
+                ),
+                is_entrypoint=args.is_entrypoint,
+                use_memory=args.use_memory,
+            )
+        )
+    elif args.command == "create-skill":
+        Operator.create_skill_tool(args.config)
+    elif args.command == "create-local-function-tool":
+        Operator.create_local_function_tool(args.config)
+    elif args.command == "create-mcp-toolset":
+        Operator.create_mcp_toolset(
+            agent_name=args.agent_name,
+            agent_mcp_toolset_config=AgentMCPToolConfig(
+                name=args.mcp_name,
+                url=args.mcp_url,
+                server_type=args.mcp_server_type,
+                auth_token=args.mcp_auth_token
+            )
+        )
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+def main():
+    command_parser(commander())
+
+if __name__ == "__main__":
+    main()

agent_base/observability/tracing.py

@@ -0,0 +1,17 @@
+def setup_tracing(endpoint_host: str, experiment_id: int):
+    from opentelemetry import trace
+    tracer = trace.get_tracer(__name__)
+    with tracer.start_as_current_span("test-span"):
+        print("trace test")
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    provider = TracerProvider()
+
+    exporter = OTLPSpanExporter(
+        endpoint=f"{endpoint_host}/v1/traces",
+        headers={"x-mlflow-experiment-id": str(experiment_id)}
+    )
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)

agent_base/operator.py

@@ -0,0 +1,98 @@
+# !/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Router
+
+Authors: fubo
+Date: 2026/03/19 00:00:00
+"""
+import os
+import json
+import logging
+from .kernel.agent_config import AgentConfig, AgentMCPToolConfig
+
+class Operator:
+    @staticmethod
+    def replace_placeholder(file_name: str, replacement_data: dict) -> str:
+        with open(file_name, "r") as fp:
+            content = fp.read()
+        for key in replacement_data:
+            content = content.replace(key, replacement_data[key])
+        return content
+
+    @staticmethod
+    def create_agent(agent_config: AgentConfig):
+        logging.info(f"Creating agent from config: {agent_config}")
+
+        # # 这里调用 google-adk 相关逻辑
+        agent_root_path = f"./{agent_config.agent_name}"
+        template_file_path = os.path.dirname(os.path.abspath(__file__)) + "/templates"
+
+        # 构建Agent文件夹
+        os.system(f"mkdir {agent_root_path}")
+        os.system(f"touch {agent_root_path}/.env")
+        os.system(f"mkdir -p {agent_root_path}/skills")
+        os.system(f"mkdir -p {agent_root_path}/local-functions")
+        os.system(f"mkdir -p {agent_root_path}/mcp-toolsets")
+
+        # 添加local-function的代码文件
+        os.system(f"touch {agent_root_path}/local-functions/function_toolset.py")
+
+        # 写入智能体代码
+        os.system(f'echo "from . import agent" >> {agent_root_path}/__init__.py')
+        agent_py_code_template_file = template_file_path + "/agent.py.template"
+        open(f"{agent_root_path}/agent.py", "w").write(
+            Operator.replace_placeholder(
+                agent_py_code_template_file,
+                {"#[OpentelemetryTraceLine] ": ""}
+            ) if not(agent_config.trace_endpoint_host is None or agent_config.trace_endpoint_host == "") else Operator.replace_placeholder(
+                agent_py_code_template_file,
+                {}
+            )
+        )
+
+        # os.system(f"cp {agent_py_code_template_file} {agent_root_path}/agent.py")
+        dotenv_template_file = template_file_path + "/env.template"
+        with open(f"{agent_root_path}/.env", "w") as fp:
+            fp.write(
+                Operator.replace_placeholder(
+                    dotenv_template_file,
+                    {
+                        "[agent-framework]": agent_config.agent_framework,
+                        "[agent-name]": agent_config.agent_name,
+                        "[agent-description]": agent_config.description,
+                        "[agent-instruction]": agent_config.instruction,
+                        "[model-base-url]": agent_config.provider.model_base_url,
+                        "[model-name]": agent_config.provider.model_name,
+                        "[model-temperature]": str(agent_config.provider.model_temperature),
+                        "[model-api-key]": agent_config.provider.model_api_key,
+                        "[is-entrypoint]": agent_config.is_entrypoint,
+                        "[use-memory]": agent_config.use_memory,
+                    }
+                )
+            )
+
+    @staticmethod
+    def create_skill_tool(config_file):
+        """创建技能和工具"""
+        pass
+
+    @staticmethod
+    def create_local_function_tool(config_file):
+        """创建本地函数工具"""
+
+    @staticmethod
+    def create_mcp_toolset(agent_name: str, agent_mcp_toolset_config: AgentMCPToolConfig):
+        """为智能体创建MCP工具集配置文件"""
+        toolsets_path = f"./{agent_name}/mcp-toolsets"
+        logging.info(f"Add MCP Toolset{agent_mcp_toolset_config.name}.json to {toolsets_path}")
+        if not os.path.exists(toolsets_path):
+            logging.error(f"No such agent and agent mcp-toolsets {toolsets_path}")
+            return
+
+        open(
+            f"{toolsets_path}/{agent_mcp_toolset_config.name}.json", "w"
+        ).write(
+            json.dumps(agent_mcp_toolset_config.dict(), ensure_ascii=False)
+        )

agent_base/templates/agent.py.template

@@ -0,0 +1,22 @@
+import os
+from dotenv import dotenv_values
+
+from agent_base import create_agent
+
+
+file_path = os.path.dirname(os.path.abspath(__file__))
+config = dotenv_values(file_path + "/.env")
+
+root_agent = create_agent(
+    agent_root_path=file_path + "/../",
+    agent_framework=config.get("AGENT_FRAMEWORK"),
+    agent_name=config.get("AGENT_NAME"),
+    agent_description=config.get("AGENT_DESCRIPTION"),
+    agent_instruction=config.get("AGENT_INSTRUCTION"),
+    model_name=config.get("MODEL_NAME"),
+    model_base_url=config.get("MODEL_BASE_URL"),
+    model_api_key=config.get("MODEL_API_KEY"),
+    model_temperature=float(config.get("MODEL_TEMPERATURE")),
+    is_entrypoint=bool(config.get("IS_ENTRYPOINT")),
+    use_memory=bool(config.get("USE_MEMORY"))
+)

agent_base/templates/env.template

@@ -0,0 +1,10 @@
+AGENT_FRAMEWORK=[agent-framework]
+AGENT_NAME=[agent-name]
+AGENT_DESCRIPTION=[agent-description]
+AGENT_INSTRUCTION=[agent-instruction]
+MODEL_BASE_URL=[model-base-url]
+MODEL_API_KEY=[model-api-key]
+MODEL_NAME=[model-name]
+MODEL_TEMPERATURE=[model-temperature]
+IS_ENTRYPOINT=[is-entrypoint]
+USE_MEMORY=[use-memory]

agent_os_base-0.1.2.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: agent-os-base
+Version: 0.1.2
+Summary: 基础智能体构建库
+Author-email: fubo <fb_linux@163.com>
+License: MIT
+Project-URL: Homepage, https://codeup.aliyun.com/64650c96168f0a5963451dec/agi-next/agent-base/blob/master/README.md
+Project-URL: Repository, https://codeup.aliyun.com/64650c96168f0a5963451dec/agi-next/agent-base.git
+Keywords: agent
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-adk[extensions]>=1.27.0
+Requires-Dist: pydantic_yaml>=1.6.0
+Requires-Dist: aiomysql
+Requires-Dist: ag_ui_adk
+Provides-Extra: test
+Requires-Dist: pytest>=6.0; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# agent-base
+
+`agent-base` 是一个用于快速搭建智能体项目脚手架的 Python 库，核心目标是：
+
+- 通过 CLI 一键创建智能体工程目录
+- 自动生成 `.env`、`agent.py`、技能目录、本地函数目录、MCP 工具集目录
+- 基于 `google-adk` 统一加载模型、Skills、本地函数工具、远端 MCP 工具
+
+---
+
+## 项目结构
+
+核心代码位于 `src/agent_base`：
+
+- `main.py`：CLI 入口，解析命令并分发到 `Operator`
+- `operator.py`：脚手架生成与文件落地逻辑
+- `agent_config.py`：配置数据模型（Pydantic）
+- `adk_agent.py`：智能体运行时封装，负责动态加载工具与技能
+- `observability/tracing.py`：OpenTelemetry Trace 初始化
+- `templates/*.template`：新建智能体时使用的代码和环境变量模板
+
+---
+
+## 依赖与版本
+
+`pyproject.toml` 中定义：
+
+- Python: `>=3.10`
+- 核心依赖：
+  - `google-adk[extensions]>=1.27.0`
+  - `pydantic_yaml>=1.6.0`
+- 命令行入口：
+  - `agent-base = agent_base.main:main`
+
+---
+
+## CLI 功能说明
+
+### 1) 创建智能体
+
+```bash
+agent-base -an <agent_name> create-agent \
+  -ad "<description>" \
+  -ai "<instruction>" \
+  -mdu "<model_base_url>" \
+  -mdn "<model_name>" \
+  -mdk "<model_api_key>" \
+  -mdt 0.0 \
+  -teh "<trace_endpoint_host>"
+```
+
+执行后会在当前目录下生成：
+
+```text
+./<agent_name>/
+  ├── .env
+  ├── __init__.py
+  ├── agent.py
+  ├── skills/
+  ├── local-functions/
+  │   └── function_toolset.py
+  └── mcp-toolsets/
+```
+
+### 2) 创建 MCP 工具集配置
+
+```bash
+agent-base -an <agent_name> create-mcp-toolset \
+  -mpn "<mcp_name>" \
+  -mpu "<mcp_url>" \
+  -mpst "SSE|StreamableHTTP" \
+  -mpat "<optional_token>"
+```
+
+会在 `./<agent_name>/mcp-toolsets/` 下生成对应 JSON 配置文件。
+
+### 3) 预留命令（尚未实现）
+
+- `create-skill`
+- `create-local-function-tool`
+
+当前在 `operator.py` 中仍是占位实现（`pass` 或空函数体）。
+
+---
+
+## 运行时加载机制（ADKAgent）
+
+`ADKAgent` 初始化时会把三类能力合并到 `tools`：
+
+1. **本地函数工具**  
+   扫描 `./<agent_name>/local-functions/*.py`，通过动态 import 抽取顶层函数并注册。
+
+2. **Skills**  
+   扫描 `./<agent_name>/skills/*`，使用 `google.adk.skills.load_skill_from_dir` 加载后封装为 `SkillToolset`。
+
+3. **远端 MCP 工具**  
+   扫描 `./<agent_name>/mcp-toolsets/*.json`，按 `server_type` 构建：
+   - `SSE` -> `SseServerParams`
+   - `StreamableHTTP` -> `StreamableHTTPServerParams`
+
+---
+
+## Trace 能力
+
+当提供 `TRACE_ENDPOINT_HOST` 时，会调用 `setup_tracing(endpoint_host, experiment_id)`：
+
+- 使用 OTLP HTTP exporter 上报到 `${endpoint_host}/v1/traces`
+- 额外写入 header：`x-mlflow-experiment-id`
+
+`experiment_id` 在示例中由当前时间戳（毫秒）生成。
+
+---
+
+## 示例代码分析（tests/test_agent）
+
+你本地示例目录中的 `tests/test_agent/agent.py` 展示了最小可运行初始化流程：
+
+1. 读取 `.env`（`dotenv`）
+2. 初始化 tracing（可选）
+3. 组装 `AgentConfig` + `ModelProvider`
+4. 构造 `root_agent = ADKAgent(...)`
+
+示例技能中包含：
+
+- `skills/calculator`：通过 `scripts/calculate.py` 提供加减乘除脚本工具
+- `skills/comment-news`：给出“先搜新闻，再客观评价”的技能流程
+- `skills/tavily-search`：封装 Tavily CLI 的检索能力（含安装与命令范式）
+
+---
+
+## 当前实现特点与注意事项
+
+### 已具备
+
+- 模板化创建智能体工程
+- 统一配置模型参数与工具加载
+- 可加载本地函数 + Skills + MCP toolsets
+
+### 需要注意
+
+- `operator.py` 使用 `os.system` 进行目录与文件创建，后续可考虑改为 `pathlib`/`shutil` 提高可维护性与安全性。
+- `create-skill`、`create-local-function-tool` 还未完成。
+- 示例 `.env` 中出现了真实样式的 API Key，建议立即替换并避免提交到版本库（应使用环境注入或密钥管理）。
+
+---
+
+## 快速开始（建议流程）
+
+1. 安装依赖并安装本包（开发模式）
+2. 通过 `agent-base ... create-agent` 生成智能体目录
+3. 在 `skills/` 与 `local-functions/` 中补充能力
+4. 根据需要添加 `mcp-toolsets/*.json`
+5. 在生成的 `agent.py` 中实例化并运行智能体
+
+如需扩展，建议优先补齐 `create-skill` 与 `create-local-function-tool` 的自动化生成能力，这样项目可以形成完整的“从 0 到可运行”脚手架闭环。

agent_os_base-0.1.2.dist-info/RECORD

@@ -0,0 +1,17 @@
+agent_base/__init__.py,sha256=lX9dwUBc5qAsfT82h2eJOcK9DGCh2VJbfssVaSd7Llk,1788
+agent_base/main.py,sha256=KKP5ef7RiZE9KtTTPU4xaoLSe4E8kYu9Kg7_9wD3WLs,4860
+agent_base/operator.py,sha256=Ft_PM7z5ScypAgviNvPDKEeKoYhLxsR4rYYaOg6geS0,3924
+agent_base/kernel/__init__.py,sha256=9kPXAo4PbVKdVMuM6pkylavV-cPB8kpHhIF-zIF-6Z8,490
+agent_base/kernel/adk_agent.py,sha256=T05_botHoNudNwqQNfIvulE_JztHivV9IzXBjK1F20A,7968
+agent_base/kernel/agent_config.py,sha256=rmIVmhoId9lFVRUdOFJLN3BIYcv2-FXAPbmzw3w30Ko,986
+agent_base/observability/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_base/observability/tracing.py,sha256=v8L0nbKrIik2mKwOUFbO0UaNbFHkcgBPcdGyaAuJuMc,707
+agent_base/templates/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_base/templates/agent.py.template,sha256=e5jjzuj0yMlKZseEdOWhM8XLCR51j-HafRkUTErzcxc,750
+agent_base/templates/env.template,sha256=6Ock2w_UvE2DkS0tBYTtbIqUz8Kv0hQFdITk_EPO7Ks,311
+agent_os_base-0.1.2.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_os_base-0.1.2.dist-info/METADATA,sha256=DEmp9bQ6nseXQxdw0c7wYc9WS9-hdrPUcuBfHE_wdVE,5357
+agent_os_base-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agent_os_base-0.1.2.dist-info/entry_points.txt,sha256=Q1XCeNmmtWzlKAJN2walA5EaqyUbzr1fCVyP6gdDxHA,52
+agent_os_base-0.1.2.dist-info/top_level.txt,sha256=poXpCRC5jAU_cOzLbf-90Fl43p4DAYyzu_jJgo6JpzI,11
+agent_os_base-0.1.2.dist-info/RECORD,,

agent_os_base-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_os_base-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-base = agent_base.main:main

agent_os_base-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_base