Skip to content

README.es.md

Latest commit

 

History

History
184 lines (136 loc) · 5.92 KB

README.es.md

File metadata and controls

184 lines (136 loc) · 5.92 KB
Raw

AI agent with LM Studio

Agente local pequeño y reutilizable que llama directamente a la API HTTP de LM Studio. Puede conversar, cambiar de perfil y ejecutar herramientas sin usar el SDK de OpenAI.

Requisitos

  • Python 3.12 o posterior.
  • Poetry.
  • LM Studio con el servidor iniciado y un modelo cargado.
  • Una clave de LM Studio si la autenticación está activada.
  • Firecrawl sólo para los perfiles que usan búsqueda web.

Configuración

Copia .env.example como src/agent/.env y completa los valores privados. El archivo .env está ignorado por Git y no debe contenerse en commits.

LM_STUDIO_URL=http://localhost:1234/v1
LM_STUDIO_API_KEY=replace-with-your-key
LM_STUDIO_MODEL=replace-with-the-loaded-model-id

FIRECRAWL_URL=https://api.firecrawl.dev/v2/search
FIRECRAWL_API_KEY=replace-with-your-key

LM_STUDIO_URL normalmente usa HTTP en el servidor local de LM Studio. Usa HTTPS sólo cuando exista un proxy TLS real delante del servidor.

Firecrawl admite dos contratos de respuesta explícitos:

  • Una URL con /v1/ debe devolver data como lista.
  • Una URL con /v2/ debe devolver data.web como lista.

Una respuesta que no coincida con la versión de su URL se trata como error, no como una búsqueda vacía.

Ajustes opcionales

Variable Valor por defecto Uso
DEFAULT_AGENT research Perfil inicial
LM_STUDIO_TIMEOUT 120 Timeout de LM Studio en segundos
FIRECRAWL_TIMEOUT 30 Timeout de Firecrawl en segundos
HTTP_RETRIES 2 Reintentos para red, 429 y errores 5xx
MAX_TOOL_ROUNDS 5 Máximo de rondas de herramientas
MAX_HISTORY_MESSAGES 40 Límite orientativo del historial

Ejecución

El comando histórico sigue funcionando:

poetry run python src/agent/agent.py

También se puede ejecutar el paquete:

PYTHONPATH=src poetry run python -m agent

Selecciona un perfil inicial con:

poetry run python src/agent/agent.py --agent analyst

Comandos interactivos

/agents          listar perfiles
/agent NAME      cambiar de perfil y abrir una conversación nueva
/new             borrar la conversación actual
/history         mostrar la forma resumida del historial
/help            mostrar ayuda
/quit            salir

También puedes salir escribiendo exit, quit, q o bye, con o sin mayúsculas. Estos comandos se procesan localmente y no llaman a LM Studio.

Cambiar de perfil reinicia la conversación para que no se mezclen instrucciones de sistema incompatibles.

Perfiles incluidos

  • research: investigación web con fuentes obligatorias.
  • analyst: análisis que separa hechos, supuestos y conclusiones.
  • general: conversación local sin herramientas externas.
  • writer: redacción y reescritura con mayor variación creativa.

Cada perfil define sólo tres cosas: prompt de sistema, nombres de herramientas y parámetros de generación. Se encuentran en src/agent/profiles.py.

Flujo de una pregunta

  1. La CLI añade la pregunta al historial.
  2. El runner envía historial, perfil y herramientas a LM Studio.
  3. Si el modelo pide herramientas, Python valida y ejecuta cada llamada.
  4. Los resultados estructurados vuelven al historial con rol tool.
  5. LM Studio recibe el historial actualizado y decide buscar otra vez o responder.
  6. Al alcanzar el límite de herramientas se hace una última llamada sin tools, garantizando una oportunidad de síntesis.
  7. La CLI imprime una sola respuesta y conserva las interacciones más recientes.

El modelo nunca ejecuta Python por sí mismo. Sólo solicita herramientas mediante el protocolo; el dispatcher decide qué funciones están permitidas.

Estructura

src/agent/
├── agent.py         entrada compatible con el script original
├── __main__.py      entrada para `python -m agent`
├── cli.py           comandos y sesión interactiva
├── config.py        carga y validación del entorno
├── http_utils.py    POST JSON y reintentos limitados
├── lm_studio.py     transporte de chat con LM Studio
├── profiles.py      perfiles y parámetros de generación
├── runner.py        bucle modelo-herramienta-modelo
└── tools.py         schemas, Firecrawl y dispatcher

La implementación usa funciones y diccionarios. Los únicos objetos con ciclo de vida son los clientes de httpx, porque mantienen conexiones HTTP reutilizables.

Añadir un perfil

Añade una entrada a AGENT_PROFILES en profiles.py:

"translator": {
    "description": "Translation without external tools",
    "system_prompt": "Translate faithfully and preserve formatting.",
    "tool_names": [],
    "generation": {
        "temperature": 0.1,
        "top_p": 0.9,
        "max_tokens": 1600,
    },
},

No es necesario modificar el runner ni la CLI.

Añadir una herramienta

Una herramienta requiere tres cambios en tools.py:

  1. Añadir su schema a TOOL_DEFINITIONS.
  2. Escribir un handler con argumentos sencillos.
  3. Registrar el handler en TOOL_HANDLERS.

Después añade su nombre a los perfiles autorizados. Un nombre desconocido o un JSON inválido genera un resultado de error controlado para el modelo.

Errores y observabilidad

Cada turno muestra:

  • fase del bucle;
  • tiempo de respuesta;
  • finish_reason;
  • uso de tokens cuando LM Studio lo incluye;
  • mensajes y caracteres aproximados del historial;
  • nombre, estado y número de resultados de cada herramienta.

Los errores de configuración aparecen antes de iniciar la sesión. Los errores de herramientas se devuelven al modelo para que pueda explicarlos. La CLI revierte un intercambio fallido para no contaminar la siguiente pregunta. Nunca se imprimen las claves API.

Pruebas

poetry run pytest -q

Las pruebas no acceden a LM Studio ni Firecrawl. Usan transportes HTTP locales y cubren contratos v1/v2, autenticación, reintentos, herramientas, síntesis final, respuestas inválidas y poda del historial.