LiteLLM Terraform Provider 中 litellm_agents 数据源详解以 IaC 方式清点与筛选代理上的 A2A Agent【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm本篇围绕 LiteLLM 官方 Terraform Provider 的litellm_agents数据源展开它用于以声明式方式读取 LiteLLM Proxy 上注册的全部 A2A Agent并支持可选的实时健康过滤。读完本文你可以掌握该数据源的完整参数与属性参考、结合terraform output的实战用法并从 Provider 的 Go 源码与 Proxy 的GET /v1/agents接口实现两个层面理解健康检查health_check背后的探测逻辑与边界行为。数据源定位它从哪里读取 Agentlitellm_agents是 Provider 内置的只读数据源用于检索当前 LiteLLM Proxy 上注册的所有 A2A Agent 列表。其文档原文见 agents.md。在 Provider 注册表中可以确认它的挂载位置——provider.go 的DataSourcesMap中注册了litellm_agents: dataSourceLiteLLMAgents()而与之配套的资源litellm_agent、单实例数据源litellm_agent也在同一文件中注册。从源码结构看该数据源与同文件的litellm_agent单实例查询共同构成 Agent 的写与读闭环数据源litellm_agents本文主角列出全部 Agent支持健康过滤数据源litellm_agent按agent_id查询单个 Agent额外导出agent_card_params、object_permission、extra_headers等字段详见 agent.md资源litellm_agent管理 Agent 的完整 CRUD实现见 resource_agent.go。使用前需要按 index.md 完成 Provider 认证配置terraform { required_providers { litellm { source BerriAI/litellm version ~ 1.99.0 # 与你 Proxy 运行的 LiteLLM 版本保持一致 } } } provider litellm { api_base https://your-litellm-proxy.com api_key var.litellm_api_key }两点适用前提需要注意依据 provider.go 的 Schema 与 README认证api_base/api_key必填也可分别通过环境变量LITELLM_API_BASE、LITELLM_API_KEY提供另有可选的insecure_skip_verify对应LITELLM_INSECURE_SKIP_VERIFY用于自签证书场景。版本对齐Provider 版本号即 LiteLLM 版本每次 Proxy 发布会同步发布同版本 Provider建议用~ 你的 Proxy 版本精确对齐避免 Provider 与 Proxy API 漂移。使用示例原文档给出的完整用法如下继承自 agents.mddata litellm_agents all {} output agent_ids { value data.litellm_agents.all.ids } # Only agents whose URL is currently reachable (or that have no URL) data litellm_agents healthy { health_check true }两个要点默认全量读取data litellm_agents all {}不传任何参数即可导出idsAgent ID 列表与agentsAgent 明细列表并可通过terraform output暴露给下游模块、告警或 CMDB 同步逻辑使用健康过滤变体health_check true时Proxy 会逐个探测 Agent 的 URL仅返回URL 可达或根本没有 URL的 Agent。实战组合与健康 Agent 联动下游资源由于ids是标准的 string 列表可以很方便地与其他资源做依赖例如把当前健康的 Agent注入到某个配置资源中示意# 仅引用健康检查后仍然在线的 Agent ID output healthy_agent_ids { value [for a in data.litellm_agents.healthy.agents : a.agent_id] }Argument Reference数据源支持的参数与文档一致并对照 data_source_agent.go 的 Schema 实现确认参数类型必填默认值说明health_checkbool否false置为true时Proxy 会对每个 Agent 的 URL 发起探测仅返回可达或无 URL的 Agent在 Go 实现中health_check被声明为Optional: true, Default: false的布尔 Schema 字段data_source_agent.go并附有与文档措辞一致的描述When true, the proxy probes each agents URL and only returns agents that are reachable or have no URL.Attribute Reference数据源导出的属性完整列表文档定义 源码字段类型对照ids— Agent ID 列表[]stringTerraform 侧为 TypeList of stringagents— Agent 明细列表每条记录导出以下字段agent_id— 唯一 Agent IDstringagent_name— Agent 名称stringtpm_limit— 每分钟 Token 数上限int可选值rpm_limit— 每分钟请求数上限int可选值session_tpm_limit— 会话级每分钟 Token 数上限int可选值session_rpm_limit— 会话级每分钟请求数上限int可选值spend— 该 Agent 累计记录的花费floatcreated_at— 创建时间戳stringupdated_at— 最后更新时间戳stringcreated_by— 创建者stringupdated_by— 最后更新者string。与单实例数据源litellm_agent相比列表数据源刻意收窄了导出面agent_card_params、object_permission、extra_headers等字段不在agents列表中导出需要时请改用 litellm_agent 数据源。源码深潜数据源的读取链路端点构造与请求列表读取的核心逻辑在 dataSourceLiteLLMAgentsReadendpoint : endpointAgents if d.Get(health_check).(bool) { endpoint fmt.Sprintf(%s?health_checktrue, endpointAgents) } resp, err : MakeRequest(client, GET, endpoint, nil)其中endpointAgents /v1/agents定义于 resource_agent.go。也就是说health_check参数在 Terraform 侧不产生任何本地过滤而是原样翻译成查询串?health_checktrue交给 Proxy 执行——过滤语义完全由服务端决定。响应结构与可选字段Proxy 返回的是 JSON 数组Provider 侧用agentAPIResponse结构体resource_agent.go解码其中限流与花费字段均为指针类型*int、*float64type agentAPIResponse struct { AgentID string json:agent_id AgentName string json:agent_name TPMLimit *int json:tpm_limit RPMLimit *int json:rpm_limit SessionTPMLimit *int json:session_tpm_limit SessionRPMLimit *int json:session_rpm_limit Spend *float64 json:spend CreatedAt string json:created_at // ... }读取函数只在指针非 nil 时才把对应字段写入 Terraform statedata_source_agent.go因此未设置限流的 Agent 不会导出 0而是留空——这在写下游for表达式或告警规则时要留意。最后数据源 ID 使用纳秒时间戳生成d.SetId(strconv.FormatInt(time.Now().UnixNano(), 10))这符合 Terraform 数据源无持久身份的惯例也意味着该数据源没有状态可比对每次plan/apply都会重新读取。测试用例佐证Provider 自带单测 data_source_agent_test.go 用一个httptest假服务器精确验证了两件事health_check true时请求路径必须为GET /v1/agents且 query 串恰好是health_checktrue返回数组中的ids顺序、agents元素内的agent_name/tpm_limit/spend等字段与响应体一一对应。结合 README 中提到的 CI 机制tools/endpointaudit/会静态审计 Provider 调用的每个端点与 Proxy 生成的 OpenAPI schema 的一致性可以推断该数据源调用的/v1/agents端点是经过自动化比对、不会与 Proxy API 静默漂移的。后端原理Proxy 侧的 health_check 语义数据源最终命中的是 Proxy 的GET /v1/agents接口endpoints.py该端点带[beta] A2A Agents标签需要user_api_key_auth鉴权并按check_feature_access_for_user(..., agents)校验调用者是否具备 agents 功能权限。与health_check相关的服务端行为endpoints.py 的 Query 声明 L371-L393 的过滤实现判定标准接口文档明确写道——Agents with reachable URLs (HTTP status 500) and agents without a URL are returned; unreachable agents are filtered out. 即 URL 可达的判定是HTTP 状态码小于 5004xx 也算可达以及没有配置 URL 的 Agent 直接放行。探测范围只对有 URL 的 Agent 发起并发探测asyncio.gather调用_check_agent_url_health没有 URL 的 Agent 不探测、直接保留。超时保护整组探测被asyncio.wait_for包裹在AGENT_HEALTH_CHECK_GATHER_TIMEOUT_SECONDS超时内一旦整体超时所有带 URL 的 Agent 均被标记为不健康日志会输出 Agent health check gather timed out after ... seconds。这意味着代理侧探测基础设施抖动时健康列表会偏保守趋空使用时应理解其语义。spend 的来源列表接口会用 Prisma 客户端批量查询agents表agents_table(prisma_client).find_many(where{agent_id: {in: agent_ids}})把每个 Agent含其别名 ID的历史花费求和后写回agent.spendendpoints.py。所以数据源里的spend属性是实时从数据库聚合的值而非缓存。敏感字段脱敏返回前会执行_redact_sensitive_agent_fields非管理员角色拿到的列表中litellm_params等敏感字段始终被遮蔽这与 Terraform 数据源不导出litellm_params/static_headers的设计取向一致单实例数据源文档中也有同样的 Security Note这两个字段可能持有 API key 或 token故不通过数据源暴露。另外从源码结构看GET /v1/agents还支持query/top_k两个自然语言语义检索参数依赖litellm_settings.agent_search_embedding_model配置实现共享自 agent_search.py但当前 Terraform 数据源只映射了health_check未暴露语义检索能力——有该需求时可直接调用 HTTP API。使用建议与注意事项默认用途是清点data litellm_agents all {}适合在 Terraform 配置中作为 Agent 全集的事实来源输出 ID 列表、统计数量、生成文档等成本是一次只读 HTTP 请求health_check true是实时语义它触发 Proxy 对每个带 URL 的 Agent 的并发探测结果依赖当前网络与对方服务的瞬时状态两次plan的结果可能不同适合用于告警门禁或运行时清单不适合期望幂等快照的场景注意 4xx 也视为健康如果 Agent URL 返回 401/404按 500 的判定仍会保留在健康列表中严格的可达性验证需要自行结合litellm_agent数据源的agent_card_params或外部探活与单实例数据源分工列表数据源拿不到agent_card_params/object_permission/extra_headers需要这些字段时用data litellm_agent必传agent_id可用列表数据源的ids驱动for_each权限前提调用该端点的 key 需具备 agents 功能访问权限且通过user_api_key_auth否则 Provider 会透传代理端的鉴权错误读取函数通过handleResponse统一报错。参考文件索引数据源文档agents.md、agent.mdProvider 实现data_source_agent.go、resource_agent.go、provider.go、data_source_agent_test.go后端接口litellm/proxy/agent_endpoints/endpoints.py、litellm/proxy/agent_endpoints/agent_search.pyProvider 总览与版本策略README.md、docs/index.md【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考