AI Agent-Readable GIFs — Machine Layer Documentation

Sorun

GIF görüntüleri yapay zeka ajanlarına opaktır. Bir README terminal demo GIF'i içerdiğinde, yapay zeka ajanı ikili piksel verisi görür — komutları çıkaramaz, çıktıyı anlayamaz veya belirli adımlara başvuramaz. Bu, görüntü tabanlı dokümantasyonun temel bir sınırlamasıdır.

AgentGIF, her GIF'e yapılandırılmış, makine tarafından okunabilir veri ekleyerek bunu çözer.

Çift Katmanlı Mimari

AgentGIF'teki her GIF'in aynı URL'de bir arada bulunan iki katmanı vardır:

Bir insan animasyonlu bir terminal görür. Bir yapay zeka ajanı yapılandırılmış veri görür: komutlar, çıktı, zaman damgaları, meta veri ve gömme kodları.

Cast Dosyaları (Asciinema v2)

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

Cast'e Erişim

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

Cast Dosya Yapısı

Satır 1, terminal meta verileri içeren bir JSON başlığıdır:

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

Sonraki satırlar olay demetleridir:

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

Her demet [timestamp_seconds, event_type, data] şeklindedir:

• "o" — output event (text written to the terminal screen)
• "i" — input event (user keystrokes, if captured)
• Zaman damgaları kayıt başlangıcından itibaren saniye cinsindendir
• Veri, renkler için ANSI kaçış kodları içerebilir

Bir Cast Dosyasını Ayrıştırma

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

Dökümler

Daha basit kullanım senaryoları için döküm endpoint'i temiz düz metin döndürür:

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

Dökümler ANSI kaçış kodlarını temizler, boşlukları daraltır ve terminal oturumunu okunabilir metin olarak sunar. Şunlar için idealdir:

• LLM bağlam pencerelerine yerleştirme (minimum token)
• Tam metin arama indeksleme
• Kaydedilen oturumlardan dokümantasyon oluşturma
• GIF'ler arasında terminal çıktısını karşılaştırma

.md Endpoint'leri

AgentGIF'teki her sayfanın bir Markdown varyantı vardır. Herhangi bir URL'ye .md ekleyin:

# 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

Yanıt text/markdown; charset=utf-8 formatındadır — LLM'lerin doğrudan ayrıştırabileceği temiz, yapılandırılmış metin.

JSON API

REST API tam yapılandırılmış veri sağlar. Okumalar için kimlik doğrulaması gerekmez:

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

İçerik Keşfi

Yapay zeka ajanları AgentGIF içeriğini birden fazla kanal aracılığıyla keşfedebilir:

Gerçek Dünya Örnekleri

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