用 Plano 的 Bearer 授权能力接入 Spotify API：Agent 应用调用第三方接口的实战指南

用 Plano 的 Bearer 授权能力接入 Spotify APIAgent 应用调用第三方接口的实战指南【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano在构建 Agent 应用时接入带鉴权的第三方 API 往往需要额外编写令牌管理、请求头注入等样板代码。本指南以 Plano 开源仓库中的 Spotify Bearer 授权演示为例讲解如何通过 Plano 的 Prompt Target 与http_headers配置让 Agent 在零业务代码的前提下安全调用 Spotify Web API 获取新专辑与艺人热门单曲并支持连续多轮的自然语言交互。读完本文你将掌握 Bearer 令牌注入的配置原理、完整参数说明以及从启动到联调的端到端操作流程。演示场景概述该演示位于 demos/integrations/spotify_bearer_auth目标非常聚焦让用户通过自然语言与两个 Spotify 官方接口交互/v1/browse/new-releases获取 Spotify 精选的最新专辑列表对应“Browse”标签页场景/v1/artists/{artist_id}/top-tracks获取指定艺人的热门单曲列表。典型的交互流程是用户先问“Show me the latest releases in the US”紧接着追问“Show me top tracks from Taylor Swift”——后者无需用户重新描述任何上下文Plano 会自动完成意图识别、参数抽取与路径拼接。从实现角度看整个过程中不需要你编写任何后端代理代码授权头、路径参数、HTTP 调用、结果格式化全部由 Plano 配置驱动完成。核心原理Prompt Target 请求头注入Bearer 授权的本质是在每一次对上游 API 的 HTTP 请求中携带Authorization: Bearer token请求头。在 Plano 中这个能力被收敛为 Prompt Target 的endpoint.http_headers配置项配合环境变量替换机制实现“密钥不出配置文件、令牌不落盘”的安全实践。源码层面的证据在 crates/common/src/configuration.rs 中EndpointDetails结构体明确定义了端点所需的三个核心字段pub struct EndpointDetails { pub name: String, pub path: OptionString, #[serde(rename http_method)] pub method: OptionHttpMethod, pub http_headers: OptionHashMapString, String, }而PromptTarget对应配置文件里的prompt_targets数组项则在其上叠加了parameters、system_prompt、auto_llm_dispatch_on_response等属性其中parameters会被转换为 OpenAI 兼容的 Function Calling 工具定义见同一文件中的impl FromPromptTarget for ChatCompletionTool这正是“LLM 抽取参数 → 组装 HTTP 请求”的桥梁。请求头真正注入上游请求的位置在 crates/prompt_gateway/src/stream_context.rsPlano 先构造包含请求 ID、traceparent 等内部头的默认请求头集合然后读取endpoint_details.http_headers并将其中的键值逐一覆盖/追加到实际发出的请求中// override http headers that are set in the prompt target let http_headers endpoint_details.http_headers.clone().unwrap_or_default(); for (key, value) in http_headers.iter() { headers.insert(key.as_str(), value.as_str()); }这意味着Authorization: Bearer $SPOTIFY_CLIENT_KEY会在请求发出前完成环境变量替换并以标准 HTTP 头的形式透传给 Spotify。环境变量替换机制根据 skills/rules/config-secrets.md 中的约定Plano 支持在配置值中使用$VAR_NAME语法引用环境变量该能力适用于access_key、状态存储的connection_string以及 Prompt Target 与端点中的http_headers。planoai up启动时会自动加载当前目录下的.env文件也接受 shell 中直接导出的环境变量若配置引用的变量缺失启动会失败并明确列出缺失的键名。因此配置文件里只出现$SPOTIFY_CLIENT_KEY占位符真正的令牌保存在.env中.env应加入.gitignore避免密钥进入版本库配置校验器 config/plano_config_schema.yaml 将http_headers定义为additionalProperties: string的对象即任意自定义请求头Authorization、X-Api-Key 等均可按此模式声明。配置详解逐段拆解 config.yaml演示的完整配置位于 demos/integrations/spotify_bearer_auth/config.yaml下面按区块讲解每个字段的作用与可调项。版本与监听器version: v0.3.0 listeners: - type: prompt name: prompt_listener port: 10000 overrides: optimize_context_window: trueversion声明配置结构版本Plano 会据此选择配置解析与行为路径listeners声明对外服务的监听器。type: prompt表示 OpenAI 兼容的 Prompt 网关Chat Completions 协议port: 10000即接入端口。schemaconfig/plano_config_schema.yaml中还支持model、agent类型、address、timeout、router、max_retries等扩展项overrides.optimize_context_window开启上下文窗口优化在多轮会话中控制上下文增长schema 定义见 config/plano_config_schema.yaml。上游端点声明endpoints: spotify: endpoint: api.spotify.com protocol: httpsendpoints是一组命名上游集群键名即后续prompt_targets.endpoint.name的引用名。此处spotify集群指向api.spotify.com且强制https协议。schemaconfig/plano_config_schema.yaml允许为每个端点配置connect_timeout、http_host、prefix_affinity自托管多副本后端按前缀一致性哈希路由等更多属性。结果格式化system_promptsystem_prompt: | I have the following JSON data representing a list of albums from Spotify: ... Please convert this JSON into Markdown with the following layout for each album: ...该区块并非普通指令而是针对回调响应的后处理提示Spotify 返回的 JSON 会被注入该提示指示 LLM 将每条专辑渲染为「专辑封面图 → 标题/艺人/发行日期 → Spotify 收听链接」的 Markdown 卡片并要求输出合法的 Markdown。这正是截图中聊天界面呈现结构化专辑卡片的原因——数据格式化逻辑同样由配置完成而非业务代码。模型提供商model_providers: - access_key: $OPENAI_API_KEY model: openai/gpt-4o default: true声明承载意图理解、参数抽取与结果格式化的 LLMaccess_key通过环境变量注入 OpenAI 密钥default: true标记默认模型。模型名使用openai/gpt-4o的“provider/model”格式Plano 的模型路由层支持按此标识进行分发与替换。Prompt Targets授权与参数抽取的核心prompt_targets: - name: get_new_releases description: Get a list of new album releases featured in Spotify (shown, for example, on a Spotify players Browse tab). parameters: - name: country description: the country where the album is released required: true type: str in_path: true - name: limit type: integer description: The maximum number of results to return default: 5 endpoint: name: spotify path: /v1/browse/new-releases http_headers: Authorization: Bearer $SPOTIFY_CLIENT_KEY - name: get_artist_top_tracks description: Get information about an artists top tracks parameters: - name: artist_id description: The ID of the artist. required: true type: str in_path: true endpoint: name: spotify path: /v1/artists/{artist_id}/top-tracks http_headers: Authorization: Bearer $SPOTIFY_CLIENT_KEY两个 Prompt Target 完整展示了该能力的关键要点元素说明本演示中的取值name目标唯一标识同时作为 LLM 可见的工具名get_new_releases/get_artist_top_tracksdescription意图匹配与工具选择的依据描述越具体命中越准“Get a list of new album releases featured in Spotify…”parameters[].name参数名须与路径模板中的占位符对应country、artist_idparameters[].type数据类型str、integer 等见下节str/integerparameters[].required是否必填缺失时 LLM 会向用户追问trueparameters[].in_path参数是否嵌入 URL 路径true拼接进 pathparameters[].default用户未提及时使用的默认值limit: 5endpoint.name引用endpoints中声明的上游spotifyendpoint.path请求路径{param}语法与in_path: true参数按名替换/v1/browse/new-releases、/v1/artists/{artist_id}/top-tracksendpoint.http_headers随请求注入的静态请求头支持$ENV替换Authorization: Bearer $SPOTIFY_CLIENT_KEY参数属性在 docs/source/concepts/prompt_target.rst 中有完整官方说明type支持int、str、float、bool、list、set、dict、tuplein_path决定参数是拼入 URL 路径还是作为查询串此外还支持enum允许值列表、format如日期2019-12-31、items复合类型元素声明。schema 层面 config/plano_config_schema.yaml 要求每个 target 至少包含name与description端点至少包含name与path并限定http_method仅可为GET/POST。值得注意的细节artist_id与country均声明in_path: true说明 LLM 抽取出的值会直接替换路径模板{artist_id}/{country}而limit未声明in_path会被作为查询参数附加。演示中 Spotify 的新专辑接口把country作为路径段/v1/browse/{country}/new-releases变体这里则直接拼接在/v1/browse/new-releases之后具体以你的目标 API 路径设计为准。可观测性tracing: random_sampling: 100random_sampling: 100表示以 100% 概率对请求采样并上报链路追踪取值范围 0–100。schemaconfig/plano_config_schema.yaml还支持trace_arch_internal、opentracing_grpc_endpoint、span_attributes自定义静态属性与头前缀以及exporters如 PostHog等高级配置。启动演示从密钥到第一个问题前置准备按仓库根目录 README.md 中的 Prerequisites 安装好 Plano 运行环境含planoaiCLI与 Docker可选 UI 服务需要。获取 Spotify 令牌在 Spotify 开发者后台创建应用获得 Client Key / Client Secret调用 Spotify 的https://accounts.spotify.com/api/token令牌端点用curl或类似工具以client_credentials等流程换取访问令牌该令牌即下文.env中的SPOTIFY_CLIENT_KEY。创建 .env 并启动在 demos/integrations/spotify_bearer_auth 目录下创建.envOPENAI_API_KEYyour_openai_api_key SPOTIFY_CLIENT_KEYyour_spotify_api_token然后一键启动sh run_demo.sh查看 run_demo.sh 可知脚本行为若.env不存在且 shell 中已导出OPENAI_API_KEY脚本会自动生成.env不会覆盖已存在的文件支持sh run_demo.sh --with-ui附加启动 UI 服务先用docker compose up -d拉起 AnythingLLM 与 JaegerJaeger 必须先于 Plano 启动以便抢占 OTEL 端口 4317再执行planoai up config.yamlsh run_demo.sh down会依次执行docker compose down与planoai down完成清理。启动成功后浏览器访问http://localhost:18080AnythingLLM 的 Chat 界面已通过 docker-compose.yaml 中的GENERIC_OPEN_AI_BASE_PATHhttp://host.docker.internal:10000/v1指向 Plano 的 10000 端口监听器。发起对话在聊天框输入show me new album releases in the USPlano 的完整处理链路如下意图匹配LLM 依据get_new_releases的描述识别意图并抽取参数countryUSlimit缺省时用默认值5参数组装country因in_path: true嵌入路径构建出面向api.spotify.com的 HTTPS GET 请求Bearer 注入请求发出前Authorization: Bearer SPOTIFY_CLIENT_KEY由 crates/prompt_gateway/src/stream_context.rs 注入请求头结果格式化Spotify 返回的专辑 JSON 交由system_prompt定义的后处理流程转为 Markdown 卡片返回给用户。继续追问Show me top tracks from Taylor Swift由于是两个独立 Prompt Target用户无需重复任何上下文——Plano 会在此前对话基础上识别新意图get_artist_top_tracks抽取artist_id如06HL4z0CvFAxyc27GXpf02并替换进/v1/artists/{artist_id}/top-tracks。这正是多轮 Agent 交互中“先浏览、再下钻”的典型范式。扩展与安全建议多目标与多 API每个第三方 API 对应一个endpoints条目每个操作对应一个 Prompt Target即可在一个 Plano 实例中统一接入多家服务鉴权头各自独立配置密钥生命周期Spotify 令牌过期后仅需更新.env并重启 Plano业务层无感知若令牌支持刷新可在获取新令牌后替换SPOTIFY_CLIENT_KEY的值配置即文档description与system_prompt是决定意图识别与输出质量的关键杠杆建议对每个参数写清取值范围与示例与 docs/source/concepts/prompt_target.rst 中的参数约定保持一致排障入口开启tracing.random_sampling后可在 Jaegerhttp://localhost:16686中观察每次 Spotify 调用 span确认请求头、路径与响应是否符合预期。小结通过demos/integrations/spotify_bearer_auth这一个演示可以看到 Plano 把“第三方 API 鉴权接入”压缩成了纯配置动作endpoints声明上游prompt_targets声明可调用的操作、参数与http_headers环境变量负责密钥隔离LLM 负责意图理解与参数抽取system_prompt负责结果美化。从 crates/common/src/configuration.rs 的数据结构到 crates/prompt_gateway/src/stream_context.rs 的请求头覆盖逻辑再到配置 schema 的严格校验整条链路都有源码可查、有示例可跑。理解了这一模式你就可以将同样的手法扩展到任何需要 Bearer Token 或自定义请求头的第三方服务上为 Agent 应用快速补齐外部数据接入能力。【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考