Esta es la implementación completa del ejemplo del artículo Construye tu primer agente de IA.
Si todavía no lo leíste, empieza allí. Aquí nos enfocamos en el código.
Qué demuestra este ejemplo
- Objetivo del agente: obtener del modelo un número mayor que 10
- Bucle: Act -> Check -> Retry (como máximo
MAX_STEPSveces) - Validación: el modelo puede devolver texto, una cadena vacía o un valor no numérico - el agente lo maneja
- Stop condition: el agente se detiene o por éxito, o por agotamiento de pasos
Estructura del proyecto
examples/
└── start-here/
└── write-your-first-agent/
└── python/
├── main.py # bucle del agente
├── llm.py # llamada al LLM (aislamiento de integración)
├── evaluator.py # verificación del resultado
└── requirements.txt
¿Por qué tres archivos y no uno? Porque en un agente real generación y evaluación casi siempre están separadas. Si quieres cambiar el modelo o la lógica de verificación, cambias un archivo sin tocar el resto.
Cómo ejecutarlo
1. Clona el repositorio y entra en la carpeta:
git clone https://github.com/AgentPatterns-tech/agentpatterns.git
cd examples/start-here/write-your-first-agent/python
2. Instala dependencias:
pip install -r requirements.txt
3. Define la API key:
export OPENAI_API_KEY="sk-..."
4. Ejecuta:
python main.py
Código
main.py - bucle del agente
from llm import generate_number
from evaluator import parse_int, is_goal_reached
GOAL = 10
MAX_STEPS = 5
def run():
for step in range(1, MAX_STEPS + 1):
print(f"\n🤖 Step {step}: Agent is trying...")
output = generate_number()
print(f"💬 Model generated: {output}")
number = parse_int(output)
if number is None:
print("❌ Not a number. Trying again...")
continue
if is_goal_reached(number, GOAL):
print(f"✅ Goal reached! {number} > {GOAL}")
return
print(f"❌ Not enough. {number} ≤ {GOAL}. Trying again...")
print("\n⚠️ Max steps reached without success")
if __name__ == "__main__":
run()
main.py no sabe nada sobre OpenAI. No sabe cómo parsear números. Solo controla el bucle - ese es el rol del agente.
llm.py - llamada al modelo
import os
from openai import OpenAI
api_key = os.environ.get("OPENAI_API_KEY")
client = OpenAI(api_key=api_key)
PROMPT = "Write ONLY a random number between 1 and 20. No text, no explanation."
def generate_number() -> str:
resp = client.responses.create(
model="gpt-4.1-mini",
input=PROMPT,
)
return resp.output_text.strip()
El modelo recibe una tarea y devuelve texto. No sabe que hay un agente, un objetivo, ni un límite de pasos. Solo genera.
evaluator.py - verificación del resultado
def parse_int(text: str) -> int | None:
"""Devuelve int o None si el texto no es un entero."""
try:
return int(text.strip())
except (ValueError, AttributeError):
return None
def is_goal_reached(number: int, goal: int) -> bool:
"""Devuelve True si el número cumple la condición."""
return number > goal
Dos preguntas pequeñas con respuestas claras: "¿es un número?" y "¿objetivo alcanzado?". Eso es todo.
requirements.txt
openai>=1.0.0
Ejemplo de salida
🤖 Step 1: Agent is trying...
💬 Model generated: 7
❌ Not enough. 7 ≤ 10. Trying again...
🤖 Step 2: Agent is trying...
💬 Model generated: 3
❌ Not enough. 3 ≤ 10. Trying again...
🤖 Step 3: Agent is trying...
💬 Model generated: 14
✅ Goal reached! 14 > 10
Por qué esto es un "agente" y no solo una función
| Función | Agente | |
|---|---|---|
| Cantidad de intentos | 1 | hasta MAX_STEPS |
| Verifica resultado | ❌ | ✅ |
| Decide si continuar o detenerse | ❌ | ✅ |
| Necesita participación humana entre pasos | — | ❌ |
Una llamada al modelo no es un agente.
Un bucle con verificación y decisión "intentar de nuevo o detenerse" sí es un agente.
Dónde profundizar después
Intenta modificar el ejemplo por tu cuenta:
- Cambia
GOAL = 10porGOAL = 19- ¿con qué frecuencia el agente alcanzará la meta dentro deMAX_STEPS? - Quita
MAX_STEPSy ponwhile True- ¿qué pasará? - Cambia el prompt para que el modelo genere números de 1 a 100 - ¿cómo impacta eso en el comportamiento del agente?
- Agrega un contador de llamadas API totales y muéstralo al final