ni.agentkit 0.3.1__py3-none-any.whl

agentkit/examples/standard/02_tool_calling.py

@@ -0,0 +1,70 @@
+"""
+示例 2：带工具的 Agent — Function Calling
+
+演示 @function_tool 装饰器：一行代码把 Python 函数变成 LLM 可调用的工具。
+
+运行前请设置环境变量：
+  export OPENAI_API_KEY="sk-..."
+
+运行：
+  python examples/standard/02_tool_calling.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner, function_tool
+
+
+# ===== 定义工具 =====
+
+@function_tool
+def add(a: int, b: int) -> str:
+    """两个数字相加"""
+    return str(a + b)
+
+@function_tool
+def multiply(a: int, b: int) -> str:
+    """两个数字相乘"""
+    return str(a * b)
+
+@function_tool
+def get_weather(city: str) -> str:
+    """获取指定城市的天气信息"""
+    weather_data = {
+        "北京": "晴，25°C",
+        "上海": "多云，22°C",
+        "深圳": "阵雨，28°C",
+    }
+    return weather_data.get(city, f"{city}：暂无数据")
+
+
+# ===== 创建 Agent =====
+
+agent = Agent(
+    name="smart-assistant",
+    instructions="你是一个全能助手。可以做数学计算和查天气。根据用户需求选择合适的工具。回答简洁。",
+    model="gpt-4o",
+    tools=[add, multiply, get_weather],
+)
+
+
+# ===== 运行测试 =====
+
+queries = [
+    "请计算 15 + 27 的结果",
+    "3 乘以 7 等于多少？",
+    "北京今天天气如何？",
+]
+
+for q in queries:
+    print(f"\n用户: {q}")
+    result = Runner.run_sync(agent, input=q)
+    if result.success:
+        print(f"助手: {result.final_output}")
+    else:
+        print(f"❌ 错误: {result.error}")
+
+    # 展示工具调用
+    for event in result.events:
+        if event.type == "tool_result":
+            print(f"  🔧 工具调用: {event.data}")

agentkit/examples/standard/03_skill_usage.py

@@ -0,0 +1,89 @@
+"""
+示例 3：带 Skill 的 Agent — 领域知识包
+
+演示 Skill 的核心用法：
+- 代码中定义 Skill（Frontmatter + Instructions）
+- Skill 三级渐进式加载（L1 → L2 → L3）
+- Skill 与 Tool 的协作
+
+运行前请设置环境变量：
+  export OPENAI_API_KEY="sk-..."
+
+运行：
+  python examples/standard/03_skill_usage.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner, Skill, SkillFrontmatter, SkillResources, function_tool
+
+
+# ===== 定义工具 =====
+
+@function_tool
+def get_weather(city: str) -> str:
+    """获取指定城市的天气信息"""
+    weather_data = {
+        "北京": "晴，25°C",
+        "上海": "多云，22°C",
+        "深圳": "阵雨，28°C",
+        "广州": "晴，30°C",
+        "成都": "阴，18°C",
+    }
+    return weather_data.get(city, f"{city}：暂无数据")
+
+
+# ===== 定义 Skill =====
+
+weather_skill = Skill(
+    frontmatter=SkillFrontmatter(
+        name="weather-analysis",
+        description="天气分析技能，查询天气并给出穿衣建议",
+    ),
+    instructions="""## 天气分析步骤
+
+1. 使用 get_weather 工具查询用户指定城市的天气
+2. 根据天气情况给出穿衣建议：
+   - 温度 > 30°C：建议穿短袖、注意防晒
+   - 温度 20-30°C：建议穿薄外套
+   - 温度 < 20°C：建议穿厚外套
+3. 如果有雨，额外提醒带伞
+4. 用简洁的中文回复用户""",
+)
+
+
+# ===== 创建带 Skill 的 Agent =====
+
+agent = Agent(
+    name="skill-agent",
+    instructions="你是一个智能助手，可以使用专业技能来完成任务。",
+    model="gpt-4o",
+    skills=[weather_skill],       # ⭐ Skill 作为一等公民
+    tools=[get_weather],
+)
+
+
+# ===== 运行测试 =====
+
+queries = [
+    "深圳今天适合穿什么衣服？",
+    "成都现在冷不冷？需要穿什么？",
+    "广州今天出门要注意什么？",
+]
+
+for q in queries:
+    print(f"\n用户: {q}")
+    result = Runner.run_sync(agent, input=q)
+    if result.success:
+        print(f"助手: {result.final_output}")
+    else:
+        print(f"❌ 错误: {result.error}")
+
+    # 展示 Skill 和工具调用
+    for event in result.events:
+        if event.type == "tool_result":
+            tool_name = event.data.get("tool", "")
+            if tool_name == "load_skill":
+                print(f"  📚 加载了 Skill: {event.data.get('result', {}).get('skill_name', '')}")
+            else:
+                print(f"  🔧 工具调用: {event.data}")

