1. 为什么 AI Agent 开发者需要一份免费 API 弹药库做 AI Agent 的人都有一个共同的痛点模型能力再强Agent 的手脚不够用照样跑不起来。所谓 Agent本质上是大模型 工具调用 记忆 规划的组合体而工具调用这一环几乎全靠 API 撑着。你要让 Agent 去读一个 GitHub 仓库、拉一份 Gitee 上的代码、查一下 GitLab 的 issue、解析一份 PDF、跑一次网页搜索背后都得有对应的接口。问题在于大部分好用的 API 要么收费要么限流狠要么注册门槛高。个人开发者和小团队做原型验证的时候最怕的就是还没跑通逻辑额度先烧完了。所以这篇内容的核心就是把我自己在搭 Agent 过程中实际用过、验证过的一批免费 API 整理出来重点覆盖代码托管平台GitHub / Gitee / GitLab的读取与下载加速以及几个能直接喂给 Agent 当工具用的通用接口。先说清楚适用人群如果你正在用 LangChain、LlamaIndex、Spring AI、扣子这类框架搭 Agent或者用 Rust、Python 从零写一个带工具调用的智能体这篇里的接口都能直接接进去。如果你只是想给自己的脚本加个能读 GitHub 文件的能力同样适用。我不打算堆一堆用不上的接口只讲那些真正能跑、有免费额度、文档还算能看的。有一个前提得先讲明白免费不等于无限。每个 API 的免费额度、限流策略、是否需要鉴权都不一样我在下面会逐个标注。另外代码托管平台的官方 API 和下载加速是两回事——官方 API 拿的是元数据仓库信息、文件内容、issue 列表加速服务解决的是clone 太慢、raw 文件打不开的问题。这两类需求要分开处理混在一起想会走很多弯路。2. 代码托管平台三巨头的 API 能力对比与选型逻辑在动手接 API 之前得先搞清楚 GitHub、Gitee、GitLab 这三家的 API 各自擅长什么。很多人一上来就想着哪个免费额度多用哪个其实选型的核心不是额度而是你的 Agent 要访问的仓库在哪、要拿什么数据。2.1 三家平台 API 的定位差异GitHub 的 REST API 和 GraphQL API 是目前生态最完整的几乎你能想到的仓库操作都有对应端点读文件内容、列目录、查 commit、搜代码、拿 release、读 issue 和 PR。它的免费额度对未鉴权请求是每小时 60 次按 IP 算带上个人访问令牌PAT后是每小时 5000 次。这个差距非常大所以只要你不是纯做一次性 demo都建议配一个 PAT。Gitee 的 OpenAPI 走的是国内访问路线优势是网络稳定、响应快特别适合国内服务器上跑的 Agent。它的免费额度相对宽松但接口覆盖面比 GitHub 窄一些主要覆盖仓库、issue、PR、用户信息这几块。如果你做的是国内开源项目的 AgentGitee 基本够用。GitLab 的 API 分 self-managed自建和 SaaS 两种。自建 GitLab 的 API 地址是你自己的域名SaaS 版是 gitlab.com。它的特点是 API 版本迭代快老版本比如 14.0 以下在对接一些新工具时会出现兼容问题——这一点在热词里也有人踩过坑IDE 登录报versions older than 14.0 are not supported。所以用 GitLab API 前先确认你的实例版本。平台鉴权方式未鉴权额度鉴权后额度主要强项GitHubPAT / OAuth60 次/小时5000 次/小时接口最全、生态最好Gitee私人令牌较低较宽松国内访问快、稳定GitLabPAT / OAuth视实例而定视实例而定自建可控、CI 集成强2.2 为什么下载加速要单独拎出来讲官方 API 解决的是读数据但 Agent 经常需要拿整个仓库——比如让它分析一个项目的结构、跑一遍代码审查。这时候就得 clone 或者下载 zip 包。而 GitHub 的 clone 在国内网络环境下经常慢到让人怀疑人生raw.githubusercontent.com 更是时不时打不开。这就是下载加速存在的意义。常见的思路有两类一类是镜像站把 GitHub 的仓库内容同步到国内可访问的域名另一类是代理加速服务通过中转节点加速 clone 和 raw 文件下载。这两类服务里有些提供免费额度比如标题里提到的5GB/月免费就是这类加速服务的典型配额。需要提醒的是加速服务只解决下载这一环它不提供 API 元数据查询。所以一个完整的 Agent 方案往往是官方 API 拿元数据 加速服务拿文件内容的组合。2.3 选型时最容易忽略的三个点第一鉴权令牌的权限范围。GitHub 的 PAT 分 fine-grained 和 classic 两种fine-grained 可以精确到单个仓库、单个权限安全性更好但配置麻烦classic 一把梭但权限过大。给 Agent 用的令牌建议按最小权限原则配只给读权限。第二限流的计算方式。GitHub 的限流是按请求次数算的但 GraphQL API 是按点数算的一次复杂查询可能消耗好几个点。如果你的 Agent 频繁调 GraphQL实际可用次数会比想象中少。第三API 版本兼容性。GitHub 的 REST API 有版本头X-GitHub-Api-VersionGitLab 的 API 版本和实例版本强绑定。写代码时把这些版本号显式声明能避免很多昨天还能跑今天报错的问题。3. GitHub API 实战从拿仓库信息到读取文件内容GitHub 是 Agent 最常打交道的平台这一节我把实际会用到的几个核心端点拆开讲每个都给出可直接复制的调用方式和参数说明。3.1 配置个人访问令牌与请求头第一步永远是鉴权。去 GitHub 的 Settings → Developer settings → Personal access tokens 生成一个令牌。给 Agent 用的场景classic 令牌勾选public_repo就够了只读公开仓库如果要读私有仓库勾repo。拿到令牌后所有请求都带上这个头curl -H Authorization: Bearer ghp_你的令牌 \ -H Accept: application/vnd.githubjson \ -H X-GitHub-Api-Version: 2022-11-28 \ https://api.github.com/repos/octocat/Hello-World这里三个头各有作用Authorization是身份凭证Accept指定返回 JSON 格式X-GitHub-Api-Version锁定 API 版本避免 GitHub 悄悄改行为导致你的 Agent 崩掉。很多人只带第一个头结果遇到返回格式变化时一脸懵其实加上版本头就能规避。3.2 读取仓库文件内容的两种方式Agent 要读一个文件有两种路径。第一种是走 Contents APIcurl -H Authorization: Bearer ghp_你的令牌 \ https://api.github.com/repos/octocat/Hello-World/contents/README.md返回的 JSON 里content字段是 Base64 编码的文件内容encoding字段标明编码方式。你需要解码才能拿到原文。这种方式的好处是能拿到文件的元信息大小、sha、下载链接坏处是文件大了之后 Base64 会膨胀而且 API 对单文件大小有限制一般 1MB 以内。第二种是直接走 raw 链接curl -H Authorization: Bearer ghp_你的令牌 \ https://raw.githubusercontent.com/octocat/Hello-World/master/README.mdraw 链接返回的是纯文本不用解码适合 Agent 直接喂给模型。但 raw 域名在国内访问不稳定这时候就需要第 5 节讲的加速方案。提示Contents API 对超过 1MB 的文件会返回content为空、只给download_url这时候得改用 raw 或 Git Blobs API 拿内容。3.3 列出目录与递归遍历仓库树Agent 分析项目结构时需要遍历整个仓库。用 Git Trees API 可以一次性拿到递归的树结构curl -H Authorization: Bearer ghp_你的令牌 \ https://api.github.com/repos/octocat/Hello-World/git/trees/master?recursive1recursive1这个参数是关键不加的话只返回顶层目录。返回结果里每个节点有path、typeblob 或 tree、size字段。你可以据此在 Agent 里构建一棵文件树然后决定读哪些文件。这里有个实操经验大仓库的递归树可能非常大比如一个几万文件的项目返回的 JSON 能有几 MB。建议在 Agent 里加一层过滤只保留你关心的扩展名比如.py、.md、.json否则光是解析这棵树就能把上下文撑爆。3.4 搜索代码与查询 issueGitHub 的搜索 API 对 Agent 特别有用。比如让 Agent 找某个项目里所有用了 requests 库的文件curl -H Authorization: Bearer ghp_你的令牌 \ https://api.github.com/search/code?qrequestsrepo:octocat/Hello-World注意搜索代码 API 对未鉴权请求是完全禁用的必须带令牌。而且它有独立的限流鉴权后每分钟 30 次比普通 API 严格得多。查 issue 则用curl -H Authorization: Bearer ghp_你的令牌 \ https://api.github.com/repos/octocat/Hello-World/issues?stateopenper_page20state可以是 open、closed、allper_page最大 100。Agent 做项目健康度分析时这两个参数组合起来很好用。4. Gitee 与 GitLab 的接口接入细节国内项目绕不开 Gitee企业内网项目绕不开 GitLab。这两家的 API 用法和 GitHub 有相似之处但细节差异不少踩坑点也集中在这里。4.1 Gitee 私人令牌与仓库读取Gitee 的鉴权用私人令牌在个人设置 → 安全设置 → 私人令牌里生成。调用时通过 query 参数传curl https://gitee.com/api/v5/repos/oschina/git-osc?access_token你的令牌读文件内容用curl https://gitee.com/api/v5/repos/oschina/git-osc/contents/README.md?access_token你的令牌Gitee 返回的content同样是 Base64 编码。它的接口路径结构和 GitHub 很像但参数命名有差异比如分页参数 Gitee 用page和per_page和 GitHub 一致但某些接口的默认值不同。迁移代码时不要想当然地照搬 GitHub 的参数逐个接口对文档确认。4.2 GitLab 个人访问令牌与项目导入GitLab 的 PAT 在 User Settings → Access Tokens 生成调用时用PRIVATE-TOKEN头curl -H PRIVATE-TOKEN: 你的令牌 \ https://gitlab.com/api/v4/projects/12345/repository/files/README.md/raw?refmain注意 GitLab 读文件用的是/repository/files/:file_path/raw路径里的斜杠要 URL 编码成%2F。这一点和 GitHub、Gitee 都不一样是新手最容易卡住的地方。GitLab 还有个导入项目的 API可以把外部仓库导入进来curl -X POST -H PRIVATE-TOKEN: 你的令牌 \ https://gitlab.com/api/v4/projects/import?pathmy-projectimport_urlhttps://example.com/repo.git这个接口在批量迁移时很有用但要注意导入是异步的返回后得轮询导入状态。4.3 版本兼容性为什么老版本 GitLab 会报错热词里提到的IDE login failed, GitLab versions older than 14.0 are not supported根因是很多新工具依赖 GitLab 14.0 之后引入的 OAuth 和 API 特性。老版本实例缺少这些端点工具自然连不上。如果你维护的是自建 GitLab遇到这类问题的排查顺序是先确认实例版本/api/v4/version端点再确认工具要求的最低版本最后决定是升级实例还是换工具。升级 GitLab 前务必备份跨大版本升级要按官方升级路径逐版本走不能跳版。平台鉴权头/参数读文件路径常见坑GitHubAuthorization: Bearer/contents/{path}大文件 content 为空Giteeaccess_token 参数/contents/{path}参数默认值差异GitLabPRIVATE-TOKEN 头/repository/files/{path}/raw路径需 URL 编码5. 下载加速方案5GB/月免费额度怎么用才不浪费这一节是标题里的重头戏。GitHub 下载慢、raw 打不开是每个国内开发者都经历过的痛。加速方案的核心思路是换一个能访问的入口去拿同样的内容。5.1 镜像站与代理加速的区别镜像站是把仓库内容定期同步到国内域名你访问的是镜像的副本。优点是稳定、不依赖实时中转缺点是同步有延迟刚提交的代码可能还没同步过来。代理加速是实时中转你请求加速域名它去源站拉取再返回给你。优点是内容实时缺点是依赖中转服务的可用性服务挂了就全挂。对 Agent 来说如果只是读 README、配置文件这类不常变的内容镜像站够用如果要读最新 commit 的代码得用代理加速。5.2 把加速地址接进 Agent 的下载逻辑假设你用的是某加速服务它通常提供两种用法一是替换 clone 地址二是替换 raw 地址。以 clone 为例把https://github.com/user/repo.git替换成加速服务提供的地址格式即可。raw 文件同理把raw.githubusercontent.com换成加速域名。在 Agent 代码里我建议把源地址和加速地址做成可配置的映射而不是硬编码。这样当某个加速服务不可用时能快速切换。下面是一个 Python 的简单封装思路ACCELERATORS { github_raw: https://加速域名/, github_clone: https://加速域名/, } def build_raw_url(repo, branch, path, use_accelTrue): base https://raw.githubusercontent.com if use_accel: base ACCELERATORS[github_raw].rstrip(/) return f{base}/{repo}/{branch}/{path}5.3 5GB 额度怎么分配才合理5GB/月听起来不少但如果你的 Agent 频繁下载大仓库很快就见底。我的分配经验是优先用 API 拿元数据不要动不动就 clone 整个仓库。一个仓库的元数据请求才几 KBclone 下来可能几百 MB。只下载需要的文件用 raw 单文件下载代替整仓 clone。缓存已下载内容同一个文件在 Agent 的多次运行中不要重复下载。用本地文件系统或对象存储做一层缓存key 用文件的 sha 值。大文件走 API 的 download_url而不是自己拼 raw 地址避免路径拼错导致重复请求。注意加速服务的免费额度通常按出站流量算下载和上传都算。如果你的 Agent 还要往仓库推内容记得把上传流量也算进预算。6. 把 API 接进 Agent 的工程化经验接口能调通只是第一步真正让 Agent 稳定跑起来还得处理错误、限流、缓存这些工程问题。这一节讲几个我踩过坑之后总结的做法。6.1 限流处理与重试策略GitHub 的限流响应会带X-RateLimit-Remaining和X-RateLimit-Reset头。Agent 应该在每次请求后检查剩余额度快用完时主动降速或切换令牌。重试策略上不要用固定间隔重试容易在限流恢复的瞬间又打满。用指数退避第一次等 1 秒第二次 2 秒第三次 4 秒最多重试 3 到 5 次。对于 403限流和 5xx服务端错误才重试404 这种客户端错误重试没意义。import time import requests def request_with_retry(url, headers, max_retries5): for i in range(max_retries): resp requests.get(url, headersheaders) if resp.status_code 200: return resp.json() if resp.status_code in (403, 429, 500, 502, 503): wait 2 ** i time.sleep(wait) continue resp.raise_for_status() raise Exception(重试次数用尽)6.2 缓存层设计别让 Agent 重复烧额度Agent 的一个典型行为是反复读同一个文件。比如它在多轮对话里反复确认某个配置如果每次都打 API额度很快见底。缓存的设计要点key 用仓库 分支 文件路径 commit sha因为同一个路径在不同 commit 下内容可能不同。value 存文件内容加一个过期时间。对于 commit sha 固定的内容可以永久缓存对于分支名这种会移动的引用缓存时间设短一点比如 5 分钟。本地缓存用 SQLite 就够了不用上 Redis。Agent 通常是单机跑的SQLite 的读写性能完全够还省了部署成本。6.3 错误处理区分重试有用和重试没用Agent 调 API 出错时最忌讳无脑重试。要按错误类型分类错误类型HTTP 状态处理方式限流403 / 429指数退避重试或切换令牌服务端错误500 / 502 / 503退避重试资源不存在404不重试返回明确错误给 Agent鉴权失败401不重试检查令牌参数错误422不重试修正参数把这张表做成 Agent 的错误处理策略能省掉大量无效请求。我见过太多 Agent 因为无脑重试 404把额度全烧光的案例。6.4 令牌管理别把密钥写进代码最后一条也是最容易被忽视的令牌绝对不能硬编码在代码里。用环境变量或密钥管理服务。如果是多用户场景每个用户用自己的令牌不要共用。在 Agent 里令牌应该从配置读取并且日志里要脱敏。很多事故就是因为调试日志把令牌打出来了然后日志被传到公开的地方。7. 几个能直接当 Agent 工具用的通用 API除了代码托管平台Agent 还需要一些通用能力接口。这里挑几个免费、好用、我实际验证过的。7.1 大模型 API 的免费额度利用做 Agent 绕不开大模型。DeepSeek、智谱、Kimi 这些国内厂商都提供免费额度或低价 API。接入时注意几点一是 API Key 的配置方式很多框架要求通过环境变量传二是上下文长度限制热词里提到的maximum context length is 1048576 tokens就是典型报错说明你喂的内容超了模型上限三是不同厂商的接口格式差异OpenAI 兼容格式现在是主流但细节仍有出入。以 DeepSeek 为例它的接口兼容 OpenAI 格式调用时把 base_url 换成 DeepSeek 的地址即可。如果报no api key for provider route通常是环境变量名没对上检查一下框架要求的变量名。7.2 文档解析类 APIAgent 处理 PDF、Word 这类文档时需要解析接口。MinerU 这类工具能把 PDF 转成结构化文本适合喂给模型。使用时注意扫描版 PDF 需要 OCR纯文本 PDF 直接解析更快解析大文档要分页处理避免一次性返回超长内容。7.3 搜索类 APIAgent 要联网查资料得有搜索接口。免费搜索 API 的额度通常不大建议在 Agent 里加一层是否需要搜索的判断不要每轮都搜。搜索结果要截断只取前几条的摘要避免上下文爆炸。8. 我在实际搭建中踩过的坑与应对讲几个真实踩过的坑都是文档里不会写、但实际一定会遇到的。第一个坑是raw 链接的缓存问题。raw.githubusercontent.com 有 CDN 缓存你刚 push 的代码通过 raw 链接可能几分钟内还是旧内容。Agent 如果依赖 raw 读最新代码会读到过期数据。解决办法是读文件时带上 commit sha 而不是分支名或者直接用 Contents API 拿带 sha 的内容。第二个坑是Gitee 令牌的权限粒度。Gitee 的私人令牌权限选项比 GitHub 粗有时候你只想读公开仓库但生成的令牌权限过大。建议单独建一个只用于 Agent 的令牌出问题能快速吊销。第三个坑是加速服务的地址格式不统一。不同加速服务对 clone 地址、raw 地址的替换规则不一样有的要改域名有的要加前缀。接进 Agent 前先用 curl 手动验证一遍确认返回的是你要的内容再写进代码。第四个坑是GitLab 自建实例的证书问题。内网 GitLab 常用自签证书Python 的 requests 默认会拒绝。要么把证书加进信任链要么在请求时关掉验证仅限内网可信环境。生产环境强烈建议用前者。第五个坑是API 返回的编码问题。GitHub 和 Gitee 的文件内容都是 Base64但有些文件本身是二进制比如图片解码后不能当文本处理。Agent 读文件前要先判断文件类型二进制文件走下载而不是解码。9. 一套可复用的 Agent 工具层封装思路最后讲讲怎么把这些 API 组织成一个 Agent 能用的工具层。核心思路是每个 API 封装成一个工具函数统一错误处理和缓存。工具函数的签名要统一比如都返回{success: bool, data: ..., error: ...}这样的结构方便 Agent 判断调用结果。每个工具要有清晰的描述description因为 Agent 是靠描述来决定调哪个工具的。描述里要写清楚这个工具干什么、需要什么参数、返回什么、有什么限制。参数校验要做在工具层不要指望模型每次都传对参数。比如仓库名必须是owner/repo格式路径不能有..这些都在工具函数里校验不合法直接返回错误不打 API。缓存和限流也放在工具层统一处理这样上层 Agent 逻辑不用关心这些细节。工具层就像一个API 网关把外部接口的不稳定性挡在外面给 Agent 一个稳定的调用界面。这套封装做完之后你会发现加新 API 变得很简单——只要按同样的模式写一个工具函数注册进去就行。Agent 的能力扩展本质上就是工具层的扩展。我在实际项目里用这套思路接过十几个 API从代码托管到文档解析到搜索整体跑下来很稳。关键不在于接口本身多高级而在于错误处理、缓存、限流这些脏活有没有做扎实。免费 API 的额度是有限的但把工程做扎实了有限的额度也能撑起一个能用的 Agent。