安装与快速开始¶

本章带你从零跑起一个「客服 Hello World」Agent：装包 → 用几行代码建工作流 → 起网关 → 发一条对话并收到回复。全程约 5 分钟，不需要任何模型 API Key（示例用本地回显模型代替真实 LLM）。

1. 安装¶

环境要求：Python ≥ 3.11；装包机器需能访问 PyPI（运行时依赖会自动从 PyPI 拉取）。

框架以构建好的 wheel 交付，统一通过 pip 安装（无需访问源码仓库）：

# 把拿到的 wheel 文件(如 agentframework-0.3.0-py3-none-any.whl)放到当前目录后：
pip install agentframework-0.3.0-py3-none-any.whl

运行时依赖自动安装：wheel 元数据已声明框架全部运行时依赖，pip 会从 PyPI 自动装好，无需你手动安装任何 requirements。
兼容清单（仅供参考，说明会被拉到哪些版本）：langgraph==1.1.6、langchain-core==1.3.1、pydantic==2.11.10、fastapi==0.116.1、uvicorn==0.44.0、sse-starlette==3.0.3、httpx>=0.27、langgraph-checkpoint==4.1.1、langgraph-checkpoint-sqlite>=3.0。
若目标环境离线 / 无法访问 PyPI，才需要随 wheel 一并提供依赖清单或离线包，见文末「离线安装」。

验证安装成功：

python -c "import agentframework; print(agentframework.__version__)"
# 0.3.0

可选能力：PostgreSQL / MongoDB / MySQL 的断点持久化 saver 是可选依赖，默认不装。从文件/URL 装 wheel 时 extras 不生效，需额外装对应包： pip install langgraph-checkpoint-postgres（PostgreSQL）、pip install langgraph-checkpoint-mongodb（MongoDB）、pip install langgraph-checkpoint-mysql（MySQL ≥8.0.19 / MariaDB ≥10.7.1）。接入见断点持久化。

2. 建第一个工作流¶

AgentFramework 的核心编排对象是 Workflow。我们加两个内置节点：

ChatLLM：调用模型生成回复（这里注入一个本地回显模型，无需真实 Key）；
Answer：输出节点，把 ChatLLM 的回复作为最终答案返回给用户。

新建 hello.py：

from agentframework import Workflow
from agentframework.nodes import Answer, ChatLLM


class EchoModel:
    """本地演示模型：把用户输入原样回显，避免需要真实 API Key。"""

    def invoke(self, messages):
        text = str(messages[-1].content) if messages else "你好"
        return f"客服回复: {text}"

    def stream(self, messages):
        from langchain_core.messages import AIMessage

        reply = self.invoke(messages)
        for ch in reply:
            yield AIMessage(content=ch)


def build():
    wf = Workflow(name="hello")
    wf.add_node(
        ChatLLM(
            name="llm",
            chat_model=EchoModel(),  # 可注入任意「可调用对象」或 LLMClient
            system="你是一个专业的客服助手",
            output=False,  # 严格收口：流式内容不进 answer，由 Answer 收口
        )
    )
    wf.add_node(Answer(name="ans", text=wf.ref("llm.reply")))  # 引用 llm 的输出 reply
    wf.add_edge("llm", "ans")  # 连线：llm → ans
    return wf

要点：

wf.ref("llm.reply") 是节点输出引用：编译期校验存在性、运行期从状态取值注入。
output=False 表示 ChatLLM 不作为输出节点，最终回答统一由 Answer 收口（避免「模型流 + Answer 整段」双重输出）。

3. 起网关并对话¶

工作流 compile() 后，用 serve() 一键注册并启动 FastGPT 兼容网关：

from agentframework import serve

if __name__ == "__main__":
    app = build().compile()  # 返回原生 LangGraph CompiledStateGraph
    serve({"hello": app}, host="0.0.0.0", port=8080)

需要 PYTHONPATH=src（源码运行时）：cd agentframework && PYTHONPATH=src python hello.py。若用 wheel 安装则无需。

启动后，另开一个终端发一条对话（appId 对应注册名 hello，chatId 用于会话/断点映射，messages 是本次对话历史）：

curl -N http://localhost:8080/api/v2/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "appId": "hello",
    "chatId": "user-001",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

你会收到一条 SSE 事件流（answer 事件携带回复增量，末尾 [DONE]）。curl -N 关闭缓冲以便实时看到流式输出。

4. 不启动 HTTP：纯库方式直接跑¶

只有需要对外对话协议（SSE / interactive / 变量回传）时才需要网关。若你只是想在程序里跑一个工作流并拿到结果，直接调用编译后的图即可：

app = build().compile()
# 直接以编程方式执行（config 里可指定 thread_id，用于断点/会话）
result = app.invoke(
    {"input": {"user": "你好"}},  # 输入 state（键与编译期 schema 对齐）
    config={"configurable": {"thread_id": "u-1"}},
)
print(result)

说明：纯库 invoke 的输入 state 键由编译器从节点声明汇总得到；对含 user_input 缺省兜底、interactive 等依赖网关注入的运行上下文（消息、变量、流式回调）的场景，请走网关方式。每个内置节点都说明了自己的输入输出字段。

下一步¶

看懂整体概念 → 核心概念 · 心智模型
把节点换成真实模型、加条件分支、检索知识库 → 按场景看指南
查看每个节点能干什么 → 内置节点速查

附：离线安装（无 PyPI 环境）¶

若目标机器无法访问 PyPI，pip install 拉不到运行时依赖。此时需随 wheel 一并提供离线依赖包（由交付方按锁定的依赖版本下载好）。基本做法：

# 在能联网的机器上，把框架运行时依赖离线下载到 wheels/ 目录
pip download -r requirements.lock -d wheels/
# 再把本框架 wheel 也放进去
cp agentframework-0.3.0-py3-none-any.whl wheels/

# 在离线机器上，从本地 wheels/ 安装（不访问 PyPI）
pip install --no-index --find-links=wheels/ agentframework-0.3.0-py3-none-any.whl

联网环境直接 pip install agentframework-0.3.0-py3-none-any.whl 即可，运行时依赖会自动从 PyPI 装上，无需本节。

可运行示例¶

以下示例的完整可运行源码与运行说明已收录进本站示例代码，与本文档各章节一一对应：

示例	演示能力	对应文档
customer_service	客服 Hello World（本章）	快速开始
ifelse_demo	条件分支（二分支/多分支）	指南 01
kb_qa	知识库问答	指南 02
http_flow	HTTP 调用	指南 03
interactive_flow	交互式暂停/恢复	指南 04
sqlite_persistence	SQLite 断点持久化	指南 06
auth_gateway	API Key 鉴权	指南 08
withdrawal_customer_service	完整多轮状态机案例	指南 01/04/05