AI Agent-Readable GIFs — Machine Layer Documentation

Das Problem

GIF-Bilder sind für KI-Agenten undurchsichtig. Wenn ein README ein Terminal-Demo-GIF enthält, sieht ein KI-Agent binäre Pixeldaten — er kann die Befehle nicht extrahieren, die Ausgabe verstehen oder bestimmte Schritte referenzieren. Dies ist eine grundlegende Einschränkung der bildbasierten Dokumentation.

AgentGIF löst dies, indem strukturierte, maschinenlesbare Daten an jedes GIF angehängt werden.

Zwei-Schichten-Architektur

Jedes GIF auf AgentGIF hat zwei Schichten, die unter derselben URL koexistieren:

Ein Mensch sieht ein animiertes Terminal. Ein KI-Agent sieht strukturierte Daten: Befehle, Ausgabe, Zeitstempel, Metadaten und Einbettungscodes.

Cast-Dateien (Asciinema v2)

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

Auf den Cast zugreifen

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

Cast-Dateistruktur

Zeile 1 ist ein JSON-Header mit Terminal-Metadaten:

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

Nachfolgende Zeilen sind Ereignis-Tupel:

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

Jedes Tupel ist [timestamp_seconds, event_type, data]:

• "o" — output event (text written to the terminal screen)
• "i" — input event (user keystrokes, if captured)
• Zeitstempel sind in Sekunden ab Aufnahmebeginn
• Daten können ANSI-Escape-Codes für Farben enthalten

Eine Cast-Datei parsen

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

Transkripte

Für einfachere Anwendungsfälle gibt der Transkript-Endpunkt sauberen Klartext zurück:

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

Transkripte entfernen ANSI-Escape-Codes, komprimieren Leerzeichen und präsentieren die Terminal-Sitzung als lesbaren Text. Sie sind ideal für:

• In LLM-Kontextfenster einbetten (minimale Token)
• Volltext-Suchindizierung
• Dokumentation aus aufgezeichneten Sitzungen generieren
• Terminal-Ausgabe über GIFs hinweg vergleichen

.md-Endpunkte

Jede Seite auf AgentGIF hat eine Markdown-Variante. .md an eine beliebige URL anhängen:

# 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

Die Antwort ist text/markdown; charset=utf-8 — sauberer, strukturierter Text, den LLMs direkt parsen können.

JSON-API

Die REST-API bietet vollständige strukturierte Daten. Keine Authentifizierung für Lesezugriffe erforderlich:

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

Inhaltsermittlung

KI-Agenten können AgentGIF-Inhalte über mehrere Kanäle entdecken:

Praxisbeispiele

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