Cómo crear un agente con Claude en un VPS

Qué significa construir un agente con Claude

Construir un agente con Claude significa usar Claude como núcleo de razonamiento mientras el bucle, las herramientas y los datos residen en su propio servidor. Claude decide qué hacer; su VPS lo ejecuta. Usted envía a Claude la tarea y el estado actual; Claude responde con una respuesta o con una solicitud para usar una de sus herramientas; su código ejecuta la herramienta y devuelve el resultado, y el bucle continúa hasta que el trabajo termine. La inteligencia es un servicio que se llama a través de internet. Todo lo demás es suyo.

Esta división es la ventaja. Obtiene razonamiento de nivel frontera sin operar un modelo, y mantiene el control total de lo que el agente puede tocar, ya que las herramientas se ejecutan en hardware de su propiedad. Si ya ha construido su primer programa con Claude, la guía sobre la primera app de Claude en un VPS cubre la base sobre la que se construye este.

Claude es el cerebro: la Messages API

Cada llamada a Claude pasa por un único endpoint, la Messages API. Usted envía la conversación hasta el momento y la lista de herramientas que el agente puede usar; Claude devuelve su siguiente mensaje. Ese mensaje es una respuesta final o una solicitud para llamar a una herramienta. Para la ruta de construcción propia no existe una "agent API" separada: el uso de herramientas es una función de este único endpoint, y el bucle a su alrededor es responsabilidad suya.

Claude no tiene estado entre llamadas, lo que significa que no recuerda nada por sí mismo. Cada solicitud contiene la conversación completa. Su código mantiene el historial y lo envía en cada turno, razón por la cual cada turno en una sesión larga cuesta más tokens que el anterior. Esto no es tanto una limitación como una elección de diseño: como el estado reside en su servidor, usted decide exactamente qué ve Claude, y nada de la tarea se almacena en un lugar que usted no controle.

El uso de herramientas es el bucle del agente

El bucle del agente con Claude es sencillo de describir. Usted envía una solicitud que incluye sus herramientas. Claude lee la tarea y, si necesita actuar, responde con una solicitud de uso de herramienta que nombra una herramienta y completa sus parámetros de entrada. Su código ejecuta esa herramienta y luego envía el resultado de vuelta a Claude en la siguiente solicitud. Claude lee el resultado y solicita otra herramienta o escribe su respuesta final. Cuando deja de solicitar herramientas, la tarea ha terminado.

Puede escribir ese bucle manualmente en pocas líneas, y mucha gente lo hace, porque es fácil de visualizar y de controlar. Los SDK oficiales también proporcionan un ejecutor de herramientas (tool runner) que gestiona el bucle por usted: usted proporciona las funciones de las herramientas y el SDK gestiona el intercambio de llamadas a Claude, la ejecución de sus herramientas y el envío de los resultados hasta que Claude termine. En ambos casos la estructura es la misma. El ejecutor solo le evita tener que escribir el bucle usted mismo.

Tres formas de construir, y cuáles encajan en un VPS

Existen tres formas de construir un agente de Claude, y difieren en la cantidad de maquinaria que usted debe ejecutar.

La primera es su propio código llamando a la API de Claude con sus propias herramientas. Usted escribe el bucle, o usa el ejecutor de herramientas del SDK, y aloja todo en su VPS. Esta es la opción común, porque le da control completo sobre las herramientas, los datos y la seguridad, y se ejecuta como un programa ordinario en su servidor. La mayor parte de esta guía asume este camino.

La segunda es el Claude Agent SDK. Este es Claude Code, el agente de codificación, empaquetado como una librería sobre la cual puede construir. Incluye un bucle de agente completo y herramientas integradas para leer y escribir archivos, ejecutar comandos de shell y realizar búsquedas, para que no tenga que ensamblarlos desde cero. También se ejecuta en su propio servidor, lo que lo hace ideal para un VPS cuando desea un agente capaz de manejar archivos y shell sin tener que construir el armazón usted mismo. Un agente que lee archivos y ejecuta comandos de shell necesita contención antes de funcionar sin supervisión, y ejecutar Claude Code de forma segura en un servidor cubre el sistema de permisos, el sandbox y las opciones de aislamiento.

La tercera son los Managed Agents, donde Anthropic ejecuta el bucle y aloja un sandbox en el que se ejecutan las herramientas del agente. Esta es la opción sin gestión: hay mucho menos que operar, pero el espacio de trabajo del agente reside en la infraestructura de Anthropic en lugar de en su VPS. Utilícela cuando desee la mínima carga operativa y no necesite que las herramientas se ejecuten en su propia máquina. Para las otras dos, su servidor es el hogar del agente, que es de lo que trata el resto de esta guía.

Conectar herramientas con MCP

Cualquiera que sea el camino que elija, querrá conectar al agente con sistemas reales, y el Model Context Protocol es la forma ordenada de hacerlo. MCP es un estándar abierto para exponer herramientas y datos a un agente. En lugar de programar manualmente una integración para cada servicio, usted apunta a Claude hacia un servidor MCP que ya presenta esas capacidades como herramientas. Puede ejecutar servidores MCP como servicios pequeños en el mismo VPS, cada uno con solo el acceso que necesita, lo cual cubro en ejecutar servidores MCP en un VPS.

Elegir un modelo

