Esencial⏱ 25 minVS Code / Cursor

Creá un agente con herramientas

Ejecutar solo funciones permitidas.

datetime

Antes de comenzar

🎯 Qué vas a lograr en esta lección

¿Qué problema vas a resolver?

Aprenderás a ejecutar solo funciones permitidas. La idea es partir de una necesidad concreta, no de memorizar código.

¿Qué vas a construir?

Tool Routing Agent: un proyecto pequeño para crear una aplicación que consulta documentos o usa herramientas. El nombre técnico identifica la carpeta del proyecto; no necesitás memorizarlo.

¿Por qué es útil?

Te ayuda a obtener respuestas basadas en información disponible y no solo en memoria del modelo.

¿Qué vas a aprender?

Practicarás fragmentos, búsqueda, fuentes, herramientas y aprobación humana. Cada término nuevo se explica antes de usarlo.

Tu primera acción

No instalés ni ejecutes nada todavía. Primero lee las palabras esenciales y observa el ejemplo pequeño. Después identificarás qué dato entra, qué instrucción trabaja y qué resultado aparece.

Cómo usar esta lección

Avanza una parte a la vez

Aprende

Leé las palabras nuevas y el ejemplo pequeño.

Practica

Cambiá una sola cosa y ejecuta nuevamente.

Comprueba

Respondé las preguntas y usa las pistas cuando las necesites.

Cierra

Marcá el checklist y decide si continuar o tomar una pausa.

No necesitás entender toda la página de una vez. Termina una parte, haz una pausa breve y continúa cuando estés listo.

Parte 1

Aprende las palabras esenciales

Leé definiciones cortas y explica cada palabra con un ejemplo propio.

Base conceptual — léela antes de practicar

🧱 Conceptos esenciales explicados desde cero

Esta sección no es opcional. Presenta las palabras y procesos que necesitás para comprender el ejemplo. Leé una definición, observa el ejemplo y explícalo con una frase propia antes de avanzar.

`agente`

Qué significa: Sistema que selecciona herramientas o pasos para alcanzar un objetivo.

Para qué sirve: Permite encadenar decisiones y acciones controladas.

Ejemplo: Elegir entre buscar, calcular o solicitar aprobación.

Confusión frecuente: Un agente necesita límites; no debe tener permisos ilimitados.

`herramienta`

Qué significa: Función externa que un agente puede invocar.

Para qué sirve: Le permite actuar o consultar.

Ejemplo: search_docs().

Confusión frecuente: Debe limitarse con allowlist.

`routing`

Qué significa: Decisión sobre qué ruta o herramienta usar.

Para qué sirve: Dirige una solicitud.

Ejemplo: Pregunta documental→RAG.

Confusión frecuente: Debe tener fallback.

`estado`

Qué significa: Información actual de un sistema u objeto.

Para qué sirve: Determina comportamiento.

Ejemplo: pending/completed.

Confusión frecuente: Cambios deben controlarse.

`allowlist`

Qué significa: Lista explícita de acciones permitidas.

Para qué sirve: Reduce superficie de riesgo.

Ejemplo: Solo read/search.

Confusión frecuente: Es más segura que permitir todo.

Ejemplo mínimo de flujo RAG

Este ejemplo es deliberadamente pequeño. Su objetivo es mostrar las piezas básicas sin mezclar todavía toda la lógica del proyecto.

pregunta = "¿Cómo instalo el proyecto?"
fragmentos = buscar_documentos(pregunta)
respuesta = responder_con_fuentes(pregunta, fragmentos)

Identificá los nombres nuevos: subraya variables, funciones, tipos, herramientas o pasos.
Señala la entrada: qué dato recibe o qué valor ya está escrito.
Señala el proceso: qué instrucción transforma, valida, consulta o calcula.
Señala la salida: qué resultado puede verse o verificarse.
Explícalo: completa “el programa recibe ___, hace ___ y entrega ___”.

No continués todavía si no podés explicar al menos tres términos y el flujo entrada → proceso → salida sin copiar el texto.

Aprende las palabras antes de usarlas

