AI Agent 上手实操：从调 API 到最小 Agent

0准备环境

1. 装 Python 3.10+（python --version 检查）。
2. 装官方库：pip install openai
3. 准备一个能联网的终端（PowerShell / Git Bash 都行）。

1用云端 API：先让它回一句话

选一家国内能直接访问的模型服务（DeepSeek、通义千问、智谱 GLM、Kimi 等都行，大多是 OpenAI 兼容接口）。本文以 DeepSeek 为例。先创建 API Key 并存进环境变量：

# PowerShell
$env:DEEPSEEK_API_KEY = "sk-你的key"

# macOS / Linux / Git Bash
export DEEPSEEK_API_KEY="sk-你的key"

新建 hello.py，粘贴并运行 python hello.py：

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.deepseek.com",   # OpenAI 兼容，国内可直接访问
    api_key=os.environ["DEEPSEEK_API_KEY"],
)

resp = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "你是个只说结论的技术助手"},
        {"role": "user", "content": "解释什么是 Agent，50 字以内"},
    ],
)
print(resp.choices[0].message.content)

看到输出就说明云端调用通了。

2换本地模型：不花钱也能跑

1. 装 Ollama（官网下载安装）。
2. 拉一个中小模型：ollama run qwen2.5:3b（首次会自动下载）。
3. 代码几乎不用改，只加一行 base_url：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",  # Ollama 的兼容接口
    api_key="ollama",                        # 本地不需要真 key
)

resp = client.chat.completions.create(
    model="qwen2.5:3b",
    messages=[{"role": "user", "content": "你好，用一句话介绍你自己"}],
)
print(resp.choices[0].message.content)

3做最小 Agent：让它自己“算数”

给模型一个计算器工具，遇到数学题它会自己决定调用，而不是瞎算。新建 agent.py：

import json
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.deepseek.com",
    api_key=os.environ["DEEPSEEK_API_KEY"],
)

def calc(expr):
    return str(eval(expr))   # 演示用；正式项目用安全计算库

tools = [{
    "type": "function",
    "function": {
        "name": "calc",
        "description": "计算数学表达式",
        "parameters": {
            "type": "object",
            "properties": {
                "expr": {"type": "string", "description": "如 123*456"}
            },
            "required": ["expr"],
        },
    },
}]

messages = [{"role": "user", "content": "123*456 等于多少？顺便告诉我 9 的平方根。"}]

for _ in range(5):                      # 最多循环 5 轮，防止死循环
    resp = client.chat.completions.create(
        model="deepseek-chat", messages=messages, tools=tools
    )
    msg = resp.choices[0].message
    messages.append(msg)

    if msg.tool_calls:                   # 模型说：我要调工具
        for call in msg.tool_calls:
            args = json.loads(call.function.arguments)
            result = calc(args["expr"])  # 你的程序真正执行
            print("调用工具:", call.function.name, args, "=>", result)
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": result,       # 把结果喂回去
            })
    else:
        print("最终回答:", msg.content)  # 模型已经完成
        break

跑 python agent.py，你会看到它“调工具 → 拿结果 → 给最终答案”。这就是 Agent 的最小闭环。

4给它加“资料”：最小 RAG

想让模型回答你自己的文档，做法：切片 → 转向量 → 检索 → 拼进 Prompt。用最朴素的实现：

import numpy as np
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.deepseek.com",
    api_key=os.environ["DEEPSEEK_API_KEY"],
)

docs = [
    "小明是一名正在学编程的大学生",
    "小明喜欢自己动手部署开源软件",
    "小明的个人网站还需要备案才能上线",
]

def emb(texts):
    # DeepSeek 暂不提供 embedding；改用支持 embedding 的国内服务或本地模型
    r = client.embeddings.create(model="你服务商的-embedding-模型", input=texts)
    return [x.embedding for x in r.data]

doc_vecs = np.array(emb(docs))
q_vec = np.array(emb(["redwenzi 学什么专业"])[0])
scores = doc_vecs @ q_vec                 # 余弦相似度（未归一化也可比大小）
top = docs[int(np.argmax(scores))]

prompt = f"只根据下面资料回答：\n资料：{top}\n问题：redwenzi 学什么专业？"
ans = client.chat.completions.create(model="deepseek-chat",
                                     messages=[{"role": "user", "content": prompt}])
print(ans.choices[0].message.content)

资料多了以后，把向量存进向量库（Chroma / pgvector 等），检索取 TopK 即可。

5部署给别人用

1. 量小/自用：继续用上面的云端 API 或 Ollama 本地接口。
2. 多人高并发：GPU 服务器装 vLLM：pip install vllm → vllm serve 模型名，自带 OpenAI 兼容接口。
3. 把 Python 脚本包成接口：FastAPI 起一个 /chat 路由，外面就能调。
4. 发布前至少做：限制并发、校验输入、给 API 加 Key、记录日志。

常见报错对照

• AuthenticationError → Key 没设对或没加到环境变量。
• model not found → 模型名不对，去服务商文档查。
• 本地连不上 → Ollama 没启动，或 base_url 端口写错（默认 11434）。
• 上下文超长 → 精简 messages，或改成只传最近几轮。
• Agent 死循环 → 加最大轮数（上面代码里的 range(5)）。