iris-next 0.0.3

iris-next

IrisAgent

最小化的智能体框架，基于 openai-agents-python 和 loom-agent 的核心设计理念。

核心特性

✅ 已实现

1. Pydantic 增强的工具系统

   • 支持复杂嵌套参数（List[str], BaseModel）
   • 自动类型校验和反序列化
   • 自动生成 JSON Schema
   • 工具安全属性（read_only, destructive）
   • 工具速率限制（rate_limit）

2. 多智能体交接 (Handoff)

   • 原生支持 Agent 之间的动态切换
   • 保留上下文无缝交接
   • 类似 OpenAI Agents SDK 的 Handoff 机制

3. 沙盒隔离 (Sandbox)

   • 抽象 Sandbox 接口
   • LocalSandbox 实现
   • 为危险工具提供隔离执行环境

4. 分层流式输出

   • 原始事件流（RawLLMEvent）
   • LLM Token 流
   • 工具调用入参流
   • 工具执行状态流
   • 工具结果流
   • Handoff 事件流

5. 工具治理

   • 权限检查
   • 自动重试
   • 超时控制
   • 速率限制（防止滥用）

6. 智能上下文压缩

   • 基于阈值的自动压缩
   • 保留重要消息

7. Skill 动态加载

   • 从文件/目录加载
   • 自动注册工具

8. Usage 统计

   • Token 消耗跟踪
   • 按 Agent 分组统计
   • 成本估算支持

9. Hook 系统

   • before_run / after_run
   • before_tool_call / after_tool_call
   • on_error / on_handoff

10. 完善的异常体系

    • 语义化异常类型
    • 区分可恢复/不可恢复错误

架构设计

src/iris_agent/
├── agent.py           # Agent 配置
├── run.py             # Runner 执行引擎
├── tool.py            # 工具系统（Pydantic + 安全属性）
├── tool_executor.py   # 工具执行器（权限 + 速率限制）
├── handoff.py         # Handoff 机制
├── exceptions.py      # 异常体系
├── usage.py           # Token 使用统计
├── hooks.py           # 生命周期钩子
├── context/           # 上下文管理
├── sandbox/           # 沙盒抽象
├── streaming/         # 分层流式事件
├── skill/             # 技能加载
└── types/             # 类型定义

快速开始

安装

pip install -r requirements.txt

环境变量配置

export OPENAI_API_KEY=your-api-key
export OPENAI_BASE_URL=http://localhost:11434/v1

基础使用

from iris_agent import Agent, Runner, tool, ToolRegistry

@tool(name="calculator", description="Calculate")
def calculator(expression: str) -> str:
    return str(eval(expression))

registry = ToolRegistry()
registry.register(calculator._tool_config)

agent = Agent(
    name="math_agent",
    instructions="You are a math assistant.",
    tool_registry=registry
)

runner = Runner(agent)

async for event in runner.run("What is 123 * 456?"):
    if event.type.value == "llm_token":
        print(event.token, end="")

Pydantic 复杂参数

from pydantic import BaseModel
from iris_agent import tool

class SearchParams(BaseModel):
    query: str
    filters: list[str]
    limit: int = 10

@tool(name="search", description="Search with filters")
def search(params: SearchParams) -> str:
    return f"Searching: {params.query}, filters: {params.filters}"

多智能体 Handoff

from iris_agent import Agent, Handoff, Runner

specialist = Agent(name="specialist", instructions="...")
generalist = Agent(
    name="generalist",
    instructions="...",
    handoffs=[
        Handoff(
            target_agent=specialist,
            description="Transfer to specialist for complex queries"
        )
    ]
)

runner = Runner(generalist)
# Agent 会自动切换

新特性使用示例

工具安全属性

from iris_agent import tool

@tool(
    name="delete_file",
    description="Delete a file",
    destructive=True,          # 标记为破坏性操作
    requires_permission=True
)
def delete_file(path: str) -> str:
    return f"Deleted {path}"

@tool(
    name="read_file",
    description="Read a file",
    read_only=True,            # 只读工具
    requires_permission=False
)
def read_file(path: str) -> str:
    return f"Content of {path}"

@tool(
    name="api_call",
    description="Call external API",
    rate_limit=10              # 限制每分钟10次调用
)
def api_call(endpoint: str) -> str:
    return f"Called {endpoint}"

Usage 统计

from iris_agent import Agent, Runner, UsageTracker

tracker = UsageTracker()
agent = Agent(name="assistant", instructions="...")
runner = Runner(agent)

# 运行后获取统计
async for event in runner.run("Hello"):
    pass

# 记录使用（需在 Runner 中集成）
# tracker.record("assistant", Usage(prompt_tokens=100, completion_tokens=50))
print(tracker.get_summary())

Hook 系统

from iris_agent import Agent, Runner, Hooks

async def log_before_tool(tool_name: str, args: dict):
    print(f"Calling tool: {tool_name} with {args}")

async def log_after_tool(tool_name: str, result):
    print(f"Tool {tool_name} returned: {result}")

hooks = Hooks()
hooks.before_tool_call.append(log_before_tool)
hooks.after_tool_call.append(log_after_tool)

# 在 Runner 中使用（需集成到 Runner）

依赖

• openai >= 1.0.0
• pydantic >= 2.0.0