🧠 Conceptos explicados desde cero

No memoricés los nombres. Leé qué significa cada término, observa el ejemplo y trata de explicarlo con tus propias palabras.

`tools`

Qué significa: tools es un término técnico utilizado en esta lección.

Para qué sirve: Nombrar una parte específica del proceso de tools.

Ejemplo pequeño: Busca tools en el ejemplo y observa qué recibe y qué produce.

Confusión frecuente: No intentés memorizar el nombre: explicá primero su función con tus propias palabras.

`routing`

Qué significa: routing es un término técnico utilizado en esta lección.

Para qué sirve: Nombrar una parte específica del proceso de routing.

Ejemplo pequeño: Busca routing en el ejemplo y observa qué recibe y qué produce.

Confusión frecuente: No intentés memorizar el nombre: explicá primero su función con tus propias palabras.

`allowlist`

Qué significa: allowlist es un término técnico utilizado en esta lección.

Para qué sirve: Nombrar una parte específica del proceso de allowlist.

Ejemplo pequeño: Busca allowlist en el ejemplo y observa qué recibe y qué produce.

Confusión frecuente: No intentés memorizar el nombre: explicá primero su función con tus propias palabras.

`arguments`

Qué significa: arguments es un término técnico utilizado en esta lección.

Para qué sirve: Nombrar una parte específica del proceso de arguments.

Ejemplo pequeño: Busca arguments en el ejemplo y observa qué recibe y qué produce.

Confusión frecuente: No intentés memorizar el nombre: explicá primero su función con tus propias palabras.

Parte 2

Mirá un ejemplo pequeño

Primero comprende un ejemplo mínimo. Después observa el código completo.

Ejemplo pequeño antes del proyecto

Relacionar una pregunta con un documento

Observá únicamente tres cosas: qué dato existe, qué instrucción se ejecuta y qué resultado aparece.

document = "Python se usa para automatización."
question = "¿Para qué se usa Python?"
print(document, question)

Resultado explicado: RAG añade después búsqueda y generación; primero comprende documento y pregunta.

Antes de continuar, responde con tus palabras:

¿Qué dato recibe o ya tiene el ejemplo?
¿Qué instrucción realiza el trabajo?
¿Qué resultado podés observar?

⌨️ Código completo

from datetime import date

def today() -> str:
    return date.today().isoformat()

def total(values: list[float]) -> float:
    return round(sum(values),2)

tools = {"today":today,"total":total}

def run_tool(name: str,arguments: dict) -> object:
    if name not in tools:
        raise ValueError("Herramienta no permitida")
    return tools[name](**arguments)

print(run_tool("today",{}))
print(run_tool("total",{"values":[12.5,8,4.25]}))

Código README Desafío

Editar y ejecutar en el navegador

Hacé un cambio pequeño y ejecuta. Este entorno no modifica los archivos descargados.

from datetime import date

def today() -> str:
    return date.today().isoformat()

def total(values: list[float]) -> float:
    return round(sum(values),2)

tools = {"today":today,"total":total}

def run_tool(name: str,arguments: dict) -> object:
    if name not in tools:
        raise ValueError("Herramienta no permitida")
    return tools[name](**arguments)

print(run_tool("today",{}))
print(run_tool("total",{"values":[12.5,8,4.25]}))

Python todavía no cargado

El resultado aparecerá aquí.

Primero entiende el ejemplo

🖼️ Explicación ilustrada: entrada → proceso → resultado

Piensa en una máquina sencilla: colocas algo en la entrada, la máquina aplica un proceso y entrega un resultado.

Situación

Una persona necesita resolver el problema de «crea un agente con herramientas».

Entrada

El programa recibe datos, instrucciones o archivos relacionados con microproyecto.

Proceso

El código valida la entrada, aplica reglas mediante funciones y prepara una respuesta.

Resultado

El usuario recibe un resultado visible que puede comprobar y comparar.

Ejemplo antes y después

Antes

Antes de ejecutar: solo tenemos datos y una necesidad.

Después

Después de ejecutar: tenemos un resultado producido por pasos identificables.

