[LINUX DO 精选] 【AgentSeed】从零开始的Agent内核开发教程（一） —— 从“大模型”开始

这篇教程是 AgentSeed 系列的第一篇，目标是从最小可运行原型开始理解 Agent 内核。作者先把普通聊天应用拆成四步：客户端收集输入、发送请求、模型服务生成回答、客户端接收并展示结果。网页或桌面应用替用户封装了调用流程；改用代码调用后，开发者才能自行决定上下文、工具调用、后续处理，以及与数据库、文件系统或业务系统的连接方式。

前置条件

Python 环境，并安装 httpx。
一个兼容 Anthropic Messages API 的公开模型服务。接口地址通常以 /v1/messages 结尾。
服务商提供的 API Key 与模型名称。示例中的地址、密钥和模型名都是占位值，不可直接用于生产环境。

获取对应版本

教程使用 AgentSeed 仓库的 v0.1-llm-api-call 版本：

git clone https://github.com/Nick-Hogo/AgentSeed.git
cd AgentSeed
git switch --detach v0.1-llm-api-call

最小 Agent 原型

import httpx

base_url = "https://api.example.com/v1/messages"
api_key = "sk-xxxx"
model = "kimi-k3"

while True:
    user_input = input("You> " )

    response = httpx.post(
        base_url,
        headers={
            "x-api-key": api_key,
            "anthropic-version": "2023-06-01",
        },
        json={
            "model": model,
            "messages": [
                {"role": "user", "content": user_input},
            ],
        },
        timeout=60,
    )

    data = response.json()
    print("Assistant>", end=" " )
    for block in data["content"]:
        if block["type"] == "text":
            print(block["text"], end="")
    print()

while True 构成最基础的输入—请求—输出循环。可以自行加入 exit 等终止条件。按这段代码的实际行为，每次请求只携带当前用户输入；它实现连续交互，但尚未保存此前消息历史。

三个核心配置

参数	作用	示例
`base_url`	模型服务的接口地址	`https://api.example.com/v1/messages`
`api_key`	服务商签发的访问凭证	`sk-xxxx`（占位符）
`model`	要调用的模型标识	`claude-5-fable` 或服务商实际标识

HTTP 请求由三部分组成：URL 指定目标接口；Header 携带认证和协议版本；JSON Body 携带模型与消息。教程采用 POST，因为客户端要先提交用户输入，再获取模型响应。

请求头中的 x-api-key 用于认证，anthropic-version: 2023-06-01 指定 Anthropic API 版本。请求体中的 messages 目前只有一条 user 消息；后续要实现真正的上下文对话，需要维护并发送消息历史。

响应结构

服务通常会返回模型标识、角色、内容块、停止原因和 Token 用量。简化结构如下：

{
  "model": "claude-fable-5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! How can I help you today?"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 32,
    "output_tokens": 39
  }
}

常用字段：

content 是内容块列表，不保证第一块一定是正文。
content[].type 可能是 text、thinking 等类型，因此示例遍历列表，只打印 type == "text" 的块。
stop_reason == "end_turn" 表示本轮生成结束。
usage.input_tokens 和 usage.output_tokens 可用于统计调用消耗。

运行与验证

把三个占位配置替换为服务商实际值，密钥不要提交到代码仓库。
安装依赖后运行脚本，在 You> 提示符输入问题。
成功时应出现 Assistant>，随后输出服务返回的所有文本块。
可检查返回 JSON 中的 model、stop_reason 与 usage，确认调用对象、结束状态和 Token 消耗符合预期。

当前版本的边界

这是 v0.1 原型，只完成最基本的模型 API 调用和命令行循环。
代码尚未维护消息历史，也没有工具调用、记忆、数据库或文件系统接入。
示例没有展示 HTTP 状态码检查、超时重试和异常响应处理；接入实际服务时需要补齐。
不同服务商的接口格式和模型标识可能不同，应以实际服务商文档为准。

原作者：guanhuhao（Nick Hugo）
原帖：https://linux.do/t/topic/2924487