Crear un agente con Claude en un VPS

Qué implica crear un agente con Claude

Crear un agente con Claude significa usar Claude como núcleo de razonamiento mientras el bucle, las herramientas y los datos residen en tu propio servidor. Claude decide qué hacer; tu VPS lo ejecuta. Envías a Claude la tarea y el estado actual, Claude responde con una respuesta o solicita usar una de tus herramientas, tu código ejecuta la herramienta y envía el resultado de vuelta, y el bucle continúa hasta completar el trabajo. La inteligencia es un servicio al que accedes a través de Internet. Todo lo que lo rodea es tuyo.

Esta separación es la principal ventaja. Obtienes un razonamiento de nivel avanzado sin operar un modelo y mantienes el control total sobre aquello a lo que puede acceder el agente, porque las herramientas se ejecutan en hardware de tu propiedad. Si ya has creado un primer programa con Claude, la guía para crear la primera aplicación de Claude en un VPS cubre los fundamentos sobre los que se basa esta guía.

Claude es el cerebro: la Messages API

Todas las llamadas a Claude pasan por un único endpoint: la Messages API. Envíe la conversación hasta ese 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. En la opción de crear el agente manualmente no existe una «agent API» independiente: el uso de herramientas es una función de este único endpoint y el bucle que lo rodea debe ejecutarlo su código.

Claude no conserva estado entre llamadas, por lo que no recuerda nada por sí mismo. Cada solicitud incluye la conversación completa. Su código conserva el historial y lo envía en cada turno, lo que explica que cada turno de una sesión larga consuma más tokens que el anterior. No se trata tanto de una limitación como de una decisión de diseño: como el estado reside en su servidor, usted decide exactamente qué ve Claude y nada relacionado con la tarea se almacena fuera de los sistemas que controla. Esto hace que el prompt siga creciendo. Aunque la ventana de contexto de Claude lo admite sin problemas, un modelo local en el mismo bucle no lo hará. Por eso es necesario aumentar num_ctx en Ollama antes de que deje de truncar los prompts largos.

El uso de herramientas es el bucle del agente

El bucle del agente con Claude es sencillo de describir. Envía una solicitud que incluye sus herramientas. Claude lee la tarea y, si necesita actuar, responde con una solicitud de uso de herramientas que indica una herramienta y completa sus entradas. El código ejecuta esa herramienta y después envía el resultado 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 unas pocas líneas, y muchas personas lo hacen porque es fácil de ver y controlar. Los SDK oficiales también proporcionan un ejecutor de herramientas que gestiona el bucle por usted: usted proporciona las funciones de las herramientas y el SDK se encarga del intercambio de llamadas a Claude, la ejecución de las herramientas y el envío de los resultados hasta que Claude termina. En ambos casos, la estructura es la misma. El ejecutor sólo evita que tenga que escribir el bucle. Si el bucle todavía parece abstracto, la solución es escribir uno mínimo antes de usar un ejecutor; ese es el paso del que depende todo lo demás en esta ruta gradual para aprender a crear agentes de IA desde cero.

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

Hay tres formas de construir un agente de Claude. Se diferencian por la cantidad de componentes que debe ejecutar.

La primera consiste en escribir su propio código, llamar a la API de Claude y usar sus propias herramientas. Puede escribir el bucle usted mismo o usar el ejecutor de herramientas del SDK, y alojar todo en su VPS. Es la opción habitual porque proporciona control completo sobre las herramientas, los datos y la seguridad, y se ejecuta como un programa normal en el servidor. La mayor parte de esta guía presupone este enfoque.

La segunda opción es Claude Agent SDK. Se trata de Claude Code, el agente de programación, empaquetado como una biblioteca sobre la que puede construir. Incluye un bucle de agente completo y herramientas integradas para leer y escribir archivos, ejecutar comandos de shell y realizar búsquedas. Por tanto, no tiene que crear estos componentes desde cero. También se ejecuta en su propio servidor, por lo que encaja bien en un VPS cuando necesita un agente capaz de trabajar con archivos y shell sin construir el armazón usted mismo. Un agente que lee archivos y ejecuta comandos de shell necesita aislamiento antes de funcionar sin supervisión. Ejecutar Claude Code de forma segura en un servidor explica el sistema de permisos, el sandbox y las opciones de aislamiento.

La tercera opción es Managed Agents. En este caso, Anthropic ejecuta el bucle y aloja un sandbox en el que se ejecutan las herramientas del agente. Es la opción que requiere menos intervención: hay muchos menos componentes que administrar, pero el espacio de trabajo del agente reside en la infraestructura de Anthropic y no en su VPS. Elija esta opción cuando quiera reducir al mínimo el trabajo operativo y no necesite que las herramientas se ejecuten en su propia máquina. En las otras dos opciones, el servidor aloja el agente. Ese es el tema del resto de esta guía.

Conectar herramientas con MCP

Independientemente de la opción que elija, querrá conectar el agente con sistemas reales. Model Context Protocol es una 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, configura Claude para usar un servidor MCP que ya presenta esas capacidades como herramientas. Puede ejecutar los servidores MCP como servicios pequeños en el mismo VPS, cada uno con sólo los permisos que necesita. Este tema se trata en ejecutar servidores MCP en un VPS.

Elegir un modelo