agentkit/examples/standard/04_multi_agent.py

@@ -0,0 +1,87 @@
+"""
+示例 4：多 Agent 协作 — Handoff 与 as_tool
+
+演示两种 Agent 协作模式：
+- as_tool（委派）：Agent A 把 Agent B 当工具调用，完成后控制权返回 A
+- Handoff（转介）：Agent A 把整个对话交给 Agent B，控制权完全转移
+
+运行前请设置环境变量：
+  export OPENAI_API_KEY="sk-..."
+
+运行：
+  python examples/standard/04_multi_agent.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner
+
+
+# ============================================================
+# 模式 A：as_tool（委派）
+# ============================================================
+
+print("=" * 50)
+print("  模式 A：as_tool（委派）")
+print("=" * 50)
+
+# 专家 Agent
+researcher = Agent(
+    name="researcher",
+    instructions="你是一个研究助手。收到问题后，给出简短的研究结论（不超过 3 句话）。",
+    model="gpt-4o",
+)
+
+# 主管 Agent，把研究员当工具用
+manager = Agent(
+    name="manager",
+    instructions="你是项目经理。需要研究信息时调用 research 工具。综合研究结果给出你的建议。",
+    model="gpt-4o",
+    tools=[
+        researcher.as_tool("research", "调用研究助手获取研究信息"),
+    ],
+)
+
+result = Runner.run_sync(manager, input="帮我调研 Python 异步编程的最佳实践")
+if result.success:
+    print(f"\n✅ 回复: {result.final_output}")
+else:
+    print(f"\n❌ 错误: {result.error}")
+
+for event in result.events:
+    if event.type == "tool_result":
+        print(f"  🔧 研究员返回: {str(event.data)[:100]}")
+
+
+# ============================================================
+# 模式 B：Handoff（转介）
+# ============================================================
+
+print(f"\n{'=' * 50}")
+print("  模式 B：Handoff（转介）")
+print("=" * 50)
+
+billing_agent = Agent(
+    name="billing",
+    instructions="你是账单专家。处理所有账单相关的问题，给出专业的解答。",
+    model="gpt-4o",
+)
+
+tech_agent = Agent(
+    name="tech",
+    instructions="你是技术支持专家。处理所有技术相关的问题。",
+    model="gpt-4o",
+)
+
+triage_agent = Agent(
+    name="triage",
+    instructions="你是客服分诊员。根据用户问题类型，转交给合适的专家：账单问题转给 billing，技术问题转给 tech。",
+    model="gpt-4o",
+    handoffs=[billing_agent, tech_agent],
+)
+
+result = Runner.run_sync(triage_agent, input="我的账单金额好像不对，比上个月多了很多")
+if result.success:
+    print(f"\n✅ 最终由 [{result.last_agent}] 处理: {result.final_output}")
+else:
+    print(f"\n❌ 错误: {result.error}")

agentkit/examples/standard/05_guardrail.py

@@ -0,0 +1,104 @@
+"""
+示例 5：安全护栏 — Guardrail 与权限控制
+
+演示三层安全机制：
+- 输入护栏（InputGuardrail）：拦截不安全的用户输入
+- 输出护栏（OutputGuardrail）：检查 Agent 的输出内容
+- 权限控制（PermissionPolicy）：限制可调用的工具
+
+运行前请设置环境变量：
+  export OPENAI_API_KEY="sk-..."
+
+运行：
+  python examples/standard/05_guardrail.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import (
+    Agent, Runner, function_tool,
+    input_guardrail, output_guardrail, GuardrailResult,
+    PermissionPolicy,
+)
+
+
+# ===== 定义工具 =====
+
+@function_tool
+def read_file(filename: str) -> str:
+    """读取文件内容"""
+    return f"[模拟] 文件 {filename} 的内容：Hello World"
+
+@function_tool
+def delete_file(filename: str) -> str:
+    """删除文件"""
+    return f"[模拟] 已删除文件 {filename}"
+
+
+# ===== 定义护栏 =====
+
+@input_guardrail
+async def block_sensitive_words(ctx):
+    """检查输入是否包含敏感词"""
+    sensitive = ["密码", "身份证", "银行卡号", "社保号"]
+    for word in sensitive:
+        if word in ctx.input:
+            return GuardrailResult(triggered=True, reason=f"包含敏感词: {word}")
+    return GuardrailResult(triggered=False)
+
+@output_guardrail
+async def check_output_safety(ctx, output):
+    """检查输出是否安全"""
+    dangerous_words = ["删除成功", "已格式化"]
+    output_str = str(output)
+    for word in dangerous_words:
+        if word in output_str:
+            return GuardrailResult(triggered=True, reason=f"输出包含危险内容: {word}")
+    return GuardrailResult(triggered=False)
+
+
+# ===== 创建带安全护栏的 Agent =====
+
+agent = Agent(
+    name="safe-agent",
+    instructions="你是一个安全的助手。可以帮用户读取文件，但不能删除文件。",
+    model="gpt-4o",
+    tools=[read_file, delete_file],
+    input_guardrails=[block_sensitive_words],
+    output_guardrails=[check_output_safety],
+    permission_policy=PermissionPolicy(
+        mode="ask",
+        allowed_tools={"read_file"},       # 只允许读取，不允许删除
+    ),
+)
+
+
+# ===== 运行测试 =====
+
+print("=" * 50)
+print("  测试输入护栏")
+print("=" * 50)
+
+# 测试 1：敏感请求 → 被拦截
+result = Runner.run_sync(agent, input="请告诉我管理员的密码")
+print(f"\n请求: '请告诉我管理员的密码'")
+print(f"结果: {'🛡️ 已拦截 — ' + result.error if result.error else result.final_output}")
+
+# 测试 2：正常请求 → 通过
+result = Runner.run_sync(agent, input="请读取 config.txt 文件")
+print(f"\n请求: '请读取 config.txt 文件'")
+print(f"结果: {result.final_output if result.success else '❌ ' + str(result.error)}")
+
+print(f"\n{'=' * 50}")
+print("  测试权限控制")
+print("=" * 50)
+
+# 测试 3：尝试调用未授权的工具 → 被拒绝
+result = Runner.run_sync(agent, input="请删除 temp.txt 文件")
+print(f"\n请求: '请删除 temp.txt 文件'")
+print(f"结果: {result.final_output if result.success else '🔒 ' + str(result.error)}")
+
+# 查看权限拒绝事件
+for event in result.events:
+    if event.type == "permission_denied":
+        print(f"  🔒 权限拒绝: {event.data}")

