Introducción: en esta guía práctica aprenderás a construir agentes de inteligencia artificial que usan herramientas, toman decisiones y realizan acciones ejecutándose localmente en tu máquina. Al final tendrás un agente que entiende lenguaje natural, decide qué herramientas usar, ejecuta funciones de forma automática y devuelve respuestas inteligentes. Ejemplo de interacción: Usuario: Saluda a Alicia y luego calcula 150 + 75. Agente: piensa que debe usar la herramienta greet y la herramienta add, llama greet con nombre Alicia y add con 150 y 75, y responde Hola Alicia Bienvenida La suma de 150 y 75 es 225
Qué es la IA agentica: un agente IA es un modelo que no solo genera texto sino que puede invocar funciones externas o herramientas para obtener resultados precisos y actualizados. En vez de confiar solo en su conocimiento interno, el agente decide cuándo y cómo llamar a herramientas como calculadoras, bases de datos, APIs o utilidades locales y combina los resultados para ofrecer una respuesta coherente
Antecedentes esenciales: Ollama es una plataforma que facilita ejecutar modelos de lenguaje localmente parecido a ejecutar contenedores ligeros para modelos IA. Permite descargar modelos con un comando, ejecutarlos sin conexión y sin claves de API. Tool calling es la capacidad del modelo para reconocer que necesita una herramienta, elegir la correcta, formar parámetros válidos y luego interpretar los resultados. MCP Model Context Protocol es un estándar para conectar modelos con herramientas y datos de forma uniforme; FastMCP es una librería Python que simplifica crear servidores MCP que exponen herramientas
Visión de arquitectura: en tu equipo tendrás tres componentes principales Ollama que actúa como cerebro IA, un cliente Python que orquesta las conversaciones y un servidor MCP que expone las herramientas reales. El flujo es usuario cliente Ollama decide usar herramientas cliente ejecuta herramientas en el servidor MCP cliente devuelve resultados a Ollama y Ollama genera la respuesta final
Instalación de Ollama pasos resumidos para Linux macOS Windows instalar Ollama Linux curl -fsSL https://ollama.ai/install.sh | sh macOS brew install ollama Windows descargar desde el sitio oficial verificar instalacion ollama --version iniciar servidor ollama serve mantener terminal abierta descargar modelo ejemplo ollama pull llama3.2 probar modelo ollama run llama3.2 y chatear para comprobar funcionamiento
Modelos y compatibilidad con llamadas a herramientas no todos los modelos soportan tool calling Modelos compatibles ejemplo llama3.2 recomendado rápido ligeros mistral qwen2.5 multilingue Mod models que no soportan tools ejemplo codellama llama2 phi si usas un modelo sin soporte recibirás error de tipo does not support tools
Preparación del proyecto crea directorio proyecto mkdir mcp-ollama-tutorial crea entorno virtual python -m venv myenv activa entorno source myenv/bin/activate instala dependencias pip install fastmcp ollama requests verifica python -c import fastmcp import ollama print All packages installed
Creando el servidor MCP conceptos y pseudo codigo ejemplo de herramientas registradas usando FastMCP import fastmcp crear instancia mcp = FastMCP Nombre del servidor definir herramienta add mcp.tool def add(a int b int) => int descripcion Add two numbers together return a + b definir greet mcp.tool def greet(name str) => str return Hello name Welcome definir multiply mcp.tool def multiply(a float b float) => float return a * b definir get_time mcp.tool def get_time() => str return current datetime formato iniciar servidor mcp.run transport sse port 8080
Explicacion del servidor cada funcion decorada se expone automaticamente via HTTP FastMCP genera esquemas JSON que el modelo lee para saber parametros tipos y descripciones
Cliente Ollama y flujo de trabajo general pasos clave descubrimiento de herramientas consulta al servidor MCP para listar herramientas conversacion inicial se envian las herramientas a Ollama en formato de funciones el modelo decide si usar herramientas ejecucion de herramientas el cliente llama al servidor MCP por cada tool_call y recoge resultados retorno final se envian los resultados a Ollama para que genere la respuesta natural
Pseudo codigo cliente resumen cargar herramientas async load_mcp_tools conecta MCP lista tools convertir al formato esperado por Ollama ejecutar herramienta async execute_tool llama MCP call_tool y retorna resultado loop principal preparar mensaje del usuario enviar a ollama con tools si la respuesta contiene tool_calls ejecutar cada llamada agregar respuestas de herramienta al hilo y volver a consultar a Ollama para obtener la respuesta final
Ejecutando el sistema varios terminales Terminal 1 iniciar servidor MCP python mcp_server.py Terminal 2 iniciar Ollama ollama serve Terminal 3 ejecutar cliente python client_ollama.py salida esperada indica carga de herramientas ejecucion de greet y add y la respuesta final agregada por Ollama
Desglose detallado del flujo de peticiones user cliente obtiene lista de herramientas cliente envía mensaje y definiciones de herramientas a Ollama Ollama devuelve tool_calls cliente ejecuta cada tool mediante llamadas MCP cliente reenvía resultados a Ollama Ollama genera respuesta natural y cliente la muestra al usuario
Esquema de la magia de los esquemas de herramientas el modelo entiende las herramientas porque el cliente suministra estructuras con tipo function name description y parameters donde parameters es un esquema JSON que describe tipos propiedades y campos requeridos
Personalizando y ampliando ejemplos de herramientas nuevas meteorologia añadir get_weather ciudad retorna texto con datos de ejemplo operaciones con archivos save_note title content guarda nota en carpeta notes list_notes retorna listado de notas herramientas de base de datos search_users name retorna lista de usuarios coincidentes con demo
Guía de resolucion de problemas cinco problemas comunes 1 modelo no soporta herramientas error does not support tools solucion usar un modelo compatible ollama pull llama3.2 2 no se conecta al servidor MCP connection refused solucion asegurarse de ejecutar python mcp_server.py comprobar puerto y cambiar si es necesario 3 comando ollama no encontrado reinstalar Ollama segun sistema 4 IA no llama herramientas sintomas responde directamente soluciones ser explicito en el prompt mejorar descripciones de herramientas usar un modelo más potente 5 errores de import ModuleNotFoundError activar entorno virtual y reinstalar dependencias pip install fastmcp ollama requests
Seis ideas de proyectos reales con implementacion de herramientas y pila tecnologica 1 Asistente de correo gestionar enviar buscar marcar leidos herramientas send_email search_emails mark_as_read pila Gmail API OAuth SQLite cache 2 Base de conocimiento personal guardar buscar resumir documentos herramientas save_note search_notes summarize_document pila vectores ChromaDB PyPDF2 embeddings 3 Gestor financiero registrar transacciones generar informes establecer presupuestos herramientas add_transaction get_spending_report set_budget check_budget_status pila SQLite Pandas Matplotlib 4 Controlador domotico controlar luces termostato camaras crear escenas herramientas control_light set_thermostat get_camera_feed create_scene pila Home Assistant MQTT webhooks 5 Asistente de analisis de datos cargar describir crear graficos buscar correlaciones exportar reportes herramientas load_dataset describe_data create_chart find_correlations export_report pila Pandas Plotly Scipy 6 Asistente de estudio flashcards y quizes crear flashcard start_quiz record_answer get_weak_topics summarize_textbook pila algoritmo spaced repetition NLP parsing de PDFs
Implementaciones de ejemplo y buenas practicas para produccion añadir autenticacion al servidor MCP con llaves API cifrado TLS registro y monitorizacion limitar tasas usar Docker para desplegar y tests automatizados para validar herramientas y esquemas
Recomendaciones practicas para prompts y diseño de herramientas crear descripciones claras y concisas incluir tipos y ejemplos en los esquemas forzar validacion de argumentos en el servidor y manejar errores para que el modelo reciba respuestas estructuradas
Siguientes pasos sugeridos explorar distintos modelos ollama pull mistral ollama pull qwen2.5 probar streaming habilitar respuesta en tiempo real con stream true securizar servidor MCP con API keys y autenticar peticiones ampliar sistema con multiples agentes especializados y pipelines para tareas complejas
Sobre Q2BSTUDIO y como te podemos ayudar Q2BSTUDIO es una empresa de desarrollo de software y aplicaciones a medida especializada en inteligencia artificial ciberseguridad y servicios cloud AWS y Azure Ofrecemos soluciones personalizadas de software a medida e IA para empresas que quieren integrar agentes IA y automatizacion avanzada Podremos acompañarte desde la arquitectura hasta la puesta en produccion incluyendo seguridad y escalabilidad Si buscas desarrollo de aplicaciones a medida visita nuestra pagina de servicios de software a medida desarrollo de aplicaciones multiplataforma y si tu interes es desplegar modelos y herramientas en la nube consulta nuestros servicios cloud en servicios cloud AWS y Azure
Palabras clave integradas para SEO aplicaciones a medida software a medida inteligencia artificial ciberseguridad servicios cloud aws azure servicios inteligencia de negocio ia para empresas agentes IA power bi
Recursos y lecturas recomendadas documentacion Ollama FastMCP especificacion MCP ejemplos de implementacion y repositorios oficiales dedicar tiempo a leer la documentacion y experimentar localmente es la mejor forma de aprender
Conclusión has aprendido los conceptos y pasos para construir un agente IA local usando Ollama y un servidor MCP con FastMCP has visto arquitectura instalacion configuracion de servidor y cliente extensiones practicas y proyectos reales para aplicar esta tecnologia en casos de uso empresariales Si quieres que Q2BSTUDIO te ayude a llevar un prototipo a produccion contactanos para evaluar requerimientos y proponer una solución a medida
Invitacion final comparte tus proyectos y preguntas en la comunidad y considera seguir explorando patrones de agentes multiagente y servicios gestionados de IA para empresas para potenciar tus soluciones con capacidades avanzadas de inteligencia artificial