¿Cómo usarás este ejemplo en el mini proyecto?

Ahora practicarás con un mini proyecto. Primero observarás el ejemplo, después cambiarás una sola parte y finalmente explicarás el resultado.

1. ObservarVer el ejemplo

2. EntenderRelacionar datos y resultado

3. CambiarModificar una sola cosa

4. EjecutarComprobar el resultado

5. ExplicarDecir qué aprendiste

Regla: cambia una sola parte, ejecuta de nuevo y explica qué diferencia observaste. No necesitás reconstruir el proyecto completo.

Parte 3

Practica con un mini proyecto

Hacé un cambio pequeño, ejecuta el código y observa qué cambió.

Practica paso a paso

🧩 Mini proyecto guiado: Creá un agente con herramientas

Completá estos ejercicios pequeños antes del desafío. Podés equivocarte: el sistema te explicará qué repasar y te dará una pista.

En esta lección aparece tools. ¿Cuál es la mejor forma de aprenderlo?

Memorizar el nombre sin ver el ejemplo. Explicar qué recibe, para qué sirve y qué resultado produce. Saltarlo y modificar todo el proyecto.

Querés practicar con el código de Creá un agente con herramientas. ¿Qué cambio es mejor para comenzar?

Borrar varias líneas sin ejecutar primero. Cambiar un texto o dato de ejemplo, ejecutar y comparar el resultado. Copiar una solución diferente sin leerla.

Después de modificar un dato, ¿qué tenés que hacer para saber si aprendiste correctamente?

Suponer que funciona porque no ves errores en el editor. Guardar, ejecutar y comparar la salida anterior con la nueva. Cambiar otras cinco cosas antes de ejecutar.

Tarea: abre el editor del navegador o el archivo completo. Cambiá un solo dato visible, ejecútalo y observa qué parte del resultado cambió.

Cambié un único valor. Ejecuté el programa después del cambio. Puedo explicar qué cambió en el resultado.

Completé los tres pasos y puedo explicarlos. Todavía no ejecuté o no entiendo el resultado.

Progreso del mini proyecto

Completá los cuatro pasos.

🧪 Error controlado

Solicita una herramienta inexistente y revisa el bloqueo.

🤖 Cursor

Explica este proyecto como tutor.
Describe entrada, procesamiento y salida.
Revisa una función por vez.
No cambies el código sin mi autorización.
Después hazme cinco preguntas.

Antes de ejecutar el proyecto

🖥️ Cómo abrir y ejecutar este proyecto, paso a paso

¿Qué significa “ejecutar”?

Ejecutar un proyecto significa pedirle a Python que lea las instrucciones guardadas en sus archivos y realice el trabajo. No modifica tu computadora completa: trabaja dentro de la carpeta del proyecto.

En estas instrucciones utilizarás la terminal, una ventana donde escribís comandos. Un comando es una instrucción corta para la computadora.

Antes de comenzar, confirma estas cuatro cosas

Descargaste y descomprimiste el proyecto. Un ZIP es una carpeta comprimida. Tenés que abrirlo para obtener una carpeta normal.
Abriste la carpeta del proyecto. Dentro deberían aparecer archivos como main.py, requirements.txt y README.md.
Python está instalado. Esto se prepara en el Nivel 00.
La terminal está ubicada en esa carpeta. Si la terminal está en otra carpeta, Python no encontrará main.py.

Terminal

Ventana donde escribís comandos. En macOS se llama Terminal; en Windows podés usar PowerShell.

Lo aprendés en: Nivel 00 · Qué necesitás para empezar a programar.

Carpeta del proyecto

Carpeta que contiene todos los archivos relacionados. Los comandos deben ejecutarse desde esta ubicación.

Lo aprendés en: Nivel 00 · Qué necesitás para empezar a programar.

Entorno virtual (`.venv`)

Una carpeta privada para las librerías de este proyecto. Evitá mezclar herramientas de proyectos diferentes.

Lo aprendés en: Nivel 00 · Entornos virtuales, debugging y diagnóstico.

`pip`

