메뉴
Analyze agentm session traces using `agentm trace` atomic commands. Use when inspecting trajectories, token economics, tool calls, or aggregating stats across a trace tree (parent + child sessions). Compose atomic commands via shell pipes — never parse OTLP JSONL directly.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | trace-analysis |
| description | Analyze agentm session traces using `agentm trace` atomic commands. Use when inspecting trajectories, token economics, tool calls, or aggregating stats across a trace tree (parent + child sessions). Compose atomic commands via shell pipes — never parse OTLP JSONL directly. |
Session traces live in two backends. agentm trace abstracts both:
| Backend | When active | Session selector |
|---|---|---|
| Local JSONL (default) | Always; files at $AGENTM_HOME/observability/<session_id>.jsonl | --file <path> or --session <id> (resolves to the JSONL) |
| ClickHouse | When AGENTM_CLICKHOUSE_URL or OTEL_EXPORTER_OTLP_ENDPOINT is set | --session <id> (queries ClickHouse automatically) |
--latest picks the most recent session file in the observability dir.
When remote trace storage is configured, --session tries ClickHouse first.
If ClickHouse has no matching session header and a local JSONL file exists,
it falls back to that file. The same subcommands and --format ndjson work
on both.
Harness operational logs (loguru) are forwarded into the OTLP logs signal
when OTEL_EXPORTER_OTLP_ENDPOINT is set. They land in the same JSONL
file interleaved with spans. Query them with agentm trace logs.
| Command | Returns |
|---|---|
index | one identity row per session: session_id, trace_id, parent_session_id, purpose, scenario |
info | session header + atom fingerprint + task_meta |
usage | aggregate token economics: turns, input_tokens, cache_read, output_tokens, total_tokens, cache_hit_rate |
turns | per-turn: turn_index, duration_ns, tool_calls, tool_call_count, input_tokens, output_tokens, cache_read, stop_reason |
tools | per-tool-call: tool, args, result, span_id, attributes |
messages | full conversation trajectory in message order |
chats | per-LLM-call with duration |
spans | generic span query (custom --name / --where / --since) |
logs | generic log query (harness operational logs) |
stats | histogram of event/span names (orientation) |
All accept --session <id> / --file <path> / --latest and --format ndjson.
agentm trace messages --latest # your own trajectory
agentm trace tools --latest --format ndjson | jq '.tool' # tool names
agentm trace tools --latest --tool bash --format ndjson # specific tool
agentm trace usage --latest # token economics
agentm trace logs --latest --format ndjson | jq '.body' # harness logs
TID=<trace_id>
# List all sessions in the trace
agentm trace index --format ndjson | jq --arg t "$TID" 'select(.trace_id==$t)'
# Aggregate usage across trace
agentm trace index --format ndjson \
| jq -r --arg t "$TID" 'select(.trace_id==$t) | .session_id' \
| while read sid; do agentm trace usage --session "$sid" --format ndjson; done \
| jq -s '{sessions: length, input: (map(.input_tokens)|add), output: (map(.output_tokens)|add)}'
# All verdicts in a verifier trace
agentm trace index --format ndjson \
| jq -r --arg t "$TID" 'select(.trace_id==$t and .purpose=="hop_worker") | .session_id' \
| while read sid; do agentm trace tools --session "$sid" --tool submit_hop_verdict --format ndjson; done \
| jq -c '.args | {verdict, predicate, rationale}'
--latest, workflow artifact child_sessions[].session_id, or indexusage --session <sid>turns --session <sid>tools --session <sid> --tool <name>logs --session <sid> — look for warnings/errorsmessages --session <sid> — only when the above don't sufficeStructured procedure to locate the root cause of a confirmed bug. Uses keyword search → focused reading → call-graph tracing. Outputs a specific file + line + hypothesis.
Step-by-step procedure to reproduce a bug. Use this FIRST before trying to fix anything. Produces a minimal script that demonstrates the failure.
AgentM SDK development guide — manifest-as-agent-unit philosophy, SDK programmatic invocation, dynamic workflow orchestration, atom contract, Operations abstraction, event system, service communication, CLI conventions, scenario authoring, logging, structured output, and config resolution. Use whenever writing, editing, or reviewing code under src/agentm/ (atoms, core, gateway), contrib/scenarios/ (manifests), or contrib/extensions/ (workspace-member atoms). Also trigger when creating new atoms, modifying MANIFEST declarations, registering tools or events, touching FileOperations / BashOperations / ResourceWriter, writing CLI subcommands, configuring model profiles, spawning child sessions, building multi-agent orchestrators, writing workflow scripts, or when a code change looks like it might bypass the SDK's existing abstractions. If you catch yourself about to write raw os.stat / open() / subprocess.run in an atom, importing openai/anthropic directly instead of going through the provider layer, or shelling
Guide for adding new benchmarks to the agentm-eval framework and running experiments through the unified `agentm eval` CLI. Covers the adapter interface, experiment lifecycle, result schema, ClickHouse linking, and output conventions. Use whenever creating a new eval adapter, modifying an existing benchmark integration, writing code under contrib/evals/src/agentm_eval/, discussing experiment management, or when the user mentions "add a benchmark", "new eval", "接入评估", "新benchmark", "实验管理", "eval adapter". Also trigger when reviewing eval-related code or debugging experiment output structure.
How to write workflow scripts that orchestrate multiple agents in AgentM. Covers agent(), parallel(), pipeline(), phase(), return values, atom_config data passing, and the journal-based resume / invalidation / partial re-run mechanism (workflow_lineage, workflow_invalidate). Trigger when writing a workflow script, choosing an orchestration pattern, recovering from a wrong node result, or when the user says 编排 / workflow / 多 agent / 并行 / 扇出 / 调度 / 写个 workflow / 失效 / 部分重跑 / 重算. Also trigger when you catch yourself building prompts inside a workflow script — pass data via atom_config instead and let the agent build its own prompt.
Analyze agentm session traces using `agentm trace` atomic commands. Use when inspecting trajectories, token economics, tool calls, or aggregating stats across a trace tree (parent + child sessions). Compose atomic commands via shell pipes — never parse OTLP JSONL directly.