agent2 0.1.0__tar.gz

agent2-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+src/**/__pycache__/
+src/**/*.pyc

agent2-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: agent2
+Version: 0.1.0
+Summary: A modular agent system framework for learning and research
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=2.44.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Provides-Extra: all-llm
+Requires-Dist: anthropic>=0.30; extra == 'all-llm'
+Requires-Dist: google-genai>=1.0; extra == 'all-llm'
+Requires-Dist: openai>=1.30; extra == 'all-llm'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: google
+Requires-Dist: google-genai>=1.0; extra == 'google'
+Provides-Extra: memory
+Requires-Dist: numpy>=1.26; extra == 'memory'
+Provides-Extra: openai
+Requires-Dist: openai>=1.30; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Agent2 — 模块化 Agent 系统框架
+
+一个从零构建的 Python Agent 系统框架，用于深入理解 AI Agent 的核心架构和设计模式。
+
+## 核心特性
+
+| 特性 | 说明 |
+|------|------|
+| 🧠 **LLM 抽象层** | 统一接口支持 OpenAI / Anthropic / Google / Ollama |
+| 🔧 **工具系统** | `@tool` 装饰器自动生成 JSON Schema，支持同步/异步 |
+| 🔄 **ReAct 模式** | Thought → Action → Observation 推理循环 |
+| 📋 **Plan-and-Execute** | 先规划后执行，支持动态重规划 |
+| 🪞 **自我反思** | ReflectionMixin 添加输出自评和迭代改进 |
+| 💾 **记忆系统** | 短期 (WorkingMemory) + 长期 (LongTermMemory/TF-IDF) |
+| 👥 **多 Agent 编排** | 顺序/监督者/辩论 三种协作模式 |
+
+## 快速开始
+
+```bash
+# 安装
+uv pip install -e "."
+
+# 安装 LLM 提供商 SDK（按需）
+uv pip install -e ".[openai]"      # OpenAI
+uv pip install -e ".[all-llm]"     # 所有 LLM
+
+# 设置 API Key
+export AGENT2_OPENAI_API_KEY=sk-...
+```
+
+### 最简示例
+
+```python
+import asyncio
+from agent2.llm import create_llm
+from agent2.agent import ReActAgent
+from agent2.tools.builtin import python_exec
+
+async def main():
+    llm = create_llm("openai", model="gpt-4o-mini")
+    agent = ReActAgent("assistant", llm=llm, tools=[python_exec])
+    result = await agent.run("What is 2^100?")
+    print(result)
+
+asyncio.run(main())
+```
+
+## 示例
+
+```bash
+uv run examples/01_single_agent.py   # 单 Agent ReAct
+uv run examples/02_tool_use.py       # 自定义工具
+uv run examples/03_planning.py       # Plan-and-Execute
+uv run examples/04_memory.py         # 记忆系统（无需 API Key）
+uv run examples/05_multi_agent.py    # 多 Agent 协作
+```
+
+## 架构
+
+```
+agent2/
+├── llm/        # LLM 抽象层 — 统一多提供商接口
+├── tools/      # 工具系统 — @tool 装饰器 + Registry
+├── agent/      # Agent 核心 — ReAct / Planner / Reflection
+├── memory/     # 记忆系统 — Working / LongTerm
+├── crew/       # 多 Agent — Sequential / Supervisor / Debate
+└── utils/      # 配置 + 日志
+```
+
+## License
+
+MIT

agent2-0.1.0/README.md