Herramienta de Python para instalar librerías. Una librería es código preparado por otras personas para resolver tareas comunes.

Lo aprendés en: Nivel 00 · Entornos virtuales, debugging y diagnóstico.

`requirements.txt`

Archivo de texto que enumera las librerías necesarias. pip lo lee para instalar las versiones requeridas.

Lo aprendés en: Nivel 00 · Entornos virtuales, debugging y diagnóstico.

`main.py`

Archivo de inicio habitual. El nombre puede cambiar en proyectos avanzados, pero aquí suele contener el flujo principal.

Lo practicas desde: Nivel 01 · Tu primer proyecto con variables.

Escoge únicamente tu sistema operativo

No ejecutés las dos rutas. Usá macOS si trabajás en una Mac o Windows si utilizás PowerShell.

macOS · Terminal zsh

Abrí Terminal dentro de la carpeta del proyecto.
Una forma sencilla es abrir la carpeta en Finder, escribir cd en Terminal, arrastrar la carpeta a la ventana y presionar Enter.
```
pwd
ls
```
Resultado esperado: pwd muestra la ruta de la carpeta y ls muestra main.py.
Creá el entorno virtual.
```
python3 -m venv .venv
```
python3 abre Python. -m venv pide crear un entorno virtual. .venv es el nombre de la nueva carpeta.
Resultado esperado: aparece una carpeta llamada .venv. El comando puede terminar sin mostrar texto.
Activá el entorno.
```
source .venv/bin/activate
```
Activar significa indicar que los siguientes comandos deben utilizar el Python privado del proyecto.
Resultado esperado: la terminal suele mostrar (.venv) al inicio de la línea.
Instalá las librerías del proyecto.
```
python -m pip install -r requirements.txt
```
python -m pip abre el instalador de librerías. -r requirements.txt le indica qué lista debe leer.
Resultado esperado: aparecen mensajes de instalación o se indica que las librerías ya están instaladas.
Ejecutá el archivo principal.
```
python main.py
```
Python abre main.py, lee sus instrucciones de arriba hacia abajo y muestra el resultado.
Resultado esperado: verás el resultado descrito en la sección “Resultado” de esta lección.

Windows · PowerShell

Abrí PowerShell dentro de la carpeta del proyecto.
En el Explorador de archivos, abrí la carpeta, hacé clic en la barra de dirección, escribí powershell y presioná Enter.
```
Get-Location
dir
```
Resultado esperado: Get-Location muestra la carpeta actual y dir muestra main.py.
Creá el entorno virtual.
```
python -m venv .venv
```
python abre Python. -m venv crea el entorno y .venv es el nombre de la carpeta.
Resultado esperado: aparece una carpeta llamada .venv.
Activá el entorno.
```
.venv\Scripts\Activate.ps1
```
PowerShell empieza a utilizar el Python privado de este proyecto.
Resultado esperado: aparece (.venv) al inicio de la línea. Si PowerShell bloquea el archivo, repasa la lección de entornos virtuales antes de cambiar políticas de seguridad.
Instalá las librerías.
```
python -m pip install -r requirements.txt
```
pip lee la lista y prepara las herramientas que utiliza el proyecto.
Resultado esperado: aparecen mensajes de instalación o confirmación.
Ejecutá el archivo principal.
```
python main.py
```
Python abre y ejecuta las instrucciones de main.py.
Resultado esperado: verás el resultado descrito en esta lección.

¿Cómo sé que estoy en la carpeta correcta?

Tenés que poder ver main.py al ejecutar ls en macOS o dir en Windows.

¿Cómo detengo un programa?

Los scripts pequeños terminan solos. Si un servidor continúa funcionando, presiona Control + C.

¿Qué hago si dice que falta un archivo?

Revisá la carpeta actual. El error suele indicar que la terminal no está ubicada donde guardaste el proyecto.

¿Debo repetir todo cada vez?

El entorno se crea e instala una vez. En una sesión nueva normalmente solo activas .venv y ejecutás python main.py.

Términos que aparecerán más adelante

API