Claude está disponible en varios modelos. Elegir uno implica equilibrar capacidad, velocidad y coste. En el momento de redactar este texto, las opciones principales son Claude Opus 4.8 (claude-opus-4-8), el modelo predeterminado capaz de resolver problemas complejos y ejecutar agentes durante mucho tiempo; Claude Sonnet 5 (claude-sonnet-5), una opción equilibrada, más económica y rápida, que se acerca a Opus en muchas tareas; y Claude Haiku 4.5 (claude-haiku-4-5), el más rápido y económico, para pasos sencillos y de gran volumen. Por encima de ellos está Claude Fable 5 (claude-fable-5), el modelo más capaz, destinado a los trabajos más exigentes. Use el identificador exacto del modelo en el código, sin añadirle una fecha.

Un patrón práctico consiste en combinarlos. Deje que un modelo más económico gestione las llamadas rutinarias a herramientas y que uno más potente tome las decisiones difíciles. Como el modelo sólo es una cadena en la petición, cambiarlo requiere modificar una sola línea. Empiece con un modelo predeterminado capaz y reduzca el nivel donde la velocidad o el coste sean más importantes que el último margen de calidad.

Ejecútalo como un servicio protegido en tu VPS

Un agente sólo es útil si permanece en ejecución y sólo es seguro si está contenido. En un VPS, ambas condiciones se cumplen al ejecutar el agente como un servicio del sistema protegido, en lugar de iniciarlo manualmente desde una terminal. Como servicio, se inicia durante el arranque, se reinicia si se bloquea y registra los mensajes en el journal. Con una configuración protegida, se ejecuta con un usuario sin privilegios y sólo tiene el acceso que necesita. Así, un error o una instrucción maliciosa tienen un alcance limitado. Una unidad de servicio sólo puede restringir lo que el proceso puede tocar. El resto debe implementarse dentro del propio armazón del agente. Esa es la función de los complementos de DeepSeek Harness que conviene instalar en otra pila: límites de gasto, reglas de permisos por herramienta y análisis de inyección de instrucciones.

La regla más importante es mantener la clave de API de Claude en el servidor. La clave paga y autoriza cada llamada. Por tanto, debe estar en un archivo que sólo pueda leer el usuario del agente, cargarse en el servicio como una variable de entorno y no incluirse nunca en el código, en un repositorio ni en ningún lugar accesible desde un navegador. Genere aquí una unidad de servicio completa y protegida para su agente:

Después, proteja el propio servidor. Configure SSH para aceptar únicamente claves y restrinja la cuenta desde la que administra el sistema, como se explica en Protección de SSH en un VPS. Si prefiere controlar el agente desde una sesión interactiva mientras lo configura, ejecutar Claude Code en un VPS con tmux es un complemento útil. Cuando tenga una segunda sesión abierta en el mismo equipo, ambas pueden intercambiar trabajo en lugar de obligarle a trasladar cada instrucción de un panel al otro. Si quiere conocer los conceptos en los que se basa todo esto sin vincularlos a un modelo concreto, la guía complementaria sobre crear su propio agente de IA en un VPS presenta los fundamentos.

Si busca un asistente de programación en la terminal, ejecutar un agente de IA para programación en un VPS cubre Aider y Goose.

FAQ

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

Empiece con Claude Opus 4.8 (claude-opus-4-8), el valor predeterminado más capaz, y ajuste a partir de ahí. Claude Sonnet 5 (claude-sonnet-5) es más económico y rápido para la mayoría de las tareas, Claude Haiku 4.5 (claude-haiku-4-5) es la mejor opción para pasos sencillos y de gran volumen, y Claude Fable 5 (claude-fable-5) es el más capaz para las tareas más difíciles. Un patrón habitual consiste en usar un modelo más económico para los pasos rutinarios y uno más potente para las decisiones complejas, ya que cambiar de modelo requiere modificar 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 Claude API o usa Claude Agent SDK, el agente se ejecuta por completo en su VPS y sólo las llamadas al modelo se envían a Anthropic. Si usa Managed Agents, Anthropic ejecuta el bucle y aloja el sandbox donde se ejecutan las herramientas, por lo que una parte menor reside en su servidor. Para un agente que se ejecute en su propia máquina, use una de las dos primeras opciones.

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

Claude API es el endpoint Messages sin abstracciones: envía una conversación y las herramientas, y escribe el bucle del agente, o usa el ejecutor de herramientas del SDK para controlarlo. Claude Agent SDK es una biblioteca de nivel superior, Claude Code empaquetado para crear aplicaciones, que incluye un bucle completo y herramientas integradas de archivos, shell y búsqueda. Use la API si quiere definirlo todo por su cuenta, y Agent SDK si quiere un agente capaz sin tener que ensamblar el armazón.

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

Manténgala en el servidor y fuera del código. Guárdela en un archivo legible únicamente por la cuenta con la que se ejecuta el agente, cárguela en el servicio como una variable de entorno y no la confirme nunca en un repositorio ni la exponga a un navegador. Como todas las solicitudes a Claude salen de su servidor, la clave nunca necesita llegar al dispositivo del usuario. Esto hace que un agente ejecutado en el servidor sea más fácil de proteger que uno integrado en una aplicación cliente.

¿Necesito alojar un modelo por mi cuenta para crear un agente con Claude?

No. Con Claude, el modelo es un servicio alojado al que se accede mediante 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, mientras el razonamiento tiene lugar en el lado de Anthropic. Esto permite que un servidor modesto ejecute un agente capaz. Si quiere un modelo completamente local, esa es la opción de alojamiento propio que se explica en la guía complementaria sobre cómo crear su propio agente de IA.