Crear un súper sencillo agente de IA en PHP para aprender

Publicado: 14 Septiembre 2026 | Escrito por Javier Orovengua | Correo electrónico | Visto: 72

Los agentes de inteligencia artificial están adquiriendo cada vez más protagonismo. Sin embargo, cuando escuchamos hablar de ellos, es fácil imaginar sistemas enormes, difíciles de programar y reservados para grandes empresas.

La realidad es mucho más sencilla: un agente de IA puede ser un pequeño programa escrito en PHP que consulta un modelo de inteligencia artificial, toma una decisión y ejecuta una acción.

En este tutorial crearemos un agente diminuto. Le daremos una palabra, decidirá si corresponde a un animal o a un objeto y la guardará en el archivo adecuado.

Por ejemplo:

Si escribimos perro, lo guardará en animales.txt.
Si escribimos mesa, lo guardará en objetos.txt.

Aunque el ejemplo sea deliberadamente sencillo, contiene los elementos esenciales de un agente de IA.

¿Qué es un agente de inteligencia artificial?

Un agente de IA es un programa capaz de recibir un objetivo, interpretar la información disponible, tomar una decisión y realizar una acción.

En nuestro ejemplo, el funcionamiento será el siguiente:

El usuario escribe una palabra.
El programa PHP la envía a un modelo de IA.
La inteligencia artificial decide si es un animal o un objeto.
PHP guarda la palabra en el archivo correspondiente.

Esta última parte es importante. Un chatbot normalmente se limita a responder, mientras que un agente puede utilizar herramientas o ejecutar acciones. En este caso, su herramienta consiste en escribir en un archivo.

Requisitos para crear el miniagente

Necesitaremos:

Un sistema Linux o un servidor con PHP.
La extensión curl de PHP.
Una cuenta en OpenAI Platform.
Una clave para utilizar la API de OpenAI.
El archivo miniagente.php que crearemos a continuación.

Podemos comprobar si PHP está instalado ejecutando:

php -v

También podemos comprobar si la extensión cURL está activa:

php -m | grep -i curl

Cómo conseguir una clave para la API de OpenAI

Debemos entrar en la sección de claves de OpenAI Platform:

https://platform.openai.com/api-keys

Después de iniciar sesión:

Pulsamos Create new secret key.
Escribimos un nombre, por ejemplo, Miniagente PHP.
Creamos la clave y la copiamos en un lugar seguro.

La clave tendrá un aspecto similar a este:

sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx

La API de OpenAI se factura independientemente de una suscripción a ChatGPT. Puede ser necesario añadir saldo o configurar un método de pago desde la sección de facturación:

Configurar la facturación de la API de OpenAI

Importante: nunca debemos publicar la clave, subirla a GitHub ni escribirla directamente dentro del código PHP.

Configurar la clave de forma segura en Linux

La guardaremos temporalmente en una variable de entorno:

export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"

Debemos sustituir el texto de ejemplo por nuestra clave real.

Este comando solo configura la clave en la terminal actual. Cuando cerremos la sesión dejará de estar disponible.

Podemos comprobar que la variable existe sin mostrar la clave completa:

if [ -n "$OPENAI_API_KEY" ]; then echo "Clave configurada"; fi

Código completo del agente de IA en PHP

Creamos un archivo llamado miniagente.php con el contenido siguiente:

<?php

/*
 * MINIAGENTE DE INTELIGENCIA ARTIFICIAL
 *
 * Uso:
 * 
 * export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxx"
 *
 * php miniagente.php perro
 *
 * El agente preguntará a la IA si "perro" es un ANIMAL
 * o un OBJETO y guardará la palabra en el archivo adecuado.
 */


/*
 * 1. OBTENER LA PALABRA ESCRITA POR EL USUARIO
 *
 * En el comando:
 *
 * php miniagente.php perro
 *
 * $argv[1] contiene la palabra "perro".
 */

$palabra = trim($argv[1] ?? '');


/*
 * 2. OBTENER LA CLAVE DE LA API
 *
 * La clave debe haberse configurado previamente:
 *
 * export OPENAI_API_KEY="sk-proj-xxxxxxxx"
 */

$apiKey = getenv('OPENAI_API_KEY');


/*
 * Comprobamos que el usuario haya escrito una palabra.
 */

if ($palabra === '') {
    exit("Uso: php miniagente.php PALABRA\n");
}


/*
 * Comprobamos que exista la clave de la API.
 */

if (!$apiKey) {
    exit("Falta configurar OPENAI_API_KEY.\n");
}


/*
 * 3. PREPARAR LA PREGUNTA PARA LA IA
 *
 * AQUÍ SE HACE LA PREGUNTA.
 *
 * En realidad enviamos dos mensajes:
 *
 * - "system" explica a la IA lo que tiene que hacer.
 * - "user" contiene la palabra que debe clasificar.
 */