Forma organizada para que dos programas intercambien solicitudes y respuestas.

Lo vas a aprender en: Nivel 04 · Consume tu primera API.

FastAPI

Librería de Python para crear APIs y servidores web. Sus proyectos se ejecutan con un comando diferente a python main.py.

Lo vas a aprender en: Nivel 06 · Crea tu primera API.

Docker

Herramienta que empaqueta una aplicación junto con su configuración para ejecutarla de forma consistente en otras computadoras.

Lo vas a aprender en: Nivel 10 · Empaqueta una API con Docker.

Notebook

Documento interactivo que combina pequeños bloques de código, resultados y explicaciones. Es común en análisis de datos.

En este curso: es un recurso opcional. No necesitás usar notebooks para completar las lecciones actuales. Consulta la introducción a notebooks cuando aparezca el término.

Herramienta externa

Programa o servicio que no forma parte de Python, por ejemplo una base de datos, navegador, servicio de nube o modelo de IA.

Regla: no la instales ni ejecutes hasta llegar a la lección que la explica y revisar su README.

🧩 Tres niveles de desafío

Esencial: cambia un dato y verifica el resultado.
Práctica: agrega validación y un mensaje de error claro.
Avanzado: separa responsabilidades, añade pruebas y documenta la arquitectura.

Aprende comprobando

🧪 Comprobaciones programando

Ejecutá un caso controlado y deja que el código compruebe condiciones importantes.

1. Caso normalUsá datos comunes.

2. Valor límiteProbá cero, vacío, máximo o mínimo.

3. Error esperadoComprobá que el mensaje ayude a corregirlo.

response = {
    "answer": "Respuesta de ejemplo",
    "sources": ["documento-1"],
}

assert response["answer"].strip()
assert isinstance(response["sources"], list)
assert response["sources"]

print("✅ Estructura válida")

Qué estás aprendiendo: La prueba valida estructura, campos obligatorios y fuentes sin gastar créditos.

Después de ejecutarlo

¿Qué condición comprueba cada assert?
¿Qué cambio hace fallar la comprobación?
¿El mensaje explica qué tenés que corregir?
¿Podés agregar otro caso?

Parte 4

Comprobá lo que entendiste

Respondé una pregunta a la vez. Podés usar pistas y volver a intentarlo.

Evaluación online

❓ Comprueba lo que entendiste

Respondé sobre Creá un agente con herramientas. Verás una explicación completa y podrás intentarlo nuevamente.

Pregunta 1 de 5 · Selección

¿Cuál describe mejor la entrada principal?

respuesta con citas o aviso de evidencia insuficiente los documentos, pregunta y metadatos el sistema divide, indexa, recupera contexto y genera respuesta

Pregunta 2 de 5 · Selección

¿Qué describe mejor el procesamiento?

los documentos, pregunta y metadatos el sistema divide, indexa, recupera contexto y genera respuesta respuesta con citas o aviso de evidencia insuficiente

Pregunta 3 de 5 · Selección

¿Qué error esperado debería manejarse?

Ninguno; si funciona una vez siempre funcionará. recuperación irrelevante, cita incorrecta o herramienta no autorizada Ocultar cualquier error sin informar.

Pregunta 4 de 5 · Respuesta breve

¿Cómo comprobarías que el resultado es correcto?

Pregunta 5 de 5 · Respuesta breve

¿Qué mejora convertiría este microproyecto en una pieza de portafolio más sólida?

Resultado de la evaluación

Completá las cinco preguntas.

Parte 5

Cerrá la lección

Resume lo aprendido, completa el checklist y decide tu siguiente paso.

📝 Resumen

Ejecutaste una referencia funcional.
Identificaste entrada, procesamiento y salida.
Modificaste un comportamiento.
Provocaste y reparaste un error.
Preparaste una mejora para GitHub.

✅ Checklist

Ejecuté la referencia. Expliqué el flujo. Reparé el error. Reconstruí el proyecto. Preparé GitHub.Puedo definir las palabras nuevas principales y explicar el ejemplo mínimo sin copiarlo.

Cómo podrás mejorar este proyecto

