agenthog-setup

Agenthog のセットアップ

このスキルを読んでいる AI コーディングエージェントであるあなたは、ユーザーのプロジェクトに AgentHog のトレーシングをインストールして設定するよう求められています。このスキルを最後まで実行してください。 検証手順を省略してはいけません。

1. ランタイムを検出する

プロジェクトのルートを確認し、言語と主要なフレームワークを特定します。

• Python：pyproject.toml、requirements.txt、setup.py、または *.py ファイルがある場合。
• TypeScript / Node："type": "module" を含む package.json、TypeScript ファイル、または tsconfig.json がある場合。

両方に該当する場合は、主要なエントリーポイントで使用されている方を選びます。本当に判断が難しい場合は、ユーザーに確認してください。

主要なフレームワーク（FastAPI、Flask、Django、LangGraph、LangChain、Express、Vercel AI SDK、Next.js、Hono など）を特定します。フレームワークによって、init を配置する場所と、リクエストごとのループの場所が決まります。

2. 設定を収集する

ユーザーから必要な値は 2 つです。エンドポイントは自動的にデフォルト設定されるため、以下の上書き条件に該当しない限り、エンドポイントについてユーザーに尋ねてはいけません。

必須：AGENTOS_API_KEY と AGENTOS_WORKSPACE_ID

これらはシークレットであり、実行時に環境から読み込まれます。SDK は環境変数から AGENTOS_API_KEY / AGENTOS_WORKSPACE_ID を読み取ります（以下の init の例を参照）。あなたの役割は、コードがこれらの環境変数を読み取るように設定し、値が存在することを確認することです。シークレットを自分で取得、閲覧、保存してはいけません。

1. すでに環境に設定されていますか？（AGENTOS_API_KEY と AGENTOS_WORKSPACE_ID が設定済み）— 問題ありません。コードがこれらを読み取るように設定し、次に進みます。

2. 設定されていませんか？値はユーザーが設定します。あなたがシークレットを扱うことはありません。 2 つの方法を提示し、最初の方法を推奨してください。 単独の export はシェルごとの設定であり、ターミナルを閉じると失われます。これは「一度トレースされた後、止まった」というよくある原因であり、他のシェル（あなた自身のツール用シェルを含む）からは参照できません。

   • 推奨 — agenthog init（agenthog >= 0.5.0）：両方の値を求め、Git で無視される .env（0600）に書き込み、再起動後もシェルをまたいでも保持します。ユーザーが実行してキーを入力します。あなたは入力しません。.env に書き込まれるため、新しいターミナルを開いても値が残り、シェル間の不一致が起きません。

   • 代替 — シェルの export（一時的な設定で、手早く一度だけ実行する場合に適しています）：アプリを実行するターミナルで、ユーザーが値を設定します。

     export AGENTOS_API_KEY=<their key>
     export AGENTOS_WORKSPACE_ID=<their workspace id>
     

     クイックスタートページには、そのまま貼り付けて使える export ブロックがあります。この設定はそのシェルセッションでのみ有効です。設定を永続化する場合は agenthog init を推奨してください。

   値は https://app.theagentos.space から取得できます（API キー：Settings → API Keys、ワークスペース ID：サイドバーのチップ／右上）。ユーザーがどちらかの方法を実行したら、以下のとおり環境変数名で存在を確認してから、次に進みます。

シークレットを一切読み取らずに存在を確認する：

変数が設定されているかだけを確認し、値は確認しないでください。ブール値による存在確認のみとし、cat .env を実行したり、キーをコンテキストに出力したりしてはいけません。

# prints only yes/no; resolves env first, then a gitignored .env the app loads
python3 -c "import os; print('AGENTOS_API_KEY set:', bool(os.getenv('AGENTOS_API_KEY')))"

False と表示された場合、ユーザーはまだ agenthog init / export を完了していません。値を探そうとせず、ユーザーに完了するよう依頼してください。

認証情報の安全な取り扱い（逸脱禁止）：

