Curso
Trabajar con la API de OpenAI
3 h
126K
Introducción a los agentes de IA
Aprende los fundamentos de los agentes de IA, sus componentes y su uso en el mundo real, sin necesidad de programar.
2. Define la configuración del proyecto
Inicia Jupyter Notebook, crea una celda nueva y añade las importaciones necesarias y la configuración del proyecto.
import json
import os
import requests
from agents import Agent, AsyncOpenAI, ModelSettings, OpenAIChatCompletionsModel, RunConfig, Runner, function_tool, set_tracing_disabled
from IPython.display import Markdown, display
from pypdf import PdfReaderAhora define el nombre del modelo, los endpoints de las APIs, el máximo de turnos del agente, la ruta al CV y las preferencias de empleo.
KIMI_MODEL = "kimi-k2.6"
KIMI_BASE_URL = "https://api.moonshot.ai/v1"
OLOSTEP_SEARCH_URL = "https://api.olostep.com/v1/searches"
OLOSTEP_SCRAPE_URL = "https://api.olostep.com/v1/scrapes"
MAX_AGENT_TURNS = 25
cv_path = "abid-resume.pdf"
preferences = """
Remote data science, AI writer, or technical writer roles in AI, machine learning, data science, or cloud.
Prefer technical content, tutorials, developer education, research writing, and AI product storytelling.
""".strip()
set_tracing_disabled(True)Los valores de KIMI_MODEL y KIMI_BASE_URL indican a la app que use Kimi K2.6 a través del endpoint compatible con OpenAI de Moonshot AI. Las URLs de Olostep se utilizan para la búsqueda en vivo y el scraping de páginas.
La variable cv_path apunta al PDF del CV. Asegúrate de guardarlo en la misma carpeta del proyecto o actualiza la ruta si está en otra ubicación.
La variable preferences le indica al agente qué tipo de empleos debe buscar. Puedes modificarla según el puesto objetivo, sector, ubicación, nivel de seniority o modalidad de trabajo preferida.
Desactivamos el tracing con set_tracing_disabled(True) porque es una función del OpenAI Agents SDK que viene activada por defecto. Como en este proyecto usamos Kimi a través de un endpoint compatible con OpenAI, desactivarlo simplifica la configuración local y evita problemas de tracing con un proveedor externo.
3. Conecta con la API de Kimi K2.6
Después, configura el cliente de Kimi usando la clave de API que guardaste antes como variable de entorno.
kimi_client = AsyncOpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url=KIMI_BASE_URL,
)Esto crea el cliente de la API de Kimi. La api_key se carga desde MOONSHOT_API_KEY y el base_url apunta al endpoint compatible con OpenAI de Moonshot AI.
Luego, envuelve el modelo de Kimi para poder usarlo dentro del OpenAI Agents SDK:
kimi_model = OpenAIChatCompletionsModel(
model=KIMI_MODEL,
openai_client=kimi_client,
)Ahora define la configuración del modelo:
model_settings = ModelSettings(
tool_choice="auto",
parallel_tool_calls=True,
extra_body={"thinking": {"type": "disabled"}},
)El ajuste tool_choice="auto" permite que el agente decida cuándo llamar a las herramientas. Con parallel_tool_calls=True el agente puede ejecutar varias llamadas a herramientas en paralelo cuando sea necesario.
También desactivamos el modo de razonamiento de Kimi con extra_body={"thinking": {"type": "disabled"}}. Así el resultado es más limpio y adecuado para un informe de encaje estructurado.
Por último, crea la configuración de ejecución:
run_config = RunConfig(
workflow_name="JobFit AI Kimi Search",
tracing_disabled=True,
)El workflow_name da una etiqueta clara a esta ejecución. Mantenemos el tracing desactivado porque usamos Kimi a través de un endpoint compatible con OpenAI, no el backend de tracing de OpenAI.
4. Extrae texto del CV de la persona candidata
Ahora usa PdfReader para cargar el CV y extraer el texto de cada página.
reader = PdfReader(cv_path)
cv_text = "\n".join(page.extract_text() or "" for page in reader.pages)[:12000]
print(f"Loaded {len(cv_text):,} characters from {cv_path}")Este código lee el PDF definido en cv_path, extrae el texto de cada página y lo une en una sola cadena.
El límite [:12000] mantiene el texto del CV lo bastante corto para encajar bien en el prompt del agente, pero con suficiente contexto sobre experiencia, habilidades y preferencias.
La salida tendrá un aspecto similar a este, según el nombre y la longitud de tu archivo:
Loaded 2,946 characters from abid-resume.pdfEsto confirma que el CV se cargó correctamente y muestra cuántos caracteres se extrajeron del PDF.
5. Crea las instrucciones del agente
A continuación, define las instrucciones que controlan cómo debe buscar el agente, usar herramientas y dar formato al informe final.
AGENT_INSTRUCTIONS = """
You are JobFit AI, a focused job-search agent.
Tool plan:
- Call search_jobs exactly once with limit 8.
- Read at most 3 direct job pages with read_job_page.
- After reading up to 3 pages, stop using tools and write the report.
- Search again only if the first search returns zero usable jobs.
- Avoid broad search pages, expired jobs, and LinkedIn unless no better source exists.
Report rules:
- Keep the report simple, clear, and practical.
- Use short bullets.
- Do not use em dashes.
- Do not use contractions.
- Do not add text before or after the report.
- End after the final Job Notes entry.
- Include at least 5 ranked jobs if the search results contain at least 5 usable jobs.
- If only 3 pages were scraped, use backup jobs from search results when they look usable.
- Every job must include a clickable Markdown link.
- Every job must have one apply decision: Apply, Maybe, or Do not apply.
Use exactly this Markdown structure:
# JobFit AI Report
## Best Match
- **Role:** <job title>
- **Company:** <company>
- **Apply decision:** Apply / Maybe / Do not apply
- **Fit score:** <score>/100
- **Link:** [Apply here](<job url>)
**Why this is the best match:**
- <specific reason>
- <specific reason>
- <specific reason>
## Ranked Jobs
| Rank | Role | Company | Apply? | Fit | Link |
| --- | --- | --- | --- | --- | --- |
| 1 | <role> | <company> | Apply / Maybe / Do not apply | <score>/100 | [Apply here](<url>) |
## Job Notes
### 1. <Role> at <Company>
- **Apply decision:** Apply / Maybe / Do not apply
- **Fit score:** <score>/100
- **Link:** [Apply here](<job url>)
**Why it fits:**
- <bullet>
- <bullet>
**Concerns:**
- <bullet>
- <bullet>
**Application angle:**
- <how the person should position their CV/application>
""".strip()Estas instrucciones mantienen al agente centrado. Limitan el flujo a una búsqueda, hasta tres lecturas de páginas de empleo y una estructura fija de informe en Markdown.
Las normas del informe también facilitan el escaneo al exigir viñetas cortas, enlaces clicables, puntuaciones de encaje y una decisión clara de postulación para cada puesto.
6. Construye el prompt de ejecución
Tras definir las instrucciones del agente, crea la plantilla de prompt que se pasará al agente en cada ejecución.
RUN_PROMPT_TEMPLATE = """
Find current job postings for this candidate and rank them by fit.
Keep the run simple:
- one search
- up to three page reads
- final report
The final report must follow AGENT_INSTRUCTIONS exactly.
Use simple wording. Do not use em dashes. Do not use contractions.
Candidate CV:
{cv_text}
Preferences:
{preferences}
""".strip()Este prompt combina, en tiempo de ejecución, el texto del CV y las preferencias de empleo.
El marcador cv_text se rellena con el contenido extraído del CV, mientras que preferences se rellena con las preferencias definidas antes. En conjunto, aportan al agente el contexto necesario para buscar empleos relevantes y ordenarlos por encaje.
7. Añade búsqueda web en vivo con Olostep
Con las instrucciones del agente y el prompt listos, añade dos herramientas que permitan al agente buscar en la web y leer páginas de empleo usando Olostep.
La primera herramienta busca listados de empleo y devuelve una lista compacta de resultados.
@function_tool
def search_jobs(query: str, limit: int = 8) -> str:
"""Search the web for job listings and return compact JSON results."""
response = requests.post(
OLOSTEP_SEARCH_URL,
headers={"Authorization": f"Bearer {os.environ['OLOSTEP_API_KEY']}", "Content-Type": "application/json"},
json={"query": query},
timeout=60,
)
response.raise_for_status()
links = response.json().get("result", {}).get("links", [])[:limit]
results = [
{"title": item.get("title", "Untitled"), "url": item.get("url"), "description": item.get("description", "")}
for item in links
if isinstance(item, dict) and item.get("url")
]
return json.dumps(results, ensure_ascii=False)El decorador @function_tool expone esta función de Python al agente como una herramienta invocable.
Cuando el agente necesita listados, llama a search_jobs con una consulta. La función envía la consulta al endpoint de búsqueda de Olostep, recopila los primeros resultados y los devuelve como JSON.
Cada resultado incluye:
- título del puesto
- URL del puesto
- descripción breve
La segunda herramienta permite al agente abrir y leer una página concreta de empleo.
@function_tool
def read_job_page(url: str) -> str:
"""Scrape one job listing URL and return markdown text."""
response = requests.post(
OLOSTEP_SCRAPE_URL,
headers={"Authorization": f"Bearer {os.environ['OLOSTEP_API_KEY']}", "Content-Type": "application/json"},
json={"url_to_scrape": url, "formats": ["markdown"]},
timeout=120,
)
response.raise_for_status()
markdown = response.json().get("result", {}).get("markdown_content") or ""
return markdown[:8000]Esta función envía una URL de empleo al endpoint de scraping de Olostep y devuelve el contenido de la página en formato Markdown.
El límite [:8000] mantiene la página recopilada en un tamaño asumible para el agente y captura los detalles más útiles: responsabilidades, requisitos e información de la empresa.
8. Crea el agente JobFit AI
Ahora crea el agente y conecta todas las piezas definidas: el modelo de Kimi, la configuración del modelo, las herramientas de Olostep y las instrucciones del agente.
agent = Agent(
name="JobFit AI",
model=kimi_model,
model_settings=model_settings,
tools=[search_jobs, read_job_page],
instructions=AGENT_INSTRUCTIONS,
)El objeto Agent es el controlador principal de este flujo.
Utiliza:
kimi_modelcomo modelo de razonamientomodel_settingspara controlar el uso de herramientas y el comportamiento de salidasearch_jobspara encontrar ofertas en vivoread_job_pagepara hacer scraping de páginas seleccionadasAGENT_INSTRUCTIONSpara seguir las reglas exactas de búsqueda e informe
Llegados a este punto, el agente ya puede buscar empleos, compararlos con el CV y generar un informe estructurado de JobFit AI.
9. Ejecuta el flujo del agente
Ahora ejecuta el agente JobFit AI usando el texto extraído del CV y las preferencias definidas.
Primero, formatea el prompt de ejecución:
prompt = RUN_PROMPT_TEMPLATE.format(cv_text=cv_text, preferences=preferences)Esto rellena la plantilla con el CV de la persona candidata y sus preferencias objetivo.
Después, inicia la ejecución con streaming del agente:
print("Starting agent run")
result = Runner.run_streamed(
agent,
prompt,
max_turns=MAX_AGENT_TURNS,
run_config=run_config,
)El método Runner.run_streamed() inicia el flujo del agente y emite eventos en tiempo real. Así puedes ver cuándo llama a una herramienta, recibe su salida y crea el mensaje final.
Ahora añade el bucle de streaming:
async for event in result.stream_events():
if event.type == "agent_updated_stream_event":
print(f"Agent: {event.new_agent.name}")
elif event.type == "run_item_stream_event":
item = event.item
if event.name == "tool_called":
raw = item.raw_item
tool_name = raw.get("name") if isinstance(raw, dict) else getattr(raw, "name", "tool")
arguments = raw.get("arguments") if isinstance(raw, dict) else getattr(raw, "arguments", "")
arguments = str(arguments).replace(chr(10), " ")[:500]
print(f"Tool call: {tool_name}")
if arguments:
print(f"Parameters: {arguments}")
elif event.name == "tool_output":
print(f"Tool output: {len(str(item.output)):,} chars")
elif event.name == "message_output_created":
print("Final message ready")Este bucle imprime avances útiles mientras se ejecuta el agente. Por ejemplo, muestra cuándo busca empleos, lee una página o termina de generar el informe.
Por último, guarda la salida final en una variable llamada report:
report = result.final_output
globals()["report"] = report
print("Run complete")
print(f"Model responses: {len(result.raw_responses)}")
print(f"Run items: {len(result.new_items)}")
print(f"Final output: {len(str(report)):,} chars")La variable report almacena el informe final de JobFit AI, que puedes mostrar, guardar o usar en la app de Gradio.
La salida tendrá un aspecto parecido a este:
Starting agent run
Agent: JobFit AI
Tool call: search_jobs
Parameters: {"query":"remote data science writer technical writer AI machine learning content editor","limit":8}
Tool output: 2,445 chars
Tool call: read_job_page
Parameters: {"url":"https://www.indeed.com/q-data-science-writer-jobs.html"}
Tool output: 8,000 chars
Tool call: read_job_page
Parameters: {"url":"https://www.builtinnyc.com/jobs/remote/data-analytics/data-science"}
Tool output: 8,000 chars
Tool call: read_job_page
Parameters: {"url":"https://www.virtualvocations.com/jobs/q-data+scientist+remote+jobs/c-writing/d-336"}
Tool output: 5,075 chars
Final message ready
Run complete
Model responses: 5
Run items: 13
Final output: 5,931 charsEsto confirma que el agente buscó empleos, leyó páginas seleccionadas y generó correctamente el informe final.
10. Muestra el informe generado de JobFit
Cuando termine la ejecución del agente, muestra el informe final en formato Markdown.
display(Markdown(report))Esto renderiza el informe de JobFit AI directamente en el notebook, más cómodo de leer que el texto plano.
El informe incluye el mejor encaje, los puestos ordenados, las puntuaciones de encaje, las decisiones de postulación, las dudas y los enfoques para la candidatura.
11. Convierte el flujo en una app web con Gradio
Después de probar el flujo en el notebook, puedes convertirlo en una app web sencilla con Gradio. Crea un archivo app.py y copia el código de JobFit-AI/app.py del proyecto en GitHub en tu archivo local.
Ejecuta la app con:
python app.py
Luego abre la app local en tu navegador en la URL mostrada (en este caso, http://127.0.0.1:7860/):
La app de Gradio ofrece una interfaz sencilla para generar informes de encaje. Incluye:
- Un campo para subir el CV en PDF.
- Un cuadro de texto para las preferencias, donde describir tipo de puesto, sector, ubicación, seniority y temas preferidos.
- Un botón Generate JobFit Report para iniciar el flujo del agente.
- Un registro de progreso oculto que aparece durante la ejecución y muestra qué está haciendo la app: leer el CV, llamar herramientas y recibir resultados.
- Un área final en Markdown que muestra el informe ordenado cuando el agente termina.
En segundo plano, la app lee el CV subido, extrae el texto, envía el CV y las preferencias al agente de JobFit AI y busca ofertas en vivo con Olostep. Lee hasta tres páginas de empleo y devuelve un informe en Markdown con puestos ordenados, puntuaciones, decisiones de postulación, dudas y enfoques de candidatura.
12. Sube un CV y genera un informe
Prueba ahora la app web subiendo un PDF de CV o currículum y haciendo clic en Generate JobFit Report.
En este ejemplo, subí un CV con unos tres años de experiencia para comprobar si la app encontraba empleos relevantes según el perfil y las preferencias. El informe se generó en menos de un minuto.
Mientras la app se ejecuta, el registro de progreso muestra cada paso del flujo, entre ellos:
- lectura del CV
- extracción de texto de cada página
- inicio de la ejecución del agente
- llamada a la herramienta de búsqueda
- recepción de la salida de la herramienta
Al completarse la ejecución, la app muestra el informe final en Markdown.
El informe empieza con el mejor encaje, seguido de una tabla de puestos ordenados. Después aporta notas detalladas por puesto, incluyendo puntuación de encaje, decisión de postulación, motivos del encaje, posibles dudas y un enfoque para la candidatura.
En este ejemplo, el primer resultado fue un puesto de Senior Data Science Writer en NannyML. Como el puesto encajaba con el bagaje en data science, redacción técnica y contenidos de IA de la persona candidata, parecía una gran opción.
Puedes hacer clic en el enlace Apply here del informe para abrir la página del puesto y revisar la oferta completa antes de decidir si postular.
Nota: si tienes algún problema ejecutando el proyecto en local, consulta el repositorio de GitHub: kingabzpro/JobFit-AI. Incluye el notebook, el archivo app.py y las instrucciones de instalación para configurar dependencias y ejecutar el proyecto en tu equipo.
Reflexiones finales
JobFit AI utiliza Kimi K2.6, Olostep y el OpenAI Agent SDK para resolver dos problemas habituales de quienes cambian de rol o están activamente postulando.
El primer problema es saber dónde postular. Hay muchos portales y páginas de empleo de empresas, pero no siempre está claro qué ofertas merecen la pena. Esta app lo acota usando el CV y las preferencias para encontrar puestos más alineados con la experiencia.
El segundo problema es filtrar un exceso de listados. En lugar de revisar manualmente cada portal, el agente busca ofertas en vivo, lee páginas seleccionadas y crea un informe estructurado con mejor encaje, puestos ordenados, puntuaciones, dudas y enfoques de candidatura. Así puedes centrarte en los roles que realmente merece la pena solicitar.
La API de Kimi K2.6 también rindió muy bien en este flujo con agentes: fue rápida, estable y siguió con eficacia instrucciones estructuradas. En pruebas, permitiendo hasta 25 turnos, el agente buscó y recopiló más páginas en profundidad, pero la ejecución tardó unos cinco minutos. Para equilibrar calidad y velocidad, limité el flujo a una búsqueda y hasta tres lecturas, generando el informe en menos de un minuto.
Puedes mejorar la calidad del informe aumentando el número de pasos, resultados de búsqueda o páginas leídas. Por ejemplo, si subes el límite del agente a 30 turnos y le permites leer más páginas, obtendrás un informe más profundo con más roles y recomendaciones más sólidas. Eso sí, aumentará el tiempo de ejecución y el uso de la API.
Si te interesa crear herramientas agentic similares, echa un vistazo a otros tutoriales de API para construir:
