agentinsight-sdk-python AGENTS.md

Development instructions for a Python SDK that sends AI-agent tracing data through OpenTelemetry. Tracing records the steps of a program so they can be inspected later.

In plain words
What is it for?
Use it when developing, testing, documenting, building, or publishing the AgentInsight Python package and its integrations.
Why use it?
It sets the required tools, coding rules, tests, project isolation, retry behaviour, and release process for safe SDK changes.

Instructions file for CodexOpenCode

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add instructions/agentinsight/agentinsight-sdk-python/agents-md
Clone the repo
git clone --depth 1 https://github.com/AgentInsight/agentinsight-sdk-python

Made for: Codex, OpenCode.

Per session 6,332 This file is loaded in full into every session.
When invoked 6,332 The same file — it is already loaded in full.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.06332 $0.06332
Opus 5 $0.03166 $0.03166
Sonnet 5 $0.01266 $0.01266
Haiku 4.5 $0.00633 $0.00633

Measured yesterday against content hash f5de99795651, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

agentinsight-sdk-python AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

AGENTS.md · 442 lines

How it starts

The opening of the file, as written. The whole thing — 442 lines — stays where its author put it; the contents beside it link to each section on GitHub.

AgentInsight Python SDK — 智能体执行规则

本文档是AI智能体(AI Agent)执行本项目开发任务的规则依据。智能体在执行任何任务前,必须先完整阅读本文档,并严格按照本文档定义的规则执行。


1. 项目基本信息

1.1 技术栈

类别 技术选型
语言/框架 Python >= 3.10, < 4.0
包管理 uv 0.11.2(锁定依赖 + 构建后端)
类型检查 mypy >= 1.0(严格模式,disallow_untyped_defs = true
代码风格 ruff >= 0.15.2(Google docstring 约定)
HTTP 客户端 httpx >= 0.15.4
数据模型 Pydantic >= 2
可观测性 OpenTelemetry API + SDK >= 1.33.1(TracerProvider + OTLP HTTP Exporter)
API 客户端 Fern 自动生成(agentinsight/api/,不可手改)
测试 pytest >= 7.4 + pytest-xdist + pytest-asyncio + pytest-httpserver
重试/退避 backoff + tenacity
猴子补丁 wrapt(OpenAI 集成)
构建 uv build --no-sources
文档 pdoc >= 15.0.4(Google 格式)
部署 PyPI 发布(GitHub Actions 自动触发)

1.2 项目关键特征

  • OpenTelemetry 原生:SDK 完全构建在 OpenTelemetry 标准之上,不作私有 tracing 协议。Span 通过 OTLPSpanExporter 发送到 AgentInsight OTLP 端点。
  • 单例资源管理AgentInsightResourceManagerpublic_key 管理单例,每个 API key 维护独立的 TracerProviderAgentInsightSpanProcessor 和后台线程。
  • 多项目安全隔离:通过 ContextVar 实现多项目场景下的客户端隔离,防止 trace 数据跨项目泄漏。
  • 三级集成方式:直接 SDK(AgentInsight 客户端)、@observe 装饰器、OpenAI 直插替换(agentinsight.openai)、LangChain 回调处理器。
  • 后台任务线程MediaUploadConsumer(媒体上传)+ ScoreIngestionConsumer(评分摄入),通过 sentinel 对象实现优雅关闭。
  • 自动生成 API 客户端agentinsight/api/ 由 Fern 根据 OpenAPI 规范自动生成,覆盖 ingestion、prompts、datasets、scores、media 等全部端点。

1.3 项目目录结构

目录 说明
agentinsight/__init__.py 公共 API 入口,__all__ 导出全部公开符号
agentinsight/_client/ 核心 SDK:客户端、装饰器、资源管理器、Span 处理器、Span 过滤器、属性传播、数据集
agentinsight/_task_manager/ 后台消费者:媒体上传队列与管理、评分摄入
agentinsight/_utils/ 内部工具:HTTP 客户端、序列化器、提示缓存、错误日志、环境变量
agentinsight/api/ Fern 自动生成的 API 客户端,禁止手改
agentinsight/openai.py OpenAI SDK 直插式集成(wrapt 猴子补丁)
agentinsight/langchain/ LangChain 回调处理器集成
tests/unit/ 单元测试:不需要 AgentInsight 服务器,使用 InMemorySpanExporter
tests/e2e/ 端到端测试:需要真实 AgentInsight 服务器,使用带轮询重试的 API wrapper
tests/live_provider/ 供应商测试:需要真实 OpenAI/LangChain API 调用
tests/support/ e2e 共享辅助工具(API wrapper、重试、轮询)
scripts/select_e2e_shard.py CI 分片选择器:历史权重 + 贪心装箱算法
scripts/codex/ Codex 云/工作树引导和共享快速检查

Read the full file on GitHub · 442 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. yesterday First seen · 442 lines · 6,332 tokens per session scan A f5de99795651

Subscribe to this mod's changes

agentinsight-sdk-python AGENTS.md is an instructions file published in the GitHub repository AgentInsight/agentinsight-sdk-python (10 stars, last pushed 1mo ago), licensed MIT. It adds 6,332 tokens to every session, about $0.0317 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.