$datos = [

    /*
     * Modelo de inteligencia artificial que utilizaremos.
     */

    'model' => 'gpt-4.1-mini',

    /*
     * Conversación que enviaremos a la IA.
     */

    'messages' => [

        /*
         * INSTRUCCIÓN PARA LA IA
         *
         * Aquí le explicamos la tarea.
         */

        [
            'role' => 'system',
            'content' =>
                'Clasifica la palabra como ANIMAL u OBJETO. ' .
                'Responde solamente ANIMAL u OBJETO.'
        ],

        /*
         * PALABRA O PREGUNTA DEL USUARIO
         *
         * Si ejecutamos:
         *
         * php miniagente.php perro
         *
         * Aquí se enviará "perro".
         */

        [
            'role' => 'user',
            'content' => $palabra
        ]
    ],

    /*
     * Con temperature 0 buscamos una respuesta
     * más estable y menos creativa.
     */

    'temperature' => 0
];


/*
 * 4. ABRIR LA CONEXIÓN CON OPENAI
 *
 * Esta es la dirección de la API a la que
 * enviaremos la pregunta.
 */

$curl = curl_init(
    'https://api.openai.com/v1/chat/completions'
);


/*
 * 5. CONFIGURAR LA PETICIÓN
 */

curl_setopt_array($curl, [

    /*
     * Queremos recibir la respuesta en una variable.
     */

    CURLOPT_RETURNTRANSFER => true,

    /*
     * Utilizamos una petición POST.
     */

    CURLOPT_POST => true,

    /*
     * Enviamos la clave de la API y especificamos
     * que los datos están en formato JSON.
     */

    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ],

    /*
     * Convertimos la pregunta almacenada en $datos
     * a formato JSON y la enviamos.
     */

    CURLOPT_POSTFIELDS => json_encode($datos),

    /*
     * Tiempo máximo de espera: 30 segundos.
     */

    CURLOPT_TIMEOUT => 30
]);


/*
 * 6. ENVIAR LA PREGUNTA Y RECIBIR LA RESPUESTA
 *
 * AQUÍ SE ENVÍA LA PREGUNTA.
 *
 * curl_exec() conecta con OpenAI y guarda
 * toda la respuesta recibida en $respuesta.
 */

$respuesta = curl_exec($curl);


/*
 * También guardamos el código HTTP.
 *
 * Por ejemplo:
 *
 * 200 = petición correcta
 * 401 = clave incorrecta
 * 429 = límite o saldo agotado
 */

$httpCode = curl_getinfo(
    $curl,
    CURLINFO_HTTP_CODE
);


/*
 * Si cURL no pudo conectarse, mostramos el error.
 */

if ($respuesta === false) {
    $error = curl_error($curl);

    curl_close($curl);

    exit("Error de conexión: $error\n");
}


/*
 * Cerramos la conexión cURL.
 */

curl_close($curl);


/*
 * 7. CONVERTIR LA RESPUESTA JSON EN UN ARRAY DE PHP
 *
 * OpenAI devuelve la información en formato JSON.
 * json_decode() la convierte en un array que PHP
 * puede consultar fácilmente.
 */

$json = json_decode($respuesta, true);


/*
 * Comprobamos si OpenAI devolvió algún error.
 */

if ($httpCode !== 200) {

    /*
     * Obtenemos el mensaje de error enviado
     * por la API.
     */

    $mensaje =
        $json['error']['message']
        ?? 'Error desconocido';

    exit("Error de la API: $mensaje\n");
}


/*
 * 8. EXTRAER LA RESPUESTA DE LA INTELIGENCIA ARTIFICIAL
 *
 * AQUÍ SE OBTIENE LA RESPUESTA.
 *
 * OpenAI guarda el texto contestado en:
 *
 * choices
 *   └── 0
 *       └── message
 *           └── content
 *
 * Por ejemplo, el contenido será:
 *
 * ANIMAL
 *
 * o:
 *
 * OBJETO
 */

$categoria = strtoupper(
    trim(
        $json['choices'][0]['message']['content']
        ?? ''
    )
);


/*
 * 9. TOMAR UNA DECISIÓN SEGÚN LA RESPUESTA
 *
 * Si la IA respondió ANIMAL, utilizamos animales.txt.
 *
 * Si respondió OBJETO, utilizamos objetos.txt.
 */

if ($categoria === 'ANIMAL') {

    $archivo = __DIR__ . '/animales.txt';

} elseif ($categoria === 'OBJETO') {

    $archivo = __DIR__ . '/objetos.txt';

} else {

    /*
     * Si la IA responde algo diferente,
     * detenemos el programa.
     */

    exit(
        "La IA no devolvió una categoría válida.\n"
    );
}


/*
 * 10. EJECUTAR LA ACCIÓN
 *
 * El agente guarda la palabra en el archivo elegido.
 *
 * FILE_APPEND:
 * Añade la palabra sin borrar las anteriores.
 *
 * LOCK_EX:
 * Bloquea temporalmente el archivo durante la escritura.
 */

