Agent-Field/agentfield · 上手攻略

• 仓库：Agent-Field/agentfield
• 链接：https://github.com/Agent-Field/agentfield
• 分类：AI Agent 框架 / Agent 即服务
• 作者：Tom
• 更新：2026-08-28

---

是什么

AgentField 是一个开源的 AI 后端控制平面（Control Plane），核心理念是：把 AI Agent 构建得像 REST API 一样可调用，像微服务一样可横向扩展。

传统 Agent 框架（LangChain、AutoGPT 等）侧重于单个 Agent 的提示词工程与工具调用；AgentField 的着眼点完全不同——它是把每个 Agent 函数直接暴露为 HTTP 端点，然后在这个端点之上构建路由、队列、重试链路、分布式递归和可观测性。

用一句话总结：AgentField = Agent 的生产化基础设施，让任意服务（前端、后端、其他 Agent、Cron 任务）都能像调用 API 一样调用 AI Agent。

---

解决什么问题

当你需要把 AI 能力嵌入生产系统时，会遇到这些问题：

• Agent 如何被服务化？ 你的后端服务、前端、CRON 如何触发一个 Agent 的执行？
• 单个 Agent 递归如何扩展到分布式？ 一个请求需要扇出（fan-out）到上千个子 Agent，当前进程内递归无法扩展。
• 生产级可靠性谁来负责？ 队列、重试、超时、追踪，这些基础设施 Agent 框架本身不解决。
• 多 Agent 如何协作？ Agent 间如何互相调用、如何传递上下文、如何管理依赖？

AgentField 的答案：你写一个 Python/Go/TypeScript 函数，它就自动变成一个带队列、重试和追踪的 REST 端点；递归调用通过控制平面变成跨进程的分布式调用。

---

快速安装

方式一：安装脚本（推荐，包含 af CLI）

curl -fsSL https://agentfield.ai/install.sh | bash
# 或
curl -sSf https://agentfield.ai/get | sh

验证安装：

af --version

方式二：仅 SDK（无 CLI）

pip install agentfield
# Python 3.10–3.13

初始化项目

af init my-agent --defaults
cd my-agent
python -m pip install agentfield

af init 会生成一个基础项目结构，包含 docker-compose.yml、.env 配置和示例 main.py。

⚠️ 版本注意：Python SDK 要求 Python 3.10–3.13，低于 3.10 会报兼容错误。控制平面（af server）需要 Docker 环境。

---

核心用法

最小可跑示例

第一步：启动控制平面（Terminal 1）

af server
# Dashboard 访问：http://localhost:8080

第二步：写 Agent 代码（main.py）

from agentfield import Agent, AIConfig
from pydantic import BaseModel

app = Agent(
    node_id="my-agent",                              # Agent 唯一 ID
    version="1.0.0",                                 # 版本号，支持灰度/A/B
    ai_config=AIConfig(model="anthropic/claude-sonnet-4-20250514"),
)

class SubQuestions(BaseModel):
    questions: list[str]

@app.reasoner(tags=["research"])
async def research(question: str, depth: int = 0) -> dict:
    # depth >= 3 时不再递归，直接回答
    if depth >= 3:
        answer = await app.ai(
            system="Answer directly and concisely.",
            user=question,
        )
        return {"question": question, "answer": answer}

    # 将问题分解为子问题
    plan = await app.ai(
        system="Break this into 3-5 independent sub-questions.",
        user=question,
        schema=SubQuestions,
    )

    # 通过控制平面递归调用自己，实现分布式扇出
    branches = await asyncio.gather(*[
        app.call(f"{app.node_id}.research", question=q, depth=depth + 1)
        for q in plan.questions
    ])

    # 汇总子结果
    synthesis = await app.ai(
        system="Synthesize these findings.",
        user=str(branches),
    )
    return {"question": question, "answer": synthesis, "branches": branches}

app.run()  # 这一行自动将所有 @app.reasoner 函数暴露为 REST 端点

第三步：运行 Agent（Terminal 2）

python main.py
# Agent 自动注册到控制平面

第四步：调用端点

curl -X POST http://localhost:8080/api/v1/execute/my-agent.research \
  -H "Content-Type: application/json" \
  -d '{"input": {"question": "解释量子计算的原理"}}'

结构化输出的同步调用示例：

curl -X POST http://localhost:8080/api/v1/execute/my-agent.summarize \
  -H "Content-Type: application/json" \
  -d '{"input": {"text": "AgentField is an open-source control plane..."}}'
# 返回结构化 JSON，不是原始 LLM 文本

核心 API 速查

方法	作用
app.ai(system=, user=, schema=)	调用 LLM，返回 Pydantic 结构化输出
app.call(target, **kwargs)	通过控制平面调用其他 Agent（含递归），返回 asyncio.Future
app.pause(approval_request_id=, ...)	暂停执行，等待人工审批（Human-in-the-Loop）
app.run()	将所有 @app.reasoner 函数暴露为 REST 端点
app.harness(prompt, schema=)	分发到 AForge 等 Coding Harness（默认 aforge）