Claude se presenta en varios modelos, y elegir uno es un equilibrio entre capacidad, velocidad y coste. Al momento de escribir esto, las opciones principales son Claude Opus 4.8 (claude-opus-4-8), el estándar capaz para razonamiento complejo y ejecuciones largas de agentes; Claude Sonnet 5 (claude-sonnet-5), una opción equilibrada que es más barata y rápida manteniendo un rendimiento cercano a Opus en muchas tareas; y Claude Haiku 4.5 (claude-haiku-4-5), la más rápida y barata, para pasos simples de alto volumen. Por encima de ellos está Claude Fable 5 (claude-fable-5), el modelo más capaz, para el trabajo más exigente. Use el identificador de modelo exacto en su código, sin añadir la fecha.

Un patrón práctico es mezclarlos. Deje que un modelo más barato gestione las llamadas rutinarias a herramientas y uno más fuerte gestione las decisiones difíciles. Debido a que el modelo es solo una cadena de texto en su solicitud, cambiar es un cambio de una sola línea, así que comience con un estándar capaz y reduzca el nivel donde la velocidad o el coste importen más que la máxima calidad.

Ejecútelo como un servicio endurecido en su VPS

Un agente solo es útil si permanece en ejecución, y solo es seguro si está contenido. En un VPS, ambos aspectos se logran ejecutando el agente como un servicio del sistema endurecido en lugar de un programa iniciado manualmente en una terminal. Como servicio, se inicia al arrancar, se reinicia si falla y registra logs en el journal. Al estar endurecido, se ejecuta como un usuario sin privilegios con solo el acceso que necesita, de modo que un error o una instrucción incorrecta tiene un límite.

La regla más importante es mantener su clave de API de Claude en el lado del servidor. La clave paga y autoriza cada llamada, por lo que debe estar en un archivo legible solo por el usuario del agente, cargado en el servicio como una variable de entorno, y nunca colocada en el código, en un repositorio o en cualquier lugar que un navegador pueda alcanzar. Genere una unidad de servicio completa y endurecida para su agente aquí:

Luego, termine de configurar el servidor. Configure SSH solo mediante llaves y bloquee la cuenta desde la que administra, como en SSH hardening on a VPS. Si prefiere dirigir el agente desde una sesión interactiva mientras lo construye, ejecutar Claude Code en un VPS con tmux es un buen complemento. Y si desea los conceptos detrás de todo esto, sin vincularlos a un modelo específico, la guía hermana sobre construir su propio agente de IA en un VPS expone los fundamentos.

Si lo que busca es un asistente de codificación por terminal, ejecutar un agente de IA de codificación en un VPS cubre Aider y Goose.

FAQ

¿Qué modelo de Claude debería usar para construir un agente?

Comience con Claude Opus 4.8 (claude-opus-4-8), el estándar capaz, y ajuste desde ahí. Claude Sonnet 5 (claude-sonnet-5) es más barato y rápido para la mayoría de los trabajos, Claude Haiku 4.5 (claude-haiku-4-5) es mejor para pasos simples de alto volumen, y Claude Fable 5 (claude-fable-5) es el más capaz para las tareas más difíciles. Un patrón común es usar un modelo más barato para pasos rutinarios y uno más fuerte para las decisiones difíciles, ya que cambiar es un cambio de una sola línea.

¿Ejecuto todo el agente en mi VPS, o lo hace Anthropic?

Depende del enfoque. Si escribe su propio bucle contra la API de Claude, o usa el Claude Agent SDK, el agente se ejecuta completamente en su VPS y solo las llamadas al modelo salen hacia Anthropic. Si usa Managed Agents, Anthropic ejecuta el bucle y aloja el sandbox donde se ejecutan las herramientas, por lo que menos parte reside en su servidor. Para un agente que se ejecuta en su propia máquina, use cualquiera de las dos primeras opciones.

¿Cuál es la diferencia entre la Claude API y el Claude Agent SDK?

La Claude API es el endpoint de Messages puro: usted envía una conversación y herramientas, y escribe el bucle del agente a su alrededor, o usa el ejecutor de herramientas del SDK para gestionarlo. El Claude Agent SDK es una librería de nivel superior, Claude Code empaquetado para construir sobre él, que incluye un bucle completo y herramientas integradas de archivos, shell y búsqueda. Use la API cuando quiera definir todo usted mismo, y el Agent SDK cuando quiera un agente capaz sin tener que ensamblar el armazón.

¿Cómo mantengo segura mi clave de API de Claude en un servidor?

Manténgala en el lado del servidor y fuera de su código. Guárdela en un archivo legible solo por la cuenta bajo la cual se ejecuta el agente, cárguela en el servicio como una variable de entorno y nunca la suba a un repositorio ni la exponga a un navegador. Debido a que cada solicitud a Claude proviene de su servidor, la clave nunca necesita llegar al dispositivo de un usuario, lo que hace que un agente ejecutado en un servidor sea más fácil de asegurar que uno embebido en una aplicación cliente.

¿Necesito alojar yo mismo un modelo para construir un agente con Claude?

No. Con Claude, el modelo es un servicio alojado que se llama a través de la API, por lo que no hay nada que ejecutar en una GPU. Su VPS ejecuta el bucle del agente, las herramientas y los datos, y el razonamiento ocurre en el lado de Anthropic. Eso es lo que permite que un servidor modesto ejecute un agente capaz. Si desea un modelo totalmente local en su lugar, ese es el camino de alojamiento propio cubierto en la guía complementaria sobre cómo construir su propio agente de IA.