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 EN (English) ou pelo SDK Node.js EN (English).

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 a página do SDK do MCP Server EN (English).

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 7 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 a um projeto Next.js com App Router (rota de assinatura do lado do servidor + página de demonstração opcional do lado do cliente).
• 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-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 Builtin Templates (builtin/generate-image@latest) e baixe as saídas localmente via -o.
• transform-remove-background-with-transloadit: Remoção de fundo pontual (imagem local -> PNG transparente) usando a Transloadit via a CLI transloadit. Use um JSON de steps mínimo com /image/bgremove e baixe o resultado para um caminho .png explícito via -o.
• 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.