Agentes de IA

Comece pelo seu projeto

Cole este prompt no seu agente de codificação a partir da raiz do projeto. Ele faz o agente inspecionar o seu stack antes de escolher um SDK, MCP ou skills, e mantém a primeira alteração revisável:

Set up the smallest safe Transloadit integration for this repository.

1. Inspect the project’s language, runtime, package manager, existing upload/media code, tests,
   and agent configuration before changing files.
2. Choose the narrowest integration that fits: an official SDK for application code, MCP for
   agent-executed runtime tools, and Agent Skills for repeatable workflow guidance. Reuse an
   existing integration when one is already present.
3. Before editing, summarize what you found, which path you chose, and the files and commands you
   expect to change.
4. Use the project’s existing package manager. Match credentials to the execution boundary. Use
   TRANSLOADIT_KEY and TRANSLOADIT_SECRET only in a trusted server, CLI, CI, or self-hosted MCP
   process. Never expose TRANSLOADIT_SECRET to browser, mobile, or other client code; use a public
   Auth Key plus a Template ID and, when required, a signature from a trusted backend. Never
   hardcode, print, commit, or overwrite credentials. If required credentials are unavailable,
   scaffold placeholders and stop before any live request.
5. Create one minimal, typed workflow and validate its Assembly Instructions. Prefer an existing
   small media fixture. Do not create an account, change a plan, or modify production Templates.
6. Run the repository’s checks. If credentials and a suitable fixture are available and a live
   test is authorized, run one Assembly, wait for completion, and report its Assembly ID, status,
   and result URL. Otherwise, report the exact command the maintainer can run.
7. Summarize every changed file, verification result, and any remaining manual step.

O resultado esperado é uma pequena alteração no repositório, não apenas um exemplo de código gerado. Revise a fronteira de confiança proposta pelo agente para as credenciais antes de permitir uma Assembly real.

O que o agente deve escolher

Servidor MCP

O Model Context Protocol⁠ (MCP) dá aos agentes acesso direto, em tempo de execução, às ferramentas da Transloadit.

Para a maioria das equipes, o ponto de partida recomendado é o MCP auto-hospedado via stdio:

TRANSLOADIT_KEY=MY_AUTH_KEY TRANSLOADIT_SECRET=MY_SECRET_KEY npx -y @transloadit/mcp-server stdio

Se você não puder executar npx no seu ambiente, use o endpoint hospedado https://api2.transloadit.com/mcp com Authorization: Bearer <token>.

Gere o token em outro ambiente confiável (por exemplo, seu backend, a CI ou o shell local) e depois passe-o para o runtime do seu agente:

npx -y @transloadit/node auth token --aud mcp

Você também pode gerar tokens via POST /token ou pelo SDK para Node.js.

Para exemplos de configuração de cliente (Claude, Cursor, VS Code/Copilot), detalhes de autenticação, documentação das ferramentas, limites e comportamento hospedado vs. auto-hospedado, veja o Servidor MCP.

Caminhos de automação

As ferramentas para agentes da Transloadit são úteis muito além dos agentes de codificação baseados em chat. Elas dão às equipes algumas formas práticas de executar o mesmo fluxo de trabalho de mídia a partir de scripts locais, jobs de CI, consoles de operações e agentes autônomos:

• CLI: use @transloadit/node quando uma pessoa ou um job de CI precisar de um comando repetível para criar uma Assembly, aguardar a conclusão e coletar os resultados.
• MCP: exponha uma superfície restrita de ferramentas da Transloadit para agentes embarcados ou hospedados que não devem ter acesso ao shell. O agente pode inspecionar a documentação dos Robots, fazer lint das Assembly Instructions, criar Assemblies e acompanhar atualizações de status pelo servidor MCP.
• Agent Skills: mantenha sob controle de versão os playbooks de fluxos de trabalho de mídia específicos da sua equipe, voltados a agentes que já têm ferramentas úteis, como acesso ao terminal, MCP, a CLI ou SDKs. As skills dizem ao agente quais Templates, etapas de verificação e fallbacks usar, mas não concedem novas capacidades por si só.
• llms.txt: dê a qualquer LLM um mapa atual dos produtos, soluções, integrações, recursos para desenvolvedores e conteúdo de aprendizado da Transloadit antes que ele proponha uma Assembly.

Para automação em produção, mantenha as credenciais no seu ambiente confiável e deixe que os agentes chamem um servidor MCP auto-hospedado ou o seu próprio backend. O MCP hospedado é conveniente quando o runtime do agente não consegue iniciar processos locais, enquanto a CLI continua sendo a opção mais simples para jobs determinísticos na CI.

Agent Skills

Agent Skills⁠ são arquivos markdown (SKILL.md) que ensinam aos agentes como realizar tarefas passo a passo.

Na prática, um servidor MCP é uma superfície de API que um agente pode chamar em tempo de execução (por meio de um processo MCP local ou hospedado), enquanto as skills são playbooks versionados que dizem ao agente o que fazer, em que ordem e como verificar o resultado. As skills não adicionam acesso a novas ferramentas por si só. Elas codificam como você quer que o agente use, de forma consistente, as ferramentas disponíveis no seu ambiente (MCP, CLI, SDKs).

• Use o MCP para execução embarcada e repetível (uploads, Assemblies, polling, resultados).
• Use as skills como playbooks reutilizáveis e guiados por pessoas para tarefas como configuração, scaffolding, templates e migrações.