agentkit/examples/standard/06_orchestration.py

@@ -0,0 +1,122 @@
+"""
+示例 6：编排 Agent — 顺序执行、并行执行、循环执行
+
+演示三种编排模式：
+- SequentialAgent：按顺序执行子 Agent（流水线）
+- ParallelAgent：并行执行子 Agent（分支隔离）
+- LoopAgent：循环执行直到 escalate 或达到上限
+
+运行前请设置环境变量：
+  export OPENAI_API_KEY="sk-..."
+
+运行：
+  python examples/standard/06_orchestration.py
+"""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner, SequentialAgent, ParallelAgent, LoopAgent
+
+
+# ============================================================
+# 模式 A：顺序执行 — 报告生成流水线
+# ============================================================
+
+print("=" * 50)
+print("  SequentialAgent — 报告生成流水线")
+print("=" * 50)
+
+pipeline = SequentialAgent(
+    name="report-pipeline",
+    sub_agents=[
+        Agent(
+            name="extractor",
+            instructions="你是数据提取专家。从用户输入中提取所有关键数据点，以列表形式输出。",
+            model="gpt-4o",
+        ),
+        Agent(
+            name="analyzer",
+            instructions="你是数据分析专家。分析上文提取的数据点，找出趋势和规律，给出 2-3 条洞察。",
+            model="gpt-4o",
+        ),
+        Agent(
+            name="reporter",
+            instructions="你是报告撰写专家。将上文的分析结果写成一段简洁的中文报告（不超过 100 字）。",
+            model="gpt-4o",
+        ),
+    ],
+)
+
+result = Runner.run_sync(pipeline, input="今年Q1销售额1000万，Q2增长到1500万，Q3下降到1200万，Q4预计1800万")
+print(f"\n输入: 今年Q1销售额1000万...")
+for event in result.events:
+    if event.type == "final_output":
+        print(f"  [{event.agent}] {event.data}")
+
+
+# ============================================================
+# 模式 B：并行执行 — 多维度分析
+# ============================================================
+
+print(f"\n{'=' * 50}")
+print("  ParallelAgent — 多维度并行分析")
+print("=" * 50)
+
+parallel = ParallelAgent(
+    name="multi-analysis",
+    sub_agents=[
+        Agent(
+            name="financial",
+            instructions="你是财务分析师。用一句话分析给定数据的财务状况。",
+            model="gpt-4o",
+        ),
+        Agent(
+            name="market",
+            instructions="你是市场分析师。用一句话分析给定数据反映的市场趋势。",
+            model="gpt-4o",
+        ),
+        Agent(
+            name="risk",
+            instructions="你是风险分析师。用一句话分析给定数据中的潜在风险。",
+            model="gpt-4o",
+        ),
+    ],
+)
+
+result = Runner.run_sync(parallel, input="公司年收入 5 亿，同比增长 20%，但负债率从 30% 升至 45%")
+print(f"\n输入: 公司年收入 5 亿...")
+for event in result.events:
+    if event.type == "final_output":
+        print(f"  [{event.agent}] {event.data}")
+
+
+# ============================================================
+# 模式 C：循环执行 — 迭代优化
+# ============================================================
+
+print(f"\n{'=' * 50}")
+print("  LoopAgent — 迭代优化循环")
+print("=" * 50)
+
+loop = LoopAgent(
+    name="improvement-loop",
+    max_iterations=3,
+    sub_agents=[
+        Agent(
+            name="writer",
+            instructions="你是一个文案写手。根据用户需求或上轮反馈，写一句广告语。只输出广告语本身。",
+            model="gpt-4o",
+        ),
+        Agent(
+            name="critic",
+            instructions="你是一个文案评审。评估上面的广告语，如果已经很好则只输出'通过'，否则给出简短的改进建议。",
+            model="gpt-4o",
+        ),
+    ],
+)
+
+result = Runner.run_sync(loop, input="为一款AI编程助手写一句吸引开发者的广告语")
+print(f"\n输入: 为一款AI编程助手写广告语")
+for event in result.events:
+    if event.type == "final_output":
+        print(f"  [{event.agent}] {event.data}")

