AI Agent-Readable GIFs — Machine Layer Documentation

Masalahnya

Gambar GIF tidak transparan untuk agen AI. Ketika README berisi GIF demo terminal, agen AI hanya melihat data piksel biner — tidak dapat mengekstrak perintah, memahami output, atau merujuk langkah-langkah tertentu. Ini adalah keterbatasan mendasar dari dokumentasi berbasis gambar.

AgentGIF mengatasi ini dengan melampirkan data terstruktur yang dapat dibaca mesin ke setiap GIF.

Arsitektur Dua Lapis

Setiap GIF di AgentGIF memiliki dua lapisan yang hidup berdampingan di URL yang sama:

Manusia melihat terminal animasi. Agen AI melihat data terstruktur: perintah, output, cap waktu, metadata, dan kode embed.

File Cast (Asciinema v2)

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

Mengakses Cast

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

Struktur File Cast

Baris 1 adalah header JSON dengan metadata terminal:

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

Baris berikutnya adalah tuple event:

[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"]

Setiap tuple adalah [timestamp_seconds, event_type, data]:

• "o" — output event (text written to the terminal screen)
• "i" — input event (user keystrokes, if captured)
• Cap waktu dalam detik dari awal perekaman
• Data mungkin mengandung kode escape ANSI untuk warna

Mengurai File Cast

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("$ ")]

Transkrip

Untuk kasus penggunaan yang lebih sederhana, endpoint transkrip mengembalikan teks biasa yang bersih:

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

Transkrip menghapus kode escape ANSI, menciutkan spasi, dan menyajikan sesi terminal sebagai teks yang dapat dibaca. Ideal untuk:

• Penyematan dalam jendela konteks LLM (token minimal)
• Pengindeksan pencarian teks lengkap
• Menghasilkan dokumentasi dari sesi yang direkam
• Membandingkan output terminal di berbagai GIF

Endpoint .md

Setiap halaman di AgentGIF memiliki varian Markdown. Tambahkan .md ke URL mana pun:

# 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

Responsnya adalah text/markdown; charset=utf-8 — teks bersih dan terstruktur yang dapat diurai langsung oleh LLM.

API JSON

REST API menyediakan data terstruktur lengkap. Tidak perlu autentikasi untuk membaca:

# 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.

Penemuan Konten

Agen AI dapat menemukan konten AgentGIF melalui beberapa saluran:

Contoh Dunia Nyata

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