🚀 Mejoras futuras y dónde las aprenderás

No son obligatorias ahora. Son mejoras que aplicarás cuando aprendas las herramientas correspondientes.

Separar la configuración del código

Qué mejora: Evita editar el programa cuando cambia una ruta, clave o preferencia.

Dónde lo aprenderás: en la lección «Protege tokens con .env», del nivel APIs y servicios externos.

Añadir pruebas automatizadas

Qué mejora: Comprueba que una modificación no rompa lo existente.

Dónde lo aprenderás: en la lección «Escribe pruebas unitarias», del nivel Testing y despliegue.

Registrar la ejecución

Qué mejora: Ayuda a entender fallos sin imprimir datos sensibles.

Dónde lo aprenderás: en la lección «Configura observabilidad», del nivel Testing y despliegue.

Mejorar mensajes y validación

Qué mejora: Explica qué dato falta y cómo corregirlo.

Dónde lo aprenderás: en la lección «Entrada de datos segura», del nivel Fundamentos de Python.

Documentar decisiones y limitaciones

Qué mejora: Permite que otra persona comprenda y evalúe el proyecto.

Dónde lo aprenderás: en la lección «Construye casos de estudio», del nivel Portafolio profesional.

Crear una demostración

Qué mejora: Muestra el problema, funcionamiento y evidencia.

Dónde lo aprenderás: en la lección «Crea un índice HTML», del nivel Portafolio profesional.

Creá un agente con herramientas

🎯 Qué vas a lograr en esta lección

¿Qué problema vas a resolver?

¿Qué vas a construir?

¿Por qué es útil?

¿Qué vas a aprender?

Tu primera acción

Avanza una parte a la vez

Aprende las palabras esenciales

🧱 Conceptos esenciales explicados desde cero

agente

herramienta

routing

estado

allowlist

Ejemplo mínimo de flujo RAG

🧠 Conceptos explicados desde cero

tools

routing

allowlist

arguments

Mirá un ejemplo pequeño

Relacionar una pregunta con un documento

⌨️ Código completo

🖼️ Explicación ilustrada: entrada → proceso → resultado

Situación

Entrada

Proceso

Resultado

Ejemplo antes y después

¿Cómo usarás este ejemplo en el mini proyecto?

Practica con un mini proyecto

🧩 Mini proyecto guiado: Creá un agente con herramientas

Reconoce una palabra nueva

Hacé un cambio seguro

Comprobá lo que ocurrió

Tu mini proyecto

Progreso del mini proyecto

🎉 ¡Mini proyecto completado!

🧪 Error controlado

🤖 Cursor

🖥️ Cómo abrir y ejecutar este proyecto, paso a paso

¿Qué significa “ejecutar”?

Antes de comenzar, confirma estas cuatro cosas

Terminal

Carpeta del proyecto

Entorno virtual (.venv)

pip

requirements.txt

main.py

Escoge únicamente tu sistema operativo

macOS · Terminal zsh

Windows · PowerShell

¿Cómo sé que estoy en la carpeta correcta?

¿Cómo detengo un programa?

¿Qué hago si dice que falta un archivo?

¿Debo repetir todo cada vez?

API

FastAPI

Docker

Notebook

Herramienta externa

🧩 Tres niveles de desafío

🧪 Comprobaciones programando

Después de ejecutarlo

Comprobá lo que entendiste

❓ Comprueba lo que entendiste

¿Cuál describe mejor la entrada principal?

¿Qué describe mejor el procesamiento?

¿Qué error esperado debería manejarse?

Resultado de la evaluación

Cerrá la lección

📝 Resumen

✅ Checklist

🚀 Mejoras futuras y dónde las aprenderás

Separar la configuración del código

Añadir pruebas automatizadas

Registrar la ejecución

Mejorar mensajes y validación

Documentar decisiones y limitaciones

`agente`

`herramienta`

`routing`

`estado`

`allowlist`

`tools`

`routing`

`allowlist`

`arguments`

Entorno virtual (`.venv`)

`pip`

`requirements.txt`

`main.py`