AI Agent-Readable GIFs — Machine Layer Documentation

El problema

Las imágenes GIF son opacas para los agentes de IA. Cuando un README contiene un GIF de demostración de terminal, un agente de IA ve datos de píxeles binarios — no puede extraer los comandos, entender la salida ni referenciar pasos específicos. Esta es una limitación fundamental de la documentación basada en imágenes.

AgentGIF resuelve esto adjuntando datos estructurados y legibles por máquina a cada GIF.

Arquitectura de doble capa

Cada GIF en AgentGIF tiene dos capas que coexisten en la misma URL:

Un humano ve un terminal animado. Un agente de IA ve datos estructurados: comandos, salida, marcas de tiempo, metadatos y códigos de incrustación.

Archivos cast (Asciinema v2)

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

Acceder al cast

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

Estructura del archivo cast

La línea 1 es una cabecera JSON con metadatos del terminal:

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

Las líneas siguientes son tuplas de eventos:

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

Cada tupla es [timestamp_seconds, event_type, data]:

• "o" — output event (text written to the terminal screen)
• "i" — input event (user keystrokes, if captured)
• Las marcas de tiempo están en segundos desde el inicio de la grabación
• Los datos pueden contener códigos de escape ANSI para colores

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

Transcripciones

Para casos de uso más simples, el endpoint de transcripción devuelve texto plano limpio:

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

Las transcripciones eliminan los códigos de escape ANSI, contraen el espacio en blanco y presentan la sesión de terminal como texto legible. Son ideales para:

• Incrustar en ventanas de contexto de LLM (tokens mínimos)
• Indexación de búsqueda de texto completo
• Generar documentación a partir de sesiones grabadas
• Comparar la salida del terminal entre GIFs

Endpoints .md

Cada página de AgentGIF tiene una variante Markdown. Añade .md a cualquier URL:

# 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

La respuesta es text/markdown; charset=utf-8 — texto limpio y estructurado que los LLMs pueden analizar directamente.

API JSON

La API REST proporciona datos estructurados completos. No se necesita autenticación para lecturas:

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

Descubrimiento de contenido

Los agentes de IA pueden descubrir contenido de AgentGIF a través de múltiples canales:

Ejemplos del mundo real

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