@@ -0,0 +1,72 @@
+# Agent2 — 模块化 Agent 系统框架
+
+一个从零构建的 Python Agent 系统框架，用于深入理解 AI Agent 的核心架构和设计模式。
+
+## 核心特性
+
+| 特性 | 说明 |
+|------|------|
+| 🧠 **LLM 抽象层** | 统一接口支持 OpenAI / Anthropic / Google / Ollama |
+| 🔧 **工具系统** | `@tool` 装饰器自动生成 JSON Schema，支持同步/异步 |
+| 🔄 **ReAct 模式** | Thought → Action → Observation 推理循环 |
+| 📋 **Plan-and-Execute** | 先规划后执行，支持动态重规划 |
+| 🪞 **自我反思** | ReflectionMixin 添加输出自评和迭代改进 |
+| 💾 **记忆系统** | 短期 (WorkingMemory) + 长期 (LongTermMemory/TF-IDF) |
+| 👥 **多 Agent 编排** | 顺序/监督者/辩论 三种协作模式 |
+
+## 快速开始
+
+```bash
+# 安装
+uv pip install -e "."
+
+# 安装 LLM 提供商 SDK（按需）
+uv pip install -e ".[openai]"      # OpenAI
+uv pip install -e ".[all-llm]"     # 所有 LLM
+
+# 设置 API Key
+export AGENT2_OPENAI_API_KEY=sk-...
+```
+
+### 最简示例
+
+```python
+import asyncio
+from agent2.llm import create_llm
+from agent2.agent import ReActAgent
+from agent2.tools.builtin import python_exec
+
+async def main():
+    llm = create_llm("openai", model="gpt-4o-mini")
+    agent = ReActAgent("assistant", llm=llm, tools=[python_exec])
+    result = await agent.run("What is 2^100?")
+    print(result)
+
+asyncio.run(main())
+```
+
+## 示例
+
+```bash
+uv run examples/01_single_agent.py   # 单 Agent ReAct
+uv run examples/02_tool_use.py       # 自定义工具
+uv run examples/03_planning.py       # Plan-and-Execute
+uv run examples/04_memory.py         # 记忆系统（无需 API Key）
+uv run examples/05_multi_agent.py    # 多 Agent 协作
+```
+
+## 架构
+
+```
+agent2/
+├── llm/        # LLM 抽象层 — 统一多提供商接口
+├── tools/      # 工具系统 — @tool 装饰器 + Registry
+├── agent/      # Agent 核心 — ReAct / Planner / Reflection
+├── memory/     # 记忆系统 — Working / LongTerm
+├── crew/       # 多 Agent — Sequential / Supervisor / Debate
+└── utils/      # 配置 + 日志
+```
+
+## License
+
+MIT

agent2-0.1.0/examples/01_single_agent.py

@@ -0,0 +1,49 @@
+"""Example 01: Single Agent — Basic ReAct pattern.
+
+Demonstrates:
+- Creating an LLM instance
+- Creating a ReAct agent with tools
+- Running a task and observing the Thought/Action/Observation loop
+
+Usage:
+    export AGENT2_OPENAI_API_KEY=sk-...
+    uv run examples/01_single_agent.py
+"""
+
+import os
+import asyncio
+
+from agent2.llm import create_llm
+from agent2.agent import ReActAgent
+from agent2.tools.builtin import python_exec
+
+
+async def main():
+    # 1. Create an LLM — switch provider by changing the first argument
+    #llm = create_llm("openai", model="gpt-4o-mini")
+    #llm = create_llm("ollama", model="gemma4:e2b")
+    llm = create_llm("deepseek")
+
+    # 2. Create a ReAct agent with a code execution tool
+    agent = ReActAgent(
+        "CodeAssistant",
+        llm=llm,
+        system_prompt=(
+            "You are a helpful coding assistant. You can execute Python code "
+            "to verify your answers. Always show your reasoning."
+        ),
+        tools=[python_exec],
+    )
+
+    # 3. Run a task
+    result = await agent.run(
+        "What is the sum of the first 100 prime numbers? Use Python to calculate it."
+    )
+
+    print("\n" + "=" * 60)
+    print("FINAL RESULT:")
+    print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent2-0.1.0/examples/02_tool_use.py