• チャットに貼り付けられた API キーを受け取ってはいけません。 ユーザーが貼り付けを申し出た場合は断り、代わりに agenthog init を実行する（または export で設定する）よう伝えてください。AGENTOS_API_KEY は名前でのみ参照し、値を扱ってはいけません。
• キーを探すためにファイルシステムを検索したり、ファイルを読んだりしてはいけません。 シークレットを読むために .env を開いてもいけません。上記のとおり、環境変数名だけで存在を確認してください。
• キーをソースコードにハードコードしてはいけません。また、表示したり出力したりしてもいけません。 コードでは環境変数を通じて AGENTOS_API_KEY を参照し、値を直接記述してはいけません。
• エージェントが平文のシークレットをディスクに書き込むことはありません。 agenthog init（ユーザー自身がキーを入力）またはユーザーが書き込みます。ステップ 6 でプレースホルダーを使った .env.example を作成または更新しても構いませんが、実際の値をあなたが扱うことはありません。

エンドポイント：デフォルトを使い、確認しない

ユーザーに確認せず、AGENTOS_ENDPOINT を次の順序で解決します。

1. 環境に AGENTOS_ENDPOINT がすでに設定されている場合は、それを使います。
2. それ以外の場合は、デフォルトの https://api.theagentos.space を使います。

エンドポイントについてユーザーに確認するのは、エンドポイントを変更したいという明確な証拠がある場合に限ります。たとえば、リクエストで「セルフホストしています」や「agenthog を自社のインフラで実行しています」のように述べている場合です。

それ以外の場合は、デフォルトを選んで次に進みます。クイックスタートのたびにエンドポイントを尋ねるのは、ホステッドクラウドを使う 95% のユーザーにとって煩わしい手間になります。

平文の API キーを絶対にコミットしないでください。また、自分でディスクに書き込まないでください。実際の値はユーザーが設定します（ステップ 6 でコードと .env.example のプレースホルダーを接続します）。

3. SDK をインストールする（十分に新しいバージョンが必須）

サポート対象の最小バージョン：Python agenthog >= 0.9.0、TypeScript agenthog >= 0.3.0。 取り込み API は、古い SDK からのイベントを 拒否します（HTTP 426）。Python の下限を 0.9.0 とするのは、このスキルが エンドツーエンドでその機能に依存するためです。具体的には、agenthog init の認証情報 （0.5.0）、OpenAI 互換エンドポイント向けの生 HTTP による LLM キャプチャと終了時の 自動フラッシュ（0.6.0）、エージェントのツールをトレースするための @agenthog.tool / @traceable デコレーター （0.7.0）、そして 1 回の呼び出しでツールをキャプチャする instrument_module（ステップ 5b、0.9.0） です。 これにより、ツールが気づかれないまま取りこぼされることがなくなります。下限より古いバージョンでは、 セットアップによって不完全なトレースが生成されます（ツールのステップが欠けたり、短時間で終了する プロセスではステップが一切記録されなかったりします）。

セットアップの一環として、プロジェクトですでに使っているパッケージマネージャー（依存関係の管理に 使っているものと同じもの）を使い、agenthog をインストール（またはアップグレード）します。 追加するものをユーザーに伝え、既存の古いインストールをそのまま残さず更新できるよう、下限バージョンを 指定してください。パッケージマネージャーを特定できない場合は、インストール前に確認してください。

Python

パッケージマネージャー（uv、poetry、pip、pipenv）を検出し、バージョンの下限を指定して アップグレードしながらインストールします。

# uv  (uv add always resolves to the newest allowed; the floor guarantees ≥0.9.0)
uv add 'agenthog>=0.9.0'

# poetry
poetry add 'agenthog@>=0.9.0'

# pip  (-U upgrades an already-installed older copy)
pip install -U 'agenthog>=0.9.0'

ファーストクラスの自動インストルメンテーションに対応したフレームワークでは、追加機能をインストールします。

# OpenAI calls
uv add 'agenthog[openai]>=0.9.0'

# Anthropic
uv add 'agenthog[anthropic]>=0.9.0'