agentkit/examples/standard/07_sync_async_stream.py

@@ -0,0 +1,171 @@
+"""
+示例：三种运行方式对比 — 同步 / 异步 / 流式（标准版）
+
+演示 Runner 的三种运行方式在同一个 Agent 上的用法差异。
+
+运行前请设置环境变量：
+  export OPENAI_API_KEY="sk-..."
+
+运行：
+  python examples/standard/07_sync_async_stream.py
+"""
+import asyncio
+import sys
+import os
+import time
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+
+from agentkit import Agent, Runner, function_tool
+
+
+# ===== 定义一个简单工具 =====
+
+@function_tool
+def get_weather(city: str) -> str:
+    """获取指定城市的天气信息"""
+    return {"北京": "晴，25°C", "上海": "多云，22°C"}.get(city, f"{city}：暂无数据")
+
+
+# ===== 创建 Agent =====
+
+agent = Agent(
+    name="assistant",
+    instructions="你是一个简洁的中文助手。回答尽量简短。",
+    model="gpt-4o",
+    tools=[get_weather],
+)
+
+
+# ============================================================
+# 方式 1：同步运行 — Runner.run_sync()
+# ============================================================
+
+def demo_sync():
+    print("=" * 50)
+    print("  方式 1：同步运行 — Runner.run_sync()")
+    print("=" * 50)
+
+    start = time.time()
+    result = Runner.run_sync(agent, input="北京今天天气如何？")
+    elapsed = time.time() - start
+
+    if result.success:
+        print(f"  ✅ 回复: {result.final_output}")
+    else:
+        print(f"  ❌ 错误: {result.error}")
+    print(f"  ⏱️ 耗时: {elapsed:.1f}s")
+
+
+# ============================================================
+# 方式 2：异步运行 — await Runner.run()
+# ============================================================
+
+async def demo_async():
+    print(f"\n{'=' * 50}")
+    print("  方式 2：异步运行 — await Runner.run()")
+    print("=" * 50)
+
+    start = time.time()
+    result = await Runner.run(agent, input="上海今天天气如何？")
+    elapsed = time.time() - start
+
+    if result.success:
+        print(f"  ✅ 回复: {result.final_output}")
+    else:
+        print(f"  ❌ 错误: {result.error}")
+    print(f"  ⏱️ 耗时: {elapsed:.1f}s")
+
+
+# ============================================================
+# 方式 2b：异步并发 — 同时运行多个 Agent
+# ============================================================
+
+async def demo_async_concurrent():
+    print(f"\n{'=' * 50}")
+    print("  方式 2b：异步并发 — 同时运行多个请求")
+    print("=" * 50)
+
+    queries = [
+        "1+1等于几？只回答数字",
+        "北京今天天气如何？",
+        "用一句话解释什么是 Python",
+    ]
+
+    start = time.time()
+    results = await asyncio.gather(*[
+        Runner.run(agent, input=q) for q in queries
+    ])
+    elapsed = time.time() - start
+
+    for q, r in zip(queries, results):
+        status = f"✅ {r.final_output}" if r.success else f"❌ {r.error}"
+        print(f"  [{q[:15]:15s}] → {status}")
+
+    print(f"  ⏱️ 3 个请求并发总耗时: {elapsed:.1f}s")
+
+
+# ============================================================
+# 方式 3：流式运行 — Runner.run_streamed()
+# ============================================================
+
+async def demo_stream():
+    print(f"\n{'=' * 50}")
+    print("  方式 3：流式运行 — Runner.run_streamed()")
+    print("=" * 50)
+
+    print("  📡 实时事件流:")
+
+    start = time.time()
+    async for event in Runner.run_streamed(agent, input="北京今天天气如何？"):
+        elapsed = time.time() - start
+        if event.type == "llm_response":
+            has_tools = "有工具调用" if event.data.has_tool_calls else "纯文本"
+            print(f"  [{elapsed:5.1f}s] 🤖 LLM 响应 ({has_tools})")
+        elif event.type == "tool_result":
+            tool_name = event.data.get("tool", "?")
+            tool_result = event.data.get("result", "")
+            print(f"  [{elapsed:5.1f}s] 🔧 工具 {tool_name} → {tool_result}")
+        elif event.type == "final_output":
+            print(f"  [{elapsed:5.1f}s] ✅ 最终输出: {event.data}")
+        else:
+            print(f"  [{elapsed:5.1f}s] 📋 {event.type}: {str(event.data)[:60]}")
+
+
+# ============================================================
+# 主入口
+# ============================================================
+
+def run_all():
+    """先同步跑一个，再 asyncio.run 跑异步的"""
+
+    print("🚀 AgentKit — 三种运行方式对比\n")
+
+    # 方式 1：同步（必须在 asyncio.run 之外调用）
+    demo_sync()
+
+    # 方式 2、2b、3：异步
+    async def async_demos():
+        await demo_async()
+        await demo_async_concurrent()
+        await demo_stream()
+
+    asyncio.run(async_demos())
+
+    print(f"\n{'=' * 50}")
+    print("  全部演示完成 🎉")
+    print("=" * 50)
+    print("""
+📝 总结：
+  run_sync()      — 最简单，一行代码，适合脚本和测试
+  await run()     — 异步核心，可并发执行多个请求
+  run_streamed()  — 实时事件流，适合聊天 UI 和进度展示
+
+⚠️ 注意：run_sync() 内部调用 asyncio.run()，因此不能在
+   已有事件循环中使用。如果你的代码已经是 async 的，
+   请直接用 await Runner.run()。
+""")
+
+
+if __name__ == "__main__":
+    run_all()