CometAgent.NEXT测试版上线

CometAgentNEXT/AGENTS.md

@@ -0,0 +1,265 @@
+# AGENTS.md
+
+This file provides guidance to Qoder (qoder.com) when working with code in this repository.
+
+## Common Commands
+
+### Setup
+```bash
+pip install -r requirements.txt
+cp .env.example .env
+```
+
+### Running the Application
+```bash
+python cli.py
+```
+
+### Running Examples
+```bash
+python examples/basic_usage.py
+python examples/test_plugins.py
+```
+
+### Testing
+```bash
+pytest tests/ -v
+```
+
+## Architecture Overview
+
+### Core Components
+
+**LLM Environment Loading Pattern** (src/env_loader.py)
+- Uses direct environment variable loading integrated into EnvLoader class
+- Eliminates factory pattern complexity completely
+- Supports only essential providers: openai, anthropic
+- All provider settings are configured via environment variables loaded through EnvLoader
+- LLM client creation unified within EnvLoader.create_llm_client() method
+
+**Agent System** (src/agent/agent.py)
+- Agents are configured with AgentConfig dataclass (name, role, goal, llm_provider, memory settings, tools, plugin settings)
+- New plugin-related config options:
+  - enable_plugins (bool): Enable plugin system (default: True)
+  - plugin_directory (str): Path to plugins directory (default: ".CometPlugins")
+  - use_builtin_tools (bool): Use legacy builtin_tools (default: False, for backward compatibility)
+- Two agent types available:
+  - Agent: Standard agent implementation
+  - ReactAgent: ReAct规范的Agent实现，结合推理(Reasoning)和行动(Action)框架
+- Each agent has: llm_client, tool_registry, memory, conversation_history
+- Agent.run() implements iterative loop with tool calling:
+  - Sends messages to LLM with available tools
+  - Executes tool calls returned by LLM
+  - Appends tool results to conversation
+  - Continues until LLM provides final response (max_iterations limit)
+- Memory integration: automatically saves user/assistant messages to memory if enabled
+- System prompt is auto-generated from role/goal unless custom system_prompt provided
+- Plugin integration: When enable_plugins=True, automatically loads plugins from plugin_directory
+
+**Prompt System** (src/agent/prompt.py)
+- 独立的Prompt处理模块，负责生成和管理Agent的系统提示
+- 支持两种提示生成方式：
+  - 标准提示：适用于普通Agent
+  - ReAct提示：适用于ReactAgent，包含ReAct思考框架指导
+- 可通过PromptConfig自定义提示参数
+- 支持从角色和目标自动生成系统提示
+
+**Tool & Plugin System** (src/plugins/base.py)
+- 合并了原有的tools和plugins目录，统一为插件系统
+- ToolRegistry manages available tools
+- Tools defined with name, description, parameters (ToolParameter: name, type, description, required)
+- Tools converted to OpenAI function calling format via to_openai_format()
+- Supports both sync and async tool functions
+- Built-in tools are now part of the plugin system in src/plugins/builtin_tools.py
+- Modern replacement for builtin_tools with extensible plugin architecture
+- BasePlugin: Abstract base class for all plugins with initialize(), get_tools(), shutdown() methods
+- PluginRegistry: Manages plugin lifecycle (load, register, unload)
+- PluginMetadata: Describes plugin information (name, version, author, dependencies, etc.)
+- Plugin types: BUILTIN (core), SYSTEM (framework), EXTERNAL (third-party/user)
+- Plugins stored in .CometPlugins/ directory with manifest.json and plugin.py
+- Supports decorator syntax (@register_tool_function) and manual tool registration
+- Hot reload capability: plugins can be loaded/unloaded at runtime
+- See .CometPlugins/README.md for complete plugin development guide
+
+**BuiltinTools Plugin** (src/plugins/builtin_tools.py)
+- Core built-in plugin providing essential tools
+- Tools: web_search, calculate, read_file, write_file, http_request
+- Automatically loaded when enable_plugins=True in AgentConfig
+
+**Memory System** (src/memory/base.py)
+- Three memory implementations:
+  - ShortTermMemory: Fixed-size FIFO buffer (default 50 entries)
+  - LongTermMemory: Persistent storage with inverted index for fast search
+  - HybridMemory: Combines both short-term and long-term (recommended)
+- MemoryEntry contains: content, role, timestamp, metadata, optional embedding
+- Search uses word-based inverted index scoring in LongTermMemory
+- HybridMemory.search() combines results from both memory types
+
+**MetaAgent Orchestration** (src/group/meta_agent.py)
+- MetaAgent manages multiple agents and coordinates workflows
+- Supports loading agents from `config.json` via `load_agents_from_config()` method
+- Four workflow types:
+  - sequential_workflow: Agents execute tasks in order, optionally sharing context
+  - parallel_workflow: Multiple agents work simultaneously using asyncio.gather
+  - hierarchical_workflow: Manager agent decomposes task into subtasks for workers, then synthesizes results
+  - dynamic_workflow: Coordinator agent dynamically decides task allocation using DELEGATE/REQUEST/COMPLETE actions
+- TaskResult captures agent_name, task, result, timestamp, metadata
+- Task history stored for all completed tasks
+
+**Configuration** (src/config.py)
+- Uses pydantic-settings for environment-based configuration
+- Settings class defines all API keys, base URLs, models, and general parameters
+- Singleton pattern via @lru_cache() in get_settings()
+- Supports .env file loading via env_loader.py
+- Each provider has dedicated api_key, base_url, model settings
+
+**Environment Loading System** (src/env_loader.py)
+- New module for loading .env files with improved logic
+- Loads .env file from current working directory first, then from project root directory
+- Uses dotenv library for loading environment variables
+- Ensures consistent environment loading across the application
+- Supports both user-specific and system-level .env files
+
+### Key Design Patterns
+
+1. **Async-First**: All agent operations, tool execution, and memory operations use async/await
+2. **OpenAI Function Calling Format**: All LLM clients normalize to OpenAI's tool calling format internally
+3. **Lazy Initialization**: Memory and tool registries created on-demand if not provided to Agent constructor
+4. **Manager Pattern**: EnvLoader.create_llm_client() centralizes client instantiation logic with direct env loading
+5. **Registry Pattern**: ToolRegistry for tool discovery and execution; PluginRegistry for plugin management
+6. **Hybrid Storage**: Memory system combines in-memory short-term with persistent long-term storage
+7. **Plugin Architecture**: Modular, extensible plugin system with hot reload support
+
+### Adding New LLM Providers
+
+**Current Support**: Only openai and anthropic providers are supported for simplicity.
+
+To add a new provider compatible with OpenAI format:
+1. Add provider settings to .env file with corresponding API key, base URL, and model
+2. Add elif branch in EnvLoader.create_llm_client() returning OpenAIClient with custom base_url
+
+For non-OpenAI-compatible providers:
+1. Create new client class inheriting from BaseLLMClient in src/llm/
+2. Implement chat() and chat_stream() methods
+3. Add import and factory logic to EnvLoader
+
+### Agent Iteration Loop
+
+The agent's run() method implements a tool-calling loop:
+1. User message added to conversation_history
+2. Loop up to max_iterations times:
+   - Call LLM with conversation history and available tools
+   - If LLM returns tool_calls:
+     - Add assistant message with tool_calls to history
+     - Execute each tool via ToolRegistry.execute_tool()
+     - Add tool results to conversation as role="tool" messages
+   - If LLM returns content without tool_calls:
+     - This is the final response, break loop
+3. Return final response content
+
+### Creating Custom Plugins
+
+To create a custom plugin:
+1. Create directory in .CometPlugins/ with your plugin name
+2. Add manifest.json with plugin metadata (name, version, author, description, dependencies, etc.)
+3. Create plugin.py with a Plugin class inheriting from BasePlugin
+4. Implement initialize() to register tools using @self.register_tool_function decorator
+5. Implement get_tools() to return list of tools
+6. Optional: Add shutdown() for cleanup and README.md for documentation
+
+Example plugin structure:
+```python
+from src.plugins import BasePlugin, PluginMetadata, Tool, ToolParameter
+
+class Plugin(BasePlugin):
+    def initialize(self):
+        @self.register_tool_function(
+            name="my_tool",
+            description="Tool description",
+            parameters=[ToolParameter(...)]
+        )
+        async def my_tool(param: str) -> str:
+            return f"Processed: {param}"
+
+    def get_tools(self):
+        return list(self.tools.values())
+```
+
+See .CometPlugins/README.md for comprehensive plugin development guide.
+
+## Recent Changes
+
+### Environment Loading Pattern Migration
+
+**Changes Made:**
+1. **Deleted**: `src/llm/llm_manager.py` - Removed the LLMManager class for simplification
+2. **Updated**: `src/env_loader.py` - Integrated LLM client creation methods directly into EnvLoader class
+3. **Updated**: `src/agent/agent.py` - Replaced LLMManager.create_client() with EnvLoader.create_llm_client()
+4. **Updated**: `src/llm/__init__.py` - Removed LLMManager import and export
+5. **Updated**: `src/__init__.py` - Added EnvLoader import and removed LLMManager
+6. **Updated**: `AGENTS.md` - Updated documentation to reflect Environment Loading pattern
+
+**Migration Benefits:**
+1. **Simplified Architecture**: LLM client creation now unified in one class (EnvLoader)
+2. **Reduced Dependencies**: Eliminated separate llm_manager.py file
+3. **Direct Environment Access**: All environment variable handling in one place
+4. **Limited Providers**: Only openai and anthropic for better maintainability
+
+**Usage:**
+- Use `EnvLoader.create_llm_client()` to create LLM clients
+- All environment variables loaded via `EnvLoader.load_env()`
+- Configure providers through `.env` file
+
+### Group/MetaAgent Migration
+
+**Changes Made:**
+1. Renamed `src/orchestration/` to `src/group/`
+2. Renamed `orchestrator.py` to `meta_agent.py`
+3. Renamed `MultiAgentOrchestrator` class to `MetaAgent`
+4. Added `load_agents_from_config(config_path="config.json")` method to dynamically load agents from JSON config
+5. Created `src/group/config.json` with example agents (coder, reviewer, tester)
+6. Updated `src/__init__.py` imports to reflect new structure
+
+**New Usage:**
+- `meta = MetaAgent()`
+- `meta.load_agents_from_config()`  # Loads agents from config.json
+- Use workflows: `await meta.sequential_workflow(tasks, share_context=True)` etc.
+
+### CrossToolsCall Cross-Agent Tool Calling
+
+**Changes Made:**
+1. Created `src/CometSpaceX/CrossToolsCall/` module with `CrossToolCaller` class and `__init__.py`.
+2. Added `cross_tool_call(agents, target_agent, tool_name, arguments)` and `list_cross_tools(agents, target_agent)` methods to `Agent` class.
+
+**Features:**
+- `CrossToolCaller` aggregates tool registries from multiple agents for shared tool access.
+- Enables any agent to call tools registered in other agents' `tool_registry`.
+- Supports async tool execution across agent boundaries.
+
+**Integration with MetaAgent:**
+- In workflows like `sequential_workflow` or `dynamic_workflow`, agents can invoke tools from collaborators.
+- Pass agent dict `meta.agents` to enable cross-calling.
+
+**Example Usage:**
+```python
+from src.agent.agent import Agent
+from src.CometSpaceX.CrossToolsCall import CrossToolCaller
+
+# Assume agents loaded via MetaAgent
+agents = meta.agents  # {'coder': coder_agent, 'tester': tester_agent}
+
+# List tester's tools from coder
+coder_tools = coder_agent.list_cross_tools(agents, 'tester')
+print(coder_tools)
+
+# Coder calls tester's tool
+result = await coder_agent.cross_tool_call(
+    agents, 'tester', 'run_tests', {'path': 'src/agent/'}
+)
+print(result)
+```
+
+**Benefits:**
+- Enables tool sharing without duplicating registries.
+- Supports MetaAgent multi-agent collaboration with plugin interoperability.
+- Minimal code changes, follows existing async patterns.