showholdings-agentmon 0.3.3

Python SDK for Show Holdings AgentOps monitoring

showholdings-agentmon

showholdings-agentmon 是 Show Holdings AgentOps 的 Python SDK。

它讓你可以在自己的 Python 程式中，用最小改動接入 run-level 與 step-level monitoring。

安裝

pip install showholdings-agentmon

最小使用範例

from showholdings_agentmon import Monitor

monitor = Monitor(
    api_key="YOUR_API_KEY",
    base_url="https://agentops.showholdings.com",
    project_name="my-agent",
)

with monitor.run(agent_name="general-agent", session_id="session-123"):
    result = run_my_agent()

auto_instrumentation v1（預設啟用）

在 v1 中，Monitor(...) 初始化後就會在 monitor.run(...) 期間自動補抓常見 steps， 你不需要額外呼叫 auto_instrument() 或新增 setup code。

目前預設自動補抓：

• OpenAI / Anthropic / Gemini 模型呼叫（llm_call）
• 模型層 tool use 事件（tool_call）
• 外部 HTTP(S) 呼叫（http_call，requests / httpx）
• 常見 DB 查詢（db_query，SQLite / SQLAlchemy 第一版）
• exception / timeout（自動標記 failed 並保留錯誤訊息）
• fallback step（執行中）：即使你只寫 monitor.run(...)，也會有基本 step 動態可視化

fallback step 行為：

• run 開始後先維持 waiting；若 1 秒內 沒有任何手動/auto step，SDK 會啟動粗粒度 fallback 執行中（processing）
• 若 run 內已有手動 step 或 auto-detected step，SDK 不會保留 fallback 造成畫面混亂
• run 失敗且沒有任何 step 時，fallback step 會以 failed 結束並帶錯誤訊息

說明：v1 是 deterministic runtime instrumentation，不包含 AI assist setup 或 function-level 自動建議插樁。

標準版（含步驟監測）

from showholdings_agentmon import Monitor

monitor = Monitor(
    api_key="YOUR_API_KEY",
    base_url="https://agentops.showholdings.com",
    project_name="my-agent"
)

with monitor.run(agent_name="填入你的 agent 名稱", session_id="填入你自訂的 session 編號"):
    # 記錄步驟 1
    with monitor.step("填入步驟 1 的名稱", step_type="例如：資料處理 / 模型呼叫 / 輸出結果"):
        result_1 = code_of_step_1()

    # 記錄步驟 2
    with monitor.step("填入步驟 2 的名稱", step_type="例如：資料處理 / 模型呼叫 / 輸出結果"):
        result_2 = code_of_step_2()

SDK 行為說明

• 進入 with monitor.run(...) 時，自動呼叫 POST /api/sdk/runs/start
• 離開 context 時，自動呼叫 POST /api/sdk/runs/end
• 進入 with monitor.step(...) 時，自動呼叫 POST /api/sdk/steps/start
• 離開 step context 時，自動呼叫 POST /api/sdk/steps/end
• auto-detected steps 也會走同一組 steps/start / steps/end API
• 成功結束會送出 status=success
• 區塊內拋出例外會送出 status=failed，並附帶：
  • failure_reason_type（例外類別名稱）
  • error_count=1
• step 區塊內拋出例外會送出 status=failed 與 error_message
• SDK 對監控 API 採 best effort；監控 API 失敗不會中斷你的主要業務流程

本地開發

pip install -e .[dev]
pytest
python -m build

發布概要

本專案已提供 GitHub Actions：

• ci.yml：在 push / pull_request 執行測試
• publish.yml：以 PyPI Trusted Publishing 為目標的正式發布流程

你可先用 TestPyPI 驗證流程，再切換到正式 PyPI 發布。