用途：为手写或不支持的 AI 智能体接入 Maple 追踪。目标是每次对话对应一个 Maple Agent Session，每条用户消息一个以 invoke_agent 为根的 trace，其中每次模型调用一个 chat span、每次工具调用一个 execute_tool span。
前提判断：先确认是否使用受支持的框架（如 Mastra、LangChain、Pydantic AI、CrewAI 等），若是应改用对应 maple-agent-tracing-<framework>。已有 OTel TracerProvider 时应复用而非新建；若模型客户端已有 GenAI 自动埋点，应二选一保留，避免每次调用重复。
配置：美国端点 https://ingest.maple.dev，欧洲 https://ingest.eu.maple.dev。可用环境变量 OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <key>"、OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf。无密钥时用字面量 MAPLE_TEST 并在 Settings → Ingestion 替换。私有 maple_sk_ 密钥不得放入浏览器代码。
三个 span 的关键属性：invoke_agent（trace 根）需 gen_ai.operation.name、gen_ai.agent.name、gen_ai.conversation.id；chat 需 provider、request.model、输入/输出消息、响应 id、finish_reasons 与用量；execute_tool 需 tool.name、tool.call.id、tool.type，以及 JSON 字符串形式的 arguments 和 result。内容是 JSON 字符串属性，不读取 span 事件或索引键。
会话 id：仅在带 gen_ai.operation.name 的 span 上读取，同一对话所有消息用同一值，禁用随机 uuid、trace id 或全局常量。用量只记在 chat span 上，成本仅在 span 带 gen_ai.usage.cost 时显示。
限制与注意：不要设置属性长度上限，截断的 JSON 会被整体丢弃；历史中的 base64 文件需替换为占位符（请求超 20 MiB 返回 413）；任何属性不得含 API 密钥；脚本需 flush，容器长驻服务在 SIGTERM 时 flush。