file_put_contents(
    $archivo,
    $palabra . PHP_EOL,
    FILE_APPEND | LOCK_EX
);


/*
 * 11. MOSTRAR EL RESULTADO
 */

echo "$palabra → $categoria\n";

echo 'Guardado en '
    . basename($archivo)
    . PHP_EOL;

Cómo ejecutar el agente

Después de guardar el archivo, ejecutamos:

# Debemos indicar la KEY API, antes de lanzar el agente. (al menos 1 vez)
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxx"

php miniagente.php perro

El resultado debería ser parecido a este:

perro → ANIMAL
Guardado en animales.txt

Si ahora probamos con un objeto:

php miniagente.php mesa

Obtendremos:

mesa → OBJETO
Guardado en objetos.txt

Podemos revisar los archivos generados con los siguientes comandos:

cat animales.txt
cat objetos.txt

Cada nueva palabra se añadirá en una línea sin borrar las anteriores.

Solución al error «You have no credits remaining»

Al ejecutar el agente por primera vez, podemos encontrarnos con este mensaje:

Error de la API: You have no credits remaining. Add credits to continue 
using the API at https://platform.openai.com/settings/organization/billing/.

Este error no significa que el programa esté mal escrito. Normalmente indica que el agente ha conseguido conectarse con OpenAI y que la clave de la API ha sido reconocida, pero la cuenta no dispone de crédito para procesar la petición.

Para solucionarlo debemos seguir estos pasos:

Entrar en la sección de facturación de OpenAI Platform .
Añadir un método de pago si todavía no existe ninguno.
Pulsar la opción para añadir crédito al saldo de la API.
Para este ejemplo, seleccionar el importe mínimo permitido será suficiente.
Esperar unos minutos para que el saldo se active.
Ejecutar nuevamente el agente.

php miniagente.php perro

Es importante distinguir entre ChatGPT y la API de OpenAI. Aunque tengamos una suscripción de pago a ChatGPT, esta no incluye necesariamente saldo para consumir la API desde nuestros propios programas. Son servicios con facturación independiente.

Este miniagente consume muy pocos tokens, por lo que cada prueba tendrá un coste muy reducido. Aun así, la cuenta necesita disponer de crédito para que OpenAI acepte la petición.

Si después de añadir saldo el error continúa, conviene esperar unos minutos, comprobar que el crédito se añadió a la organización o al proyecto correctos y volver a intentarlo.

Cómo funciona el código PHP

El programa recoge la palabra desde la línea de órdenes mediante $argv[1] y obtiene la clave desde la variable de entorno OPENAI_API_KEY.

Después construye una petición en formato JSON. La instrucción enviada al modelo es muy concreta: debe clasificar la palabra y responder únicamente ANIMAL u OBJETO.

PHP envía la petición mediante cURL y comprueba que la API haya respondido correctamente. Finalmente, examina la categoría devuelta y utiliza file_put_contents() para guardar la palabra.

La opción FILE_APPEND añade el texto al final del archivo. La opción LOCK_EX evita que dos ejecuciones escriban simultáneamente y puedan interferirse.

¿Por qué esto ya puede considerarse un agente?

Nuestro programa es minúsculo, pero completa el ciclo básico de funcionamiento de un agente:

Recibe un objetivo: clasificar una palabra.
Utiliza inteligencia artificial: consulta un modelo para interpretarla.
Toma una decisión: animal u objeto.
Actúa: guarda la palabra en un archivo.

El modelo de inteligencia artificial no escribe directamente en nuestro sistema. Es el programa PHP el que controla las acciones permitidas.

Este detalle resulta fundamental al crear agentes más avanzados: la IA puede proponer o seleccionar una acción, pero nuestro código debe comprobar y limitar lo que realmente puede ejecutar.

Posibles mejoras para continuar aprendiendo

Una vez comprendido el ejemplo, podemos ampliarlo poco a poco:

Añadir categorías como alimentos, lugares o personas.
Evitar que una palabra se guarde repetida.
Registrar la fecha y la hora de cada clasificación.
Pedir confirmación cuando la palabra sea ambigua.
Utilizar una base de datos en lugar de archivos de texto.
Crear un formulario web para introducir las palabras.

No hace falta construir un sistema enorme para entender qué es un agente de IA. Con un solo archivo PHP podemos crear un programa que interpreta una entrada, toma una decisión mediante inteligencia artificial y ejecuta una acción concreta.

Este miniagente no pretende resolver un problema empresarial, sino mostrar el concepto de la forma más clara posible.

A partir de esta base podríamos crear agentes que clasifiquen correos, revisen documentos, organicen incidencias o interactúen con aplicaciones como un ERP o un gestor de contenidos.

La complejidad puede crecer tanto como necesitemos, pero el principio seguirá siendo el mismo: recibir, decidir y actuar.

No estás registrado para postear comentarios

JComments

Categoría: Inteligencia Artifical

LinuxParty