Eles também se complementam. Uma skill pode padronizar um fluxo de trabalho e então instruir o agente a usar o MCP (ou um fallback local via CLI) para a execução propriamente dita.

Instale com a Skills CLI

npx skills add transloadit/skills

Isso instala todas as 13 skills da Transloadit no seu projeto:

• docs-transloadit-robots

  Consulta offline de Robots da Transloadit e da documentação/exemplos de seus parâmetros via a CLI transloadit. Use para redigir ou validar o JSON de steps sem adivinhar nomes/parâmetros de Robots.

• integrate-asset-delivery-with-transloadit-smartcdn-in-nextjs

  Adicione assinatura de URLs do Smart CDN da Transloadit do lado do servidor, para um recurso explicitamente configurado, a um projeto Next.js com App Router.

• integrate-uppy-transloadit-s3-uploading-to-nextjs

  Adicione o Uppy Dashboard + uploads da Transloadit a um app Next.js (App Router), com geração de assinatura do lado do servidor e exportação opcional via /s3/store.

• transform-build-mosaic-collage-with-transloadit

  Colagem pontual de fotos em mosaico justificado (N imagens locais -> uma única imagem) usando a CLI oficial @transloadit/node. Usa o efeito mosaic do Robot /image/merge para criar um layout em blocos justificado com fotos com recorte central e baixa o resultado para um caminho de saída explícito via --output.

• transform-build-polaroid-collage-with-transloadit

  Colagem pontual de fotos Polaroid empilhadas (N imagens locais -> uma única imagem) usando a CLI oficial @transloadit/node. Usa o efeito polaroid-stack do Robot /image/merge e baixa o resultado para um caminho de saída explícito via --output.

• transform-convert-markdown-to-pdf-with-transloadit

  Converta um arquivo Markdown local em um PDF no mesmo diretório usando a CLI oficial @transloadit/node. Use quando o usuário quiser renderizar um arquivo .md como .pdf, especialmente em uma sessão de agente ou em um repositório local. A CLI obtém os dados de autenticação no ambiente do shell, depois no arquivo .env do diretório de trabalho atual e, por fim, em ~/.transloadit/credentials.

• transform-describe-image-with-transloadit

  Descrição pontual de imagem usando a CLI oficial @transloadit/node. Use image describe --fields labels para rótulos de objetos, ou image describe --for wordpress para um JSON estruturado com texto alternativo, título, legenda e descrição.

• transform-encode-hls-video-with-transloadit

  Codificação HLS pontual (vídeo local -> versões HLS + playlist) usando a Transloadit via a CLI transloadit. Prefira Builtin Templates (builtin/encode-hls-video@latest) e baixe as saídas localmente via -o.

• transform-generate-image-with-transloadit

  Geração de imagem pontual (prompt -> arquivo de imagem) usando a Transloadit via a CLI transloadit. Prefira image generate para geração somente a partir de texto e para geração guiada por uma entrada, e use --output quando precisar de um caminho determinístico.

• transform-remove-background-with-transloadit

  Remoção de fundo pontual (imagem local -> PNG transparente) usando a CLI oficial @transloadit/node. Use um JSON de Steps mínimo com /image/bgremove e baixe o resultado para um caminho .png explícito via -o.

• transform-transcribe-audio-with-transloadit

  Transcrição pontual de arquivos locais de áudio ou vídeo em arquivos de texto ou de legendas usando a Transloadit via a CLI oficial @transloadit/node. Use quando o usuário quiser converter a fala em mídias locais para .txt, .json, .srt ou .webvtt; prefira a intenção speech transcribe com Replicate.

• transform-upscale-image-with-transloadit

  Ampliação pontual de imagem com IA (imagem local -> imagem ampliada) usando a Transloadit via a CLI transloadit. Prefira a intenção image upscale e use --output para um caminho determinístico.

• transloadit

  Skill principal de entrada da Transloadit. Direcione para a skill integrate-*, transform-* ou docs-* correta e prefira executar via npx -y @transloadit/node ... (CLI) para um comportamento determinístico.

Descoberta automática

O catálogo de skills também pode ser descoberto em transloadit.com/.well-known/skills/index.json, seguindo o RFC de descoberta de Agent Skills⁠. Isso significa que você também pode instalar com:

npx skills add https://transloadit.com

Instalação manual

Clone ou crie um symlink do repositório transloadit/skills⁠ no diretório de skills do seu agente:

llms.txt

A Transloadit publica um arquivo llms.txt, um índice de roteamento compacto de todo o site que segue o padrão llms.txt⁠. Ele cobre produtos e serviços, soluções, integrações, índices de mídia e de tarefas, recursos para desenvolvedores e de aprendizado, e suporte.

Para a descoberta específica de Robots, use /docs/robots/llms.txt. O arquivo de compatibilidade legado llms-full.txt inclui inline os schemas completos de parâmetros dos Robots, mas é grande. Prefira llms.txt para a descoberta e busque apenas as páginas Markdown vinculadas que sejam relevantes para a tarefa.

Qual abordagem devo usar?

Essas abordagens se complementam. Use o MCP auto-hospedado para acesso a ferramentas na maioria das configurações, ou o MCP hospedado quando o runtime do agente não conseguir iniciar processos locais. Instale skills para orientar os fluxos de trabalho e aponte o seu LLM para o llms.txt quando ele precisar da documentação da Transloadit.