AI Agent-Readable GIFs — Machine Layer Documentation

問題

GIF 画像は AI エージェントにとって不透明です。README にターミナルデモ GIF が含まれている場合、AI エージェントはバイナリのピクセルデータしか見えません — コマンドを抽出したり、出力を理解したり、特定のステップを参照したりすることができません。これは画像ベースのドキュメントの根本的な制限です。

AgentGIF はすべての GIF に構造化された機械可読データを添付することでこれを解決します。

デュアルレイヤーアーキテクチャ

AgentGIF のすべての GIF には、同じ URL に共存する 2 つのレイヤーがあります:

人間にはアニメーションのターミナルが表示されます。AI エージェントには構造化データが見えます: コマンド、出力、タイムスタンプ、メタデータ、埋め込みコード。

キャストファイル (Asciinema v2)

The cast file is the richest data source. It's an asciinema v2 recording with precise timestamps for every terminal event.

キャストへのアクセス

curl -s https://agentgif.com/api/v1/gifs/{id}/cast/

キャストファイル構造

1 行目はターミナルメタデータを含む JSON ヘッダーです:

{"version": 2, "width": 120, "height": 40, "timestamp": 1710000000, "env": {"SHELL": "/bin/zsh", "TERM": "xterm-256color"}}

後続の行はイベントタプルです:

[0.0, "o", "$ "]
[0.5, "o", "docker compose up -d\r\n"]
[1.2, "o", "\u001b[32mCreating network...\u001b[0m\r\n"]
[2.8, "o", "Container app-1  Started\r\n"]

各タプルは [timestamp_seconds, event_type, data] です:

• "o" — output event (text written to the terminal screen)
• "i" — input event (user keystrokes, if captured)
• タイムスタンプは録画開始からの秒数です
• データには色のための ANSI エスケープコードが含まれる場合があります

キャストファイルの解析

import json

# Read cast file
lines = cast_data.strip().split("\n")
header = json.loads(lines[0])
events = [json.loads(line) for line in lines[1:]]

# Extract all output text
output = "".join(data for ts, typ, data in events if typ == "o")

# Find commands (lines starting with $ or % prompt)
commands = [line for line in output.split("\n") if line.startswith("$ ")]

トランスクリプト

より簡単なユースケースでは、トランスクリプトエンドポイントがクリーンなプレーンテキストを返します:

curl -s https://agentgif.com/api/v1/gifs/{id}/transcript/

トランスクリプトは ANSI エスケープコードを削除し、空白を整理し、ターミナルセッションを読みやすいテキストとして提示します。以下に最適です:

• LLM コンテキストウィンドウへの埋め込み (最小トークン)
• 全文検索インデックス作成
• 録画されたセッションからドキュメントを生成
• 複数の GIF 間でターミナル出力を比較

.md エンドポイント

AgentGIF のすべてのページに Markdown バリアントがあります。任意の URL に .md を追加:

# GIF detail → structured summary
curl https://agentgif.com/@agentgif/docker-compose/.md

# Tag listing → all GIFs with this tag
curl https://agentgif.com/explore/tags/docker/.md

# Tool page → all GIFs for this CLI tool
curl https://agentgif.com/tools/git/.md

# Collection → ordered GIF list
curl https://agentgif.com/@agentgif/collections/devops-essentials/.md

レスポンスは text/markdown; charset=utf-8 — LLM が直接解析できるクリーンで構造化されたテキストです。

JSON API

REST API は完全な構造化データを提供します。読み取りには認証不要:

# Search for GIFs about a topic
curl -s "https://agentgif.com/api/v1/search/?q=kubernetes" | jq '.results[:3] | .[].title'

# Get full metadata for a specific GIF
curl -s "https://agentgif.com/api/v1/gifs/{id}/" | jq '{title, command, tags, gif_url}'

# Browse by tag
curl -s "https://agentgif.com/api/v1/tags/docker/gifs/" | jq '.count'

See the complete API Reference for all 30+ endpoints.

コンテンツ発見

AI エージェントは複数のチャネルを通じて AgentGIF コンテンツを発見できます:

実際の例

Agent: "Find a Docker demo and explain the steps"

# 1. Search for Docker GIFs
curl -s "https://agentgif.com/api/v1/search/?q=docker+compose" | jq '.results[0].id'
# → "xK9mQ2pL"

# 2. Get the transcript
curl -s "https://agentgif.com/api/v1/gifs/xK9mQ2pL/transcript/"
# → $ docker compose up -d
#   Creating network...
#   Container app-1  Started

# 3. Agent can now explain: "The demo shows docker compose up -d,
#    which starts services in detached mode..."

Agent: "Add a demo GIF to a README"

# 1. Search for the right tool
curl -s "https://agentgif.com/api/v1/search/?q=ripgrep" | jq '.results[0] | {id, gif_url, title}'

# 2. Generate embed code
# → [![ripgrep demo](https://media.agentgif.com/ID.gif)](https://agentgif.com/ID)

Agent: "Compare two terminal tools"

# Get GIFs for both tools
curl -s "https://agentgif.com/api/v1/tags/grep/gifs/" | jq '.results[].command'
curl -s "https://agentgif.com/api/v1/tags/ripgrep/gifs/" | jq '.results[].command'

# Compare the transcripts to understand different syntax