AI Agent-Readable GIFs — Machine Layer Documentation

O Problema

Imagens GIF são opacas para agentes de IA. Quando um README contém um GIF de demonstração de terminal, um agente de IA vê dados binários de pixels — não consegue extrair os comandos, entender a saída ou referenciar etapas específicas. Esta é uma limitação fundamental da documentação baseada em imagens.

O AgentGIF resolve isso anexando dados estruturados e legíveis por máquina a cada GIF.

Arquitetura de Camada Dupla

Cada GIF no AgentGIF possui duas camadas que coexistem na mesma URL:

Um humano vê um terminal animado. Um agente de IA vê dados estruturados: comandos, saída, timestamps, metadados e códigos de embed.

Arquivos Cast (Asciinema v2)

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

Acessando o Cast

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

Estrutura do Arquivo Cast

A linha 1 é um cabeçalho JSON com metadados do terminal:

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

As linhas subsequentes são 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 é [timestamp_seconds, event_type, data]:

• "o" — output event (text written to the terminal screen)
• "i" — input event (user keystrokes, if captured)
• Os timestamps são em segundos a partir do início da gravação
• Os dados podem conter códigos de escape ANSI para cores

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

Transcrições

Para casos de uso mais simples, o endpoint de transcrição retorna texto simples limpo:

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

As transcrições removem códigos de escape ANSI, condensam espaços em branco e apresentam a sessão de terminal como texto legível. São ideais para:

• Incorporação em janelas de contexto de LLM (tokens mínimos)
• Indexação de pesquisa de texto completo
• Geração de documentação a partir de sessões gravadas
• Comparação de saída de terminal entre GIFs

Endpoints .md

Cada página no AgentGIF tem uma variante Markdown. Adicione .md a qualquer 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

A resposta é text/markdown; charset=utf-8 — texto limpo e estruturado que LLMs podem analisar diretamente.

API JSON

A REST API fornece dados estruturados completos. Nenhuma autenticação é necessária para leituras:

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

Descoberta de Conteúdo

Agentes de IA podem descobrir conteúdo do AgentGIF por múltiplos canais:

Exemplos do 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