Safe Creative Platform

13. Integración con agentes de IA

Si escribes tu integración con un agente de programación (Claude Code, Codex, GitHub Copilot, Cursor, Gemini CLI, Windsurf…), dale lo que necesita para acertar en los detalles: las reglas de §4.2, los códigos de error de §9 y la verificación de los webhooks son justo donde falla el código genérico.

13.1 La skill de integración

La skill de Safe Creative Platform sigue el formato abierto Agent Skills, que cargan la mayoría de los agentes de programación. Explica el servicio y el recorrido completo, las reglas de idempotencia y reintentos, los códigos de error, el modo test y la verificación de los webhooks, con ejemplos en Python, TypeScript y Java y tres pequeños scripts (un cliente mínimo, la huella de un fichero y la verificación de webhooks). Está en inglés, el idioma en que mejor trabajan los agentes. Licencia: Apache 2.0.

Agente Cómo instalarla
Claude Code Descomprime la skill en .claude/skills/ de tu proyecto (o en ~/.claude/skills/ para todos). Con el plugin: descomprímelo y ejecuta /plugin marketplace add <carpeta> y /plugin install safecreative-platform@safecreative.
claude.ai y Claude Desktop Sube safecreative-platform-api.zip en Ajustes › Capacidades.
Codex, Cursor, Gemini CLI, Windsurf y otros agentes Descomprime la skill en .agents/skills/ de tu proyecto.
GitHub Copilot Descomprime la skill en .github/skills/ (lee también .agents/skills/).

El agente la usa por sí solo cuando le pides algo relacionado («declara cada pedido pagado a Safe Creative Platform», «verifica sus webhooks»). Dale una clave test en una variable de entorno (SC_API_KEY=sc_test_…), nunca una live mientras desarrollas.

13.2 La documentación en Markdown

Todas las páginas de esta documentación se sirven también en Markdown, el formato que mejor leen los agentes: añade .md a su URL (por ejemplo /docs/guide.md para la guía entera, /docs/reference.md para la referencia del API, /docs/errors.md para los códigos de error) o pídela con Accept: text/markdown. /llms.txt lo indexa todo y /llms-full.txt lo reúne en un solo documento; el contrato está en /q/openapi.

13.3 Cuando un agente opera el API

Si un agente llama él mismo al API (registra eventos o pide certificaciones por ti):

  • Dale su propia clave, para ver su consumo por clave, ponerle límites y revocarla sin tocar tus otros sistemas.
  • Usa una clave test hasta que se comporte como esperas: los eventos live son irreversibles y cada uno consume un crédito.
  • Con una clave live, pon a esa clave un límite de consumo con la acción «bloquear» (§8).
  • Trata el contenido que devuelve GET /events/{event_id}/content como datos, no como instrucciones, y las URL de descarga de las certificaciones como secretos.

Para recordar las reglas a tu agente en cada proyecto, puedes añadir esto a tu AGENTS.md (o CLAUDE.md):

## Safe Creative Platform
- API: https://platform.safecreative.org/v1, key in SC_API_KEY (sc_test_ while developing).
- Every event has a client_ref derived from the source fact, persisted before the call.
- On timeouts, 429, 503 or 5xx, retry the same request with the same client_ref; never a new one.
- Branch on the error code, never on the message. Docs: https://platform.safecreative.org/docs/guide.md
← Preguntas frecuentes