⚠️ 注意：app.run() 是阻塞调用，会持续运行并自动注册 Agent 到控制平面；需要配合 asyncio 使用，不能在同步上下文中直接调用带 async 的 reasoner。

Human-in-the-Loop 审批

@app.reasoner(tags=["insurance", "critical"])
async def evaluate_claim(claim: dict) -> dict:
    decision = await app.ai(
        system="Insurance claims adjuster. Evaluate and decide.",
        user=f"Claim #{claim['id']}: {claim['description']}",
        schema=Decision,
    )

    if decision.confidence < 0.85:
        # 暂停执行，发送审批请求
        await app.pause(
            approval_request_id=f"claim-{claim['id']}",
            approval_request_url=f"https://internal.example.com/approvals/{claim['id']}",
            expires_in_hours=48,
        )

    await app.call("notifier.send_decision", input={
        "claim_id": claim["id"],
        "decision": decision.model_dump(),
    })
    return decision.model_dump()

使用 Coding Agent 自动生成后端

Claude Code / Codex / Cursor 等工具中输入：

/agentfield Build a claims processor with risk scoring, pattern detection,
and human approval for low-confidence decisions.

会自动生成 docker-compose.yml + Agent 代码 + 可直接 curl 的 REST 端点。

---

典型适用场景

1. 企业内部 AI 能力的 API 化：把 AI 能力嵌入后端服务，不需要 Agent 框架，只需要一个可靠的 HTTP 端点。
2. 多 Agent 递归搜索/研究：一个查询扇出到 N 个子研究 Agent，结果汇总，类似 Deep Research 的自定义实现。
3. 需要人工审批的生产流程：保险理赔、风控审核、内容审核等需要人工介入的 AI 决策链路。
4. 跨服务 Agent 编排：前端 → 后端 API → Agent → 另一个 Agent 的跨服务调用链。
5. Coding Agent 的后端支撑：用 /agentfield prompt 让 Claude Code / Cursor 自动生成带生产基础设施的 Agent 代码。

---

坑与注意

1. 控制平面必须先启动：Agent 代码运行前必须 af server 已启动并监听 localhost:8080（默认），否则 Agent 注册失败。
2. app.run() 阻塞 Terminal：作为开发调试方式，python main.py 会持续占用终端；生产环境需配合 Docker/后台进程管理。
3. 递归深度需要显式限制：示例中的 depth >= 3 深度限制是必需的，没有隐式深度保护；无限制递归会导致控制平面队列爆炸。
4. Python 版本约束：SDK 要求 Python 3.10–3.13，实测低于 3.10 pip install 会报错。
5. af server 在 macOS 会注册 launchd：安装脚本会注册为登录项，使用 af service stop 停止，不要直接 kill，否则会被 launchd 重启。
6. DID/VC 功能默认开启：Agent 构造函数中 vc_enabled=True 和 enable_did=True 是默认行为；如不需要去中心化身份验证会产生额外开销，可显式禁用。
7. 结构化输出依赖 Pydantic：所有 app.ai() 的 schema 必须继承 pydantic.BaseModel，不支持其他 schema 库。
8. 模型名需带完整 provider 前缀：如 anthropic/claude-sonnet-4-20250514，不能只写 claude-sonnet-4；不带前缀时行为不确定（AIConfig 文档未明确定义 fallback 行为）。

---

与同类对比

维度	AgentField	LangChain/LangGraph	AutoGPT	OpenAI Agents SDK
定位	Agent 即 API/微服务	Agent 构建框架	单体自主 Agent	多 Agent 协作
学习曲线	低（纯函数装饰器）	高（图/链概念多）	中	中
生产部署	原生支持（控制平面）	需自行工程化	不适合生产	一般
多 Agent 协作	通过 app.call() 原生支持	支持但复杂	不支持	支持
扇出扩展性	水平扩展（控制平面路由）	单进程	不支持	一般
Human-in-the-Loop	原生 app.pause()	需自行实现	不支持	不支持
SDK 语言	Python/Go/TypeScript	多语言	Python	Python/JS
开源	Apache 2.0	MIT	MIT	Apache 2.0

一句话对比：如果你的场景是"让后端/前端/Cron 能调用 Agent"而不是"探索 Agent 能力边界"，AgentField 是目前最顺滑的选择；相比 LangChain 的图/链概念，AgentField 用纯函数思维让工程团队更容易上手。

---

一句话推荐结论

需要把 AI Agent 像 API 一样嵌入生产系统、或需要跨进程分布式 Agent 递归时，AgentField 是目前上手最快、概念最简洁的选择。

⚠️ 本文档引用版本：Python SDK agentfield（latest，2026-08-27 docs revision）；模型名称格式 anthropic/claude-sonnet-4-20250514 来自官方示例，实际使用时请以 pip show agentfield 输出为准。

来源：GitHub README · Quick Start · Python SDK