# LangChain / LangGraph
uv add 'agenthog[langchain]>=0.9.0'

# OpenTelemetry passthrough
uv add 'agenthog[otel]>=0.9.0'

TypeScript

# pnpm (preferred)
pnpm add agenthog@latest

# npm
npm install agenthog@latest

# yarn
yarn add agenthog@latest

# bun
bun add agenthog@latest

TS の自動インストルメンテーションはインテグレーションのインポートを通じて設定されるため、インストール時に追加機能は不要です。 reference/typescript.md を参照してください。

インストールしたバージョンが下限を満たしていることを確認する（省略しない）

インストール後、バージョンを確認します（Python >= 0.9.0、TypeScript >= 0.3.0）。 満たしていない場合は、続行する前にアップグレードして再確認します。以降のセットアップと 取り込み API は、このバージョンを前提としています。

# Python — prints the installed version; exits non-zero if below the floor.
python -c "import agenthog, sys; from importlib.metadata import version; \
v=version('agenthog'); print('agenthog', v); \
sys.exit(0 if tuple(map(int, v.split('.')[:2])) >= (0,9) else 1)"

# TypeScript — same idea.
node -e "const v=require('agenthog/package.json').version; const [a,b]=v.split('.').map(Number); \
console.log('agenthog', v); process.exit((a>0||b>=3)?0:1)"

確認結果が下限（Python 0.9.0、TypeScript 0.3.0）を下回る場合は、インストール時と同じ方法で （パッケージマネージャーを使って agenthog をアップグレードし）、確認を再実行します。下限を 満たせないままの場合（たとえば、レジストリにまだ公開されていない場合）は、サポート対象外の バージョンのまま進めず、停止してユーザーに伝えてください。テレメトリが取り込み時に拒否されたり、 トレースからツールのステップが欠落したりします。

4. アプリの起動時に init を設定する

トレース対象とする LLM／ツールの呼び出しより前に、init を一度だけ実行する必要があります。 アプリのメインエントリーポイントに配置します。

フレームワーク	init の呼び出し場所
FastAPI	app = FastAPI() より前の main.py
Flask	app = Flask(__name__) より前の app.py
Django	settings.py の末尾、または apps.py の ready() フック
LangGraph スクリプト	グラフを構築する前のスクリプトの先頭
Express	app.listen より前の index.ts／server.ts
Next.js	instrumentation.ts（Next.js 公式の OTel／トレーシングフック）
Vercel AI SDK	AI クライアントを構築する箇所

Python の初期化パターン

import os
import agenthog

agenthog.init(
    api_key=os.environ["AGENTOS_API_KEY"],
    endpoint=os.environ.get("AGENTOS_ENDPOINT", "https://api.theagentos.space"),
    workspace_id=os.environ["AGENTOS_WORKSPACE_ID"],
    agent_id="<descriptive-agent-name>",  # pick based on what this service is
)

# Auto-instrument supported LLM / framework libraries. Detects installed
# packages (openai, anthropic, langchain) and patches them. As of
# agenthog >= 0.6.0 it ALSO captures raw-HTTP calls to OpenAI-compatible
# /chat/completions endpoints made via `requests` or `httpx` — so agents that
# POST directly to NVIDIA, Together, Groq, OpenRouter, a local vLLM/Ollama,
# etc. (instead of through a vendor SDK) get traced with no code change.
agenthog.autoinstrument()

プロバイダーの対応範囲。 autoinstrument()（>= 0.6.0）は、ベンダー SDK と、生の HTTP による OpenAI 互換の呼び出しの 両方 をカバーします。エージェントが、どちらの方法でも認識されない カスタムまたは OpenAI 形式ではない エンドポイントと通信する場合、LLM 呼び出しは自動で記録されません。その場合は、agenthog.emit("agent.llm_call", {...}) で明示的にログを記録してください（ツールの場合は Step 5b の log_tool_call）。検証（Step 7）では、トレースに空の task_run だけでなく、LLM のステップが実際に表示されていることを確認してください。

