git clone https://github.com/antoinezambelli/forge.git
cd forge
pip install -e .

# 安装 Ollama（如果没有）
curl -fsSL https://ollama.com/install.sh | sh

# 下载 Qwen-2.5-7B（约 4.5GB）
ollama pull qwen2.5:7b

# 启动服务（默认端口 11434）
ollama serve

model:
  provider: "ollama"
  model: "qwen2.5:7b"
  base_url: "http://localhost:11434"

guardrails:
  tool_selection:
    enabled: true
    strict_mode: true  # 严格模式：工具选择错误直接拒绝
  parameter_validation:
    enabled: true
    required_fields: ["query", "target", "action"]
  output_format:
    enabled: true
    schema: "json"  # 强制 JSON 输出
  retry_policy:
    max_retries: 3
    backoff: "exponential"

from forge import Agent, Guardrail

# 定义 Agent 的工具集
tools = [
    {
        "name": "search_news",
        "description": "搜索最新 AI 新闻",
        "parameters": {
            "query": "搜索关键词",
            "source": "新闻来源（hackernews/arxiv/techcrunch）",
            "max_results": "返回结果数量（1-20）"
        }
    },
    {
        "name": "summarize",
        "description": "总结文章内容",
        "parameters": {
            "text": "需要总结的文本",
            "max_length": "摘要最大长度（字数）"
        }
    },
    {
        "name": "publish_draft",
        "description": "发布草稿到平台",
        "parameters": {
            "title": "文章标题",
            "content": "文章内容",
            "platform": "目标平台（wechat/twitter/blog）"
        }
    }
]

# 创建带 guardrails 的 Agent
agent = Agent(
    model="qwen2.5:7b",
    tools=tools,
    guardrails=[
        Guardrail.tool_selection(valid_tools=[t["name"] for t in tools]),
        Guardrail.parameter_required(["query"]),
        Guardrail.output_json(),
        Guardrail.retry(max_attempts=3)
    ]
)

# 执行任务——Forge 会自动验证每一步
result = agent.execute(
    "搜索今天关于 AI Agent 的最新 5 条新闻，总结后发布到微信公众号草稿箱"
)

print(f"✅ 任务完成，执行了 {result.steps} 个步骤")
print(f"🛡️ Guardrail 拦截了 {result.interventions} 次错误操作")
print(f"📊 最终输出: {result.output}")

# 这个指令缺少必要的参数
result = agent.execute("发一篇文章")
# Forge 会拦截并返回：
# ❌ Guardrail: 缺少必要参数 'title' 和 'content'
# 🔄 正在请求 Agent 补充信息...

Guardrail.pre_check(
    # 检查工具是否存在
    tool_exists=True,
    # 检查必填参数
    required_params=["query"],
    # 检查参数类型
    param_types={"max_results": int}
)

Guardrail.post_check(
    # 验证返回格式
    expect_json=True,
    # 验证必含字段
    required_fields=["title", "url", "summary"],
    # 验证数据完整性
    min_results=1
)

Guardrail.state_machine(
    states=["search", "filter", "summarize", "publish"],
    transitions={
        "search": ["filter"],
        "filter": ["summarize"],
        "summarize": ["publish"],
        "publish": []
    },
    # 不允许跳过步骤
    allow_skip=False
)

# ai-neican-forge-config.yaml
model:
  provider: "ollama"
  model: "qwen2.5:7b"

guardrails:
  # Guard 1: 工具选择——Agent 必须用正确的工具
  tool_selection:
    valid_tools:
      - "search_news"      # 搜索热点
      - "extract_content"  # 提取文章内容
      - "write_draft"      # 写草稿
      - "generate_cover"   # 生成封面图
      - "publish_draft"    # 发布草稿
    strict_mode: true

  # Guard 2: 参数校验——每个工具的参数必须完整
  parameter_validation:
    search_news:
      required: ["query", "max_results"]
      types:
        max_results: "int"
        query: "str"
      constraints:
        max_results: { min: 1, max: 20 }
    write_draft:
      required: ["title", "content", "word_count"]
      constraints:
        word_count: { min: 800, max: 5000 }

  # Guard 3: 流程状态机——必须按顺序执行
  workflow:
    states: ["scan", "select", "write", "review", "publish"]
    transitions:
      scan: ["select"]
      select: ["write"]
      write: ["review"]
      review: ["write", "publish"]  # review 不通过回退到 write
      publish: []
    max_loops: 3  # 防止 write→review→write 死循环

  # Guard 4: 输出质量——内容必须达标
  content_quality:
    min_word_count: 800
    required_sections: ["标题", "核心观点", "正文", "行动建议"]
    forbidden_patterns:
      - "今天看到一篇文章"  # 禁止空洞开头
      - "据说"               # 禁止无来源引用
      - "可能会"             # 禁止模糊表述

  retry_policy:
    max_retries: 3
    backoff: "exponential"