@@ -0,0 +1,88 @@
+"""Example 02: Tool Use — defining and using custom tools.
+
+Demonstrates:
+- @tool decorator for creating tools from functions
+- ToolRegistry for managing multiple tools
+- Agent using tools to solve problems
+
+Usage:
+    export AGENT2_OPENAI_API_KEY=sk-...
+    uv run examples/02_tool_use.py
+"""
+
+import asyncio
+import math
+
+from agent2.llm import create_llm
+from agent2.agent import ReActAgent
+from agent2.tools import tool, ToolRegistry
+
+
+# ── Define custom tools ─────────────────────────────────────────────
+
+
+@tool(description="Calculate basic math expressions. Supports +, -, *, /, **, sqrt.")
+def calculator(expression: str) -> str:
+    """Evaluate a math expression safely."""
+    allowed = {
+        "sqrt": math.sqrt,
+        "sin": math.sin,
+        "cos": math.cos,
+        "tan": math.tan,
+        "pi": math.pi,
+        "e": math.e,
+        "abs": abs,
+        "round": round,
+    }
+    try:
+        result = eval(expression, {"__builtins__": {}}, allowed)
+        return f"{expression} = {result}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+@tool(description="Get the current date and time.")
+def get_current_time() -> str:
+    """Return the current date and time."""
+    from datetime import datetime
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+@tool(description="Convert temperature between Celsius and Fahrenheit.")
+def convert_temperature(value: float, from_unit: str) -> str:
+    """Convert temperature. from_unit should be 'C' or 'F'."""
+    if from_unit.upper() == "C":
+        result = value * 9 / 5 + 32
+        return f"{value}°C = {result:.1f}°F"
+    elif from_unit.upper() == "F":
+        result = (value - 32) * 5 / 9
+        return f"{value}°F = {result:.1f}°C"
+    else:
+        return f"Unknown unit: {from_unit}. Use 'C' or 'F'."
+
+
+# ── Main ────────────────────────────────────────────────────────────
+
+
+async def main():
+    llm = create_llm("deepseek")
+
+    # Create agent with multiple custom tools
+    agent = ReActAgent(
+        "ToolDemo",
+        llm=llm,
+        tools=[calculator, get_current_time, convert_temperature],
+    )
+
+    # Test with a task requiring multiple tools
+    result = await agent.run(
+        "What is the current time? Also, what is 37°C in Fahrenheit? "
+        "And what is the square root of 144?"
+    )
+
+    print("\n" + "=" * 60)
+    print("RESULT:", result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent2-0.1.0/examples/03_planning.py

@@ -0,0 +1,42 @@
+"""Example 03: Planning — Plan-and-Execute pattern.
+
+Demonstrates:
+- PlannerAgent that separates planning from execution
+- Dynamic re-planning based on intermediate results
+- Multi-step task decomposition
+
+Usage:
+    export AGENT2_OPENAI_API_KEY=sk-...
+    uv run examples/03_planning.py
+"""
+
+import asyncio
+
+from agent2.llm import create_llm
+from agent2.agent import PlannerAgent
+from agent2.tools.builtin import web_search, python_exec
+
+
+async def main():
+    llm = create_llm("deepseek")
+
+    agent = PlannerAgent(
+        "Researcher",
+        llm=llm,
+        tools=[web_search, python_exec],
+        enable_replan=True,
+        max_step_iterations=3,
+    )
+
+    result = await agent.run(
+        "Compare the population of Tokyo, New York, and London. "
+        "Which city is the most densely populated? "
+        "Show the calculations."
+    )
+
+    print("\n" + "=" * 60)
+    print("RESULT:", result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent2-0.1.0/examples/04_memory.py

@@ -0,0 +1,101 @@
+"""Example 04: Memory — working memory and long-term memory.
+
+Demonstrates:
+- WorkingMemory for conversation history management
+- LongTermMemory for semantic search (TF-IDF based)
+- Integrating memory with agents
+
+Usage:
+    uv run examples/04_memory.py
+"""
+
+import asyncio
+
+from agent2.memory import WorkingMemory, LongTermMemory
+from agent2.llm.message import Message
+
+
+async def demo_working_memory():
+    """Demonstrate working memory (conversation history)."""
+    print("=" * 60)
+    print("Working Memory Demo")
+    print("=" * 60)
+
+    memory = WorkingMemory(max_messages=10)
+
+    # Simulate a conversation
+    await memory.add("What is machine learning?", role="user")
+    await memory.add(
+        "Machine learning is a subset of AI that enables systems to learn from data.",
+        role="assistant",
+    )
+    await memory.add("What are the main types?", role="user")
+    await memory.add(
+        "The main types are: supervised learning, unsupervised learning, "
+        "and reinforcement learning.",
+        role="assistant",
+    )
+
+    # Search memory
+    results = await memory.search("types of learning")
+    print(f"\nSearch for 'types of learning': {len(results)} results")
+    for r in results:
+        print(f"  [{r.score:.2f}] {r.content[:80]}...")
+
+    # Get messages ready for LLM
+    messages = memory.get_messages_for_llm("You are a helpful AI.")
+    print(f"\nMessages for LLM: {len(messages)} messages")
+    for m in messages:
+        print(f"  [{m.role.value}] {(m.content or '')[:60]}...")
+
+
+async def demo_long_term_memory():
+    """Demonstrate long-term memory (semantic search)."""
+    print("\n" + "=" * 60)
+    print("Long-Term Memory Demo")
+    print("=" * 60)
+
+    memory = LongTermMemory(embedding_provider="tfidf")
+
+    # Store some knowledge
+    facts = [
+        "Python is a high-level programming language created by Guido van Rossum.",
+        "Rust is a systems programming language focused on safety and performance.",
+        "JavaScript is primarily used for web development in browsers.",
+        "Machine learning uses algorithms to learn patterns from data.",
+        "Docker is a platform for containerizing applications.",
+        "Kubernetes orchestrates container deployment at scale.",
+        "PostgreSQL is a powerful open-source relational database.",
+        "Redis is an in-memory data store used for caching.",
+    ]
+
+    print("\nStoring facts...")
+    for fact in facts:
+        await memory.add(fact)
+    print(f"Stored {memory.size} items")
+
+    # Search for related information
+    queries = [
+        "programming language for web",
+        "database systems",
+        "container orchestration",
+    ]
+
+    for query in queries:
+        print(f"\n🔍 Search: '{query}'")
+        results = await memory.search(query, top_k=3)
+        for r in results:
+            print(f"  [{r.score:.3f}] {r.content}")
+
+    # Get formatted context for prompt injection
+    context = await memory.get_context("What language should I use for AI?")
+    print(f"\n📋 Context for RAG:\n{context}")
+
+
+async def main():
+    await demo_working_memory()
+    await demo_long_term_memory()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent2-0.1.0/examples/05_multi_agent.py

@@ -0,0 +1,127 @@
+"""Example 05: Multi-Agent — crew orchestration patterns.
+
+Demonstrates:
+- SequentialCrew: pipeline-style execution
+- SupervisorCrew: supervisor delegates to workers
+- DebateCrew: agents debate and reach consensus
+
+Usage:
+    export AGENT2_OPENAI_API_KEY=sk-...
+    uv run examples/05_multi_agent.py
+"""
+
+import asyncio
+
+from agent2.llm import create_llm
+from agent2.agent import ReActAgent
+from agent2.crew import SequentialCrew, SupervisorCrew, DebateCrew
+
+
+async def demo_sequential():
+    """Sequential pipeline: Research → Write → Edit."""
+    print("\n" + "=" * 60)
+    print("Sequential Crew Demo")
+    print("=" * 60)
+
+    llm = create_llm("deepseek")
+
+    researcher = ReActAgent(
+        "researcher",
+        llm=llm,
+        system_prompt="You are a research expert. Gather key facts and data points.",
+    )
+    writer = ReActAgent(
+        "writer",
+        llm=llm,
+        system_prompt="You are a professional writer. Create clear, engaging content from research.",
+    )
+    editor = ReActAgent(
+        "editor",
+        llm=llm,
+        system_prompt="You are an editor. Polish the writing for clarity and accuracy.",
+    )
+    translator = ReActAgent(
+        "translator",
+        llm=llm,
+        system_prompt="You are an translator. Translate the writing into Chinese.",
+    )
+
+    crew = SequentialCrew("content_pipeline", agents=[researcher, writer, editor, translator])
+    result = await crew.run("Write a brief explanation of how neural networks work")
+    print(f"\nFinal output:\n{result}")
+
+
+async def demo_supervisor():
+    """Supervisor delegates to specialized workers."""
+    print("\n" + "=" * 60)
+    print("Supervisor Crew Demo")
+    print("=" * 60)
+
+    llm = create_llm("openai", model="gpt-4o-mini")
+
+    analyst = ReActAgent(
+        "analyst",
+        llm=llm,
+        system_prompt="You are a data analyst. Focus on numbers, trends, and insights.",
+    )
+    strategist = ReActAgent(
+        "strategist",
+        llm=llm,
+        system_prompt="You are a strategy consultant. Focus on actionable recommendations.",
+    )
+
+    crew = SupervisorCrew(
+        "consulting_team",
+        agents=[analyst, strategist],
+        supervisor_llm=llm,
+    )
+    result = await crew.run("What should a startup focus on in its first year?")
+    print(f"\nFinal output:\n{result}")
+
+
+async def demo_debate():
+    """Agents with different perspectives debate."""
+    print("\n" + "=" * 60)
+    print("Debate Crew Demo")
+    print("=" * 60)
+
+    llm = create_llm("openai", model="gpt-4o-mini")
+
+    optimist = ReActAgent(
+        "optimist",
+        llm=llm,
+        system_prompt=(
+            "You are an optimistic technology enthusiast. "
+            "You focus on opportunities, benefits, and positive outcomes."
+        ),
+    )
+    critic = ReActAgent(
+        "critic",
+        llm=llm,
+        system_prompt=(
+            "You are a critical thinker and devil's advocate. "
+            "You focus on risks, limitations, and potential problems."
+        ),
+    )
+
+    crew = DebateCrew(
+        "tech_debate",
+        agents=[optimist, critic],
+        synthesizer_llm=llm,
+        rounds=1,
+    )
+    result = await crew.run("Should companies fully adopt AI for customer service?")
+    print(f"\nFinal output:\n{result}")
+
+
+async def main():
+    # Run one demo at a time to keep output readable
+    # Uncomment the one you want to try:
+
+    await demo_sequential()
+    # await demo_supervisor()
+    # await demo_debate()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent2-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "agent2"
+version = "0.1.0"
+description = "A modular agent system framework for learning and research"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "httpx>=0.27",
+    "rich>=13.0",
+    "openai>=2.44.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.30"]
+anthropic = ["anthropic>=0.30"]
+google = ["google-genai>=1.0"]
+all-llm = ["openai>=1.30", "anthropic>=0.30", "google-genai>=1.0"]
+memory = ["numpy>=1.26"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "mypy>=1.10"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[[tool.uv.index]]
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+default = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent2"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.14"
+strict = true

agent2-0.1.0/src/agent2/__init__.py

@@ -0,0 +1,6 @@
+"""Agent2 - A modular agent system framework for learning and research."""
+
+from agent2.utils.config import Settings
+
+__version__ = "0.1.0"
+__all__ = ["Settings"]

agent2-0.1.0/src/agent2/agent/__init__.py

@@ -0,0 +1,21 @@
+"""Agent module — reasoning cores for LLM-powered agents.
+
+Available agent types:
+
+- :class:`ReActAgent` — Thought → Action → Observation loop
+- :class:`PlannerAgent` — Plan-and-Execute pattern
+- :class:`ReflectionMixin` — Self-critique mixin for any agent
+"""
+
+from agent2.agent.base import BaseAgent, MaxIterationsExceeded
+from agent2.agent.react import ReActAgent
+from agent2.agent.planner import PlannerAgent
+from agent2.agent.reflection import ReflectionMixin
+
+__all__ = [
+    "BaseAgent",
+    "MaxIterationsExceeded",
+    "ReActAgent",
+    "PlannerAgent",
+    "ReflectionMixin",
+]