agenthog >= 0.6.0 では、終了時のフラッシュは自動で行われます。init() は atexit と SIGTERM のドレインを登録するため、短時間で終了する CLI やスクリプトでも、手動で flush() を呼び出さずにバッファーが送信されます。これを回避するのは強制終了（SIGKILL、os._exit）だけです。そのような終了方法を使う場合は、終了前に agenthog.shutdown() を呼び出してください。

TypeScript の初期化パターン

import { init } from "agenthog";

init({
  apiKey: process.env.AGENTOS_API_KEY!,
  endpoint: process.env.AGENTOS_ENDPOINT ?? "https://api.theagentos.space",
  workspaceId: process.env.AGENTOS_WORKSPACE_ID!,
  agentId: "<descriptive-agent-name>",
});

// Auto-instrumentation is per-integration in TS. Import the wrapper for the
// LLM client you use. Examples:
//   import "agenthog/integrations/openai";
//   import "agenthog/integrations/anthropic";
//   import "agenthog/integrations/vercelAI";
//   import "agenthog/integrations/langchain";

リポジトリ名だけではなく、サービスの機能を説明する agentId を選んでください。例：customer-support-bot、code-review-agent、etl-pipeline。

5. エージェントのメインループを start_task_run でラップする

1 つの task_run は、エージェントのエンドツーエンドの実行 1 回分です（ユーザーメッセージ 1 件 → 最終応答 1 件、または cron のトリガー 1 回 → ジョブ 1 件の完了）。スパンはその内側にネストされます。

Python — コンテキストマネージャー

with agenthog.start_task_run(user_id=user_id) as ctx:
    # Auto-instrumented LLM calls in here are traced under one task_run_id.
    # Tool calls are NOT auto-traced unless they go through a framework
    # (LangChain/LangGraph) — see Step 5b for hand-written tool loops.
    result = my_agent.run(user_input)
    return result

使用可能なキーワード引数：agent_id、task_run_id、trace_id、user_id、session_id。metadata= キーワード引数は ありません。代わりに、上記の明示的なキーワード引数でアトリビューション情報を付与してください。

HTTP ハンドラー（FastAPI／Flask）の場合は、ハンドラーの本体をラップします。

@app.post("/chat")
async def chat(req: ChatRequest):
    with agenthog.start_task_run(user_id=req.user_id):
        return await my_agent.run(req.message)

TypeScript — コールバック

import { startTaskRun } from "agenthog";

app.post("/chat", async (req, res) => {
  await startTaskRun({ userId: req.body.userId }, async () => {
    const out = await myAgent.run(req.body.message);
    res.json(out);
  });
});

使用可能な StartTaskRunArgs のフィールド：agentId、taskRunId、traceId、userId、sessionId。metadata フィールドはありません。

ユーザーのフレームワークにミドルウェアの仕組み（Express、Hono、FastAPI のミドルウェア）がある場合は、各リクエストで task_run が自動的に取得されるよう、start_task_run をミドルウェアとして組み込むことを推奨します。

5b. エージェントのツールを計装する（実行ツリー全体）

autoinstrument() は LLM 呼び出し（ベンダー SDK と、生の HTTP による OpenAI 互換の呼び出し）を取得しますが、エージェントの ツール は取得しません。ツールとは、API の呼び出し、DB のクエリ、ジオコーディング、計算の実行などを行う通常の関数です。何もしなければ、トレースには LLM のステップしか表示されず、ツールの使用状況を確認する評価で「エージェントはツールを使っていない／幻覚を起こした」と誤って報告されます。これはどのトレーサーでも同じ境界です。Arize／LangSmith は、計装されたフレームワーク上でのみツリー全体を自動トレースし、手書きのツールには同様にアノテーションが必要です。

このステップで、モデルのステップだけではなく、ワークフロー全体のツリー（ツール呼び出し + LLM 呼び出し）が生成されます。エージェントにツール／ヘルパー関数がある場合は、必ず実行してください。

推奨 — ツールのモジュールに対する 1 回の呼び出し（Python、agenthog >= 0.9.0）

エージェントのツール関数を格納しているモジュールを instrument_module に指定します。1 回の呼び出しで、そのモジュール内に定義されている すべてのパブリック関数 を agent.tool_call ステップとしてラップします。これにより、関数ごとのデコレーターでは起こり得る、ツールが気付かれないまま漏れる事態を防げます。ラップされた名前の一覧が 返される ので、Step 7 の件数確認用にその一覧を保持してください。

import agenthog
import weather            # the module with the agent's tool functions

agenthog.init(...)
wrapped = agenthog.instrument_module(weather)
# wrapped == ['get_weather', 'get_air_quality', 'geocode']

プライベートヘルパー（先頭に _ が付くもの）、インポートされた名前、クラス、定数はスキップされます。デフォルトの選択方法が合わない場合は、選択を調整してください。

• ツールではないパブリック関数：instrument_module(weather, exclude=["build_prompt"])。
• 先頭に _ が付いたツール、またはインポートされた名前に紛れているツール：instrument_module(weather, include=["_geocode"])。

すでに @agenthog.tool でデコレートされている関数は検出され、二重にラップされません。エージェントのツールモジュールをすべて列挙し、それぞれに対して instrument_module を 1 回呼び出してください。これにより、「すべてのツールが取得される」ことを、適用し忘れる可能性のある関数ごとの判断ではなく、構造的に保証できます。

ツールが多くのファイルに分散している場合、または関数ごとに制御したい場合 — 各関数にデコレーターを付ける

エージェントがツールとして使用する各関数に @agenthog.tool を追加します。各関数に1行ずつ追加するだけで、引数は tool.input に、戻り値は tool.output に記録され、実行時間／ステータス／エラーも、アクティブな task_run 配下の agent.tool_call ステップとして記録されます。同期関数と非同期関数の両方で動作し、init() の前から追加しておいても安全です。すべてのツールにデコレーターを付けてください。付け忘れたツールはトレースに表示されません（これを防ぐのが instrument_module です）。

import agenthog

@agenthog.tool
def get_weather(city: str) -> dict | None:
    ...

@agenthog.tool(name="geocode")          # custom step name
def _geocode(city: str) -> tuple[float, float] | None:
    ...

TypeScript には、まだ @tool デコレーターも instrument_module もありません（JS SDK は 0.6.0 より前のバージョンです。一括キャプチャ、デコレーター、raw HTTP キャプチャ、終了時の自動フラッシュは、現時点では Python のみで利用できます）。Node/TS エージェントでは、下記の「代替方法」セクションにある明示的な logToolCall の方法でツールを計測してください。また、JS SDK が追いつくまでは、自動キャプチャに関するその他の機能も Python より限定的であることに留意してください。

ツール関数を特定します。通常は、エントリーポイントが LLM 呼び出しの前後に呼び出すヘルパー関数（データ取得、検索、アクション）です。どちらの方法でも、次のような複数ステップのトレースが生成されます。 task_run → get_weather → geocode → get_air_quality → llm_call

代替方法 — 明示的にログを記録する（古い SDK、または生のツール呼び出しループの場合）

デコレーターを使用できない場合（モデルのツール呼び出しループでツールが動的にディスパッチされる場合や、instrument_module も @tool もない TS SDK を使用する場合など）は、各呼び出しをログに記録します。

result = run_tool(name, **args)
agenthog.get_default_client().log_tool_call(name=name, input=args, output=result)

const result = await runTool(name, args);
await getDefaultClient()!.logToolCall({ name, input: args, output: result });

log_tool_call / logToolCall には name と、任意の input、output、status、duration_ms、error を指定します。すべてのツールがすでに自動計測されるフレームワークを経由している場合に限り、ツールの計測を省略してください。

6. 設定を記載する（プレースホルダーのみ — 実際のキーは決して記載しない）

.env.example にプレースホルダーを3行追加します（ファイルがない場合は作成します）。このファイルはコミットされるため、実際のキーを含めてはいけません。

AGENTOS_API_KEY=agops_replace_me
AGENTOS_WORKSPACE_ID=ws_replace_me
AGENTOS_ENDPOINT=https://api.theagentos.space

実際の値については、次のようにします。

• Python（ステップ2で agenthog init を使用した場合）： git の追跡対象外である .env はすでに書き込まれ、追跡対象外になっています。ここで追加ですることはありません。チームメイト向けに、上記の .env.example のプレースホルダーをコミットするだけです。
• **それ以外の場合：**実際の値はユーザー自身が設定するよう伝えてください。シェル環境、シークレットマネージャー、または git の追跡対象外である .env に設定します。ユーザーに代わって、平文のキーをファイルに書き込んではいけません。.env を使用する場合は、シークレットがコミットされないよう、.gitignore に記載されていることを確認してください（記載がなければ追加します）。

.env を実際に読み込ませる（省略しないでください）

.env ファイルだけでは、os.environ / process.env に値は設定されません。SDK は実行時（ステップ4）に環境変数からキーを読み取るため、アプリが .env を読み込まないと、ユーザーがすべて正しく設定していても、キーが空または見つからず、トレースが表示されません。実行環境に合った読み込み処理を組み込みます。

実行環境	.env を環境変数に反映する方法
Next.js	自動で読み込まれます — Next.js が .env / .env.local を読み込みます。追加作業はありません。
Node（Next.js 以外）	node --env-file=.env … で実行する（Node 20 以降）か、最初の import として import "dotenv/config"; を追加します。
Python — FastAPI / Flask / スクリプト	agenthog.init(...) より前に from dotenv import load_dotenv; load_dotenv() を追加する（python-dotenv 依存関係を追加）、pydantic-settings を使用する、または uv run --env-file .env … で実行します。
すべての実行環境	または、起動前にシェルでエクスポートします：export AGENTOS_API_KEY=… AGENTOS_WORKSPACE_ID=…。

プロジェクトに合った方法を選んでください。load_dotenv() を追加する場合は、エントリーポイントの先頭に置き、init の実行前に呼び出されるようにします。完了を宣言する前に、変数が実際に設定されていることを確認してください（ステップ7の「AGENTOS_API_KEY が読み込まれていることを確認する」チェック）。

7. 検証する（必須ゲート — 省略したり、確認済みと見なしたりしないでください）

この手順は必須であり、完了の条件です。 実際の実行から得られた本物のトレースを確認するまでは、セットアップは完了していません。init と start_task_run を連携させただけでは、トレースは生成されません。LLM／ツール呼び出しが記録されなければ、空の task_run になるだけで、有用な情報は何も表示されません。コードが「連携されているように見える」という理由だけで、成功を報告してはいけません。トレースを確認した場合にのみ成功と報告してください。

トレースが存在するだけでなく、完全であることも確認してください。 LLM 呼び出しと、エージェントが使用した各ツールに対する tool_call ステップ（手順 5b）の両方が含まれている必要があります。数を確認してください。 個別の tool_call ステップの数は、計測したツールの数、つまり instrument_module が返したリストの長さ、または @agenthog.tool でデコレートした関数の数と一致する必要があります。数が少ない場合は、ツールが計測されていないか（または実行パスで呼び出されていません）。llm_call だけでツールのステップがないトレースは、ツールがまったく計測されていないということです。手順 5b に戻ってください。数が一致しない場合は、このゲートを通過したことにしてはいけません。目指すのは、Arize／LangSmith に表示されるような実行ツリー全体です。

アプリを実行してください。ラップしたハンドラーを通るリクエストを 1 つ実行してください。その後、簡単な順に次のいずれか1 つの方法で確認します。

方法 A — ダッシュボード（常に利用可能）

ブラウザーで次を開きます。

https://app.theagentos.space/traces

必要であればサインインしてください。実行したリクエストのトレースが、数秒以内に表示されるはずです。デフォルトではこの方法を使用してください。

方法 B — CLI 検証ツール（オフライン、暗号学的）

agenthog CLI はインストール済みのエントリーポイントとして提供されており、python -m agenthog として実行するものではありません。__main__.py はありません。エントリーポイントを直接呼び出してください。

# If agenthog[audit] is installed in the active env:
agenthog audit verify --workspace-id $AGENTOS_WORKSPACE_ID

# Or, ephemerally without modifying the project's deps:
uvx --with 'agenthog[audit]' agenthog audit verify --workspace-id $AGENTOS_WORKSPACE_ID

# Or, with uv run from outside any project (mirrors `uv run --no-project`):
uv run --no-project --with 'agenthog[audit]' agenthog audit verify \
    --workspace-id $AGENTOS_WORKSPACE_ID

python -m agenthog audit verify は実行しないでください。'agenthog' is a package and cannot be directly executed というエラーで失敗します。CLI はモジュールランナーではなく、agenthog コンソールスクリプトのエントリーポイントから呼び出します。

注：agenthog audit verify には [audit] エクストラが必要です（Ed25519 検証用に cryptography がインストールされます）。トレース用に agenthog[openai] だけをインストールした場合は、検証用に [audit] を追加するか、方法 A を使用してください。

30 秒経ってもトレースが表示されない場合

1. アプリの標準出力に [agenthog.sdk] の警告行がないか確認してください。
2. AGENTOS_API_KEY が読み込まれていること（空でないこと、プレースホルダーでないこと）を確認してください。
3. エンドポイントに接続できることを確認してください。curl -I $AGENTOS_ENDPOINT
4. ハンドラーの実行前に、アプリが実際に init を呼び出していることを確認してください（ハンドラーのインポート後に init が設定されている場合があります。モジュールの読み込み時に init が最初に実行されるよう、インポート順を修正してください）。
5. トレースは表示されるものの、中身が空（LLM ステップなし）の場合： モデル呼び出しが記録されていません。autoinstrument() はベンダー SDK と、agenthog >= 0.6.0 では生の HTTP による OpenAI 互換の /chat/completions 呼び出しを計測します。カスタム／OpenAI 形式ではないエンドポイントは自動でトレースされません。agenthog.emit("agent.llm_call", {...}) で記録してください。（古い SDK では、生の requests／httpx 呼び出しは記録されません。>= 0.6.0 にアップグレードするか、カスタムの base_url を指定した OpenAI SDK に切り替えてください。）
6. 実行時間の短いスクリプトで、何も届かない場合： agenthog >= 0.6.0 では終了時にバッファーが自動でフラッシュされます。古いバージョンでは、プロセスの終了前に agenthog.flush() を追加するか、アップグレードしてください。

8. 結果を報告する

トレースが表示されることを確認したら、ユーザーに次の内容を伝えてください。

• インストールしたもの（どのエクストラか）
• init 呼び出しを配置した場所（ファイルと行番号）
• ループをラップした場所（ファイルと行番号）
• 検証トレースの trace_id（ユーザーが直接開けるように）

ルール

• 例外をスローしないでください。 AgentHog の設定に誤りがあっても、ユーザーのエージェントは実行を続ける必要があります。SDK は呼び出し自体が例外を発生させないことを保証しているため、コードの組み込みもその契約に従ってください。
• 認証情報は環境内に置いてください。 API キーは実行時に環境変数から読み込みます。ハードコードしたり、表示または出力したり、平文の値をファイルに書き込んだり、ファイルシステムをスキャンして探したりしないでください。コードで環境変数を参照し、ユーザー自身にシークレットを設定してもらいます（ステップ 2）。
• シークレットを自動で計測しないでください。 ユーザーのプロンプトに PII や API キーが含まれている場合は、レポートでプライバシー制御（capture_content=False）について説明してください。デフォルト設定を黙って変更しないでください。
• 関係のないコードをリファクタリングしないでください。 トレース機能の組み込みに必要な箇所だけを変更してください。ユーザーがより広範な可観測性の作業を希望する場合は、明示的に依頼してもらってください。
• すでにプロジェクトで uv を使っている場合は、uv を使用してください。 それ以外の場合は、プロジェクトで使われているパッケージマネージャーを使用してください。新しいものを導入しないでください。