Crear un agente con la API de Python
En esta página
Tu primer agente de Mistral
Las tres lecciones anteriores han establecido el vocabulario; esta te pone manos a la obra. Crearás un agente mediante la API de Python, enriqueciéndolo progresivamente con instrucciones, parámetros de generación y herramientas, para luego iniciar una conversación con él. La progresión es intencionadamente incremental: cada añadido modifica un comportamiento observable, mostrándote por qué el mismo método create() puede producir tanto un asistente genérico como un experto con un estilo estrictamente delimitado.
Prerrequisitos
La instalación consta de dos pasos. Primero, el SDK oficial.
pip install mistralai
A continuación, haz que tu clave de API esté disponible en el entorno en lugar de codificarla directamente en tu código. Confirmar accidentalmente una clave en un repositorio es el primer incidente de seguridad en cualquier proyecto de LLM.
export MISTRAL_API_KEY="your-api-key"
Después, construyes el cliente en una sola línea. Este objeto client sirve como punto de entrada para el resto de la lección.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Crear un agente mínimo
El método client.beta.agents.create() acepta tres parámetros obligatorios y varios opcionales. Empecemos con lo estrictamente necesario.
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="Simple Assistant",
description="A conversational agent with persistent state."
)
print(f"Agent created: {agent.id}")
Este agente es minimalista: sin instrucciones específicas, sin herramientas, sin barreras de seguridad. Se comporta como un endpoint de Chat Completions mejorado con persistencia. Observa el identificador devuelto en agent.id: esto es lo que debes almacenar en el lado de la aplicación, ya que es la única referencia estable a esta configuración.
Definir el comportamiento con instrucciones
Las instrucciones actúan como el prompt del sistema y son la palanca principal para controlar el comportamiento. El ejemplo siguiente transforma un asistente genérico en un experto legal cuyo alcance, formato y límites están explícitamente acotados.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Legal Expert",
description="Agent specialized in French business law.",
instructions="""You are an expert in French business law.
Rules:
- Always respond in French
- Cite relevant legal articles
- Specify when a question requires a lawyer's opinion
- Structure your responses with headings and lists
- Never give definitive legal advice"""
)
Observa la estructura de este prompt: una definición del rol al inicio, seguida de reglas numeradas. Esta organización por secciones ayuda al modelo a priorizar las restricciones. Sé específico con el rol, el tono y los límites en lugar de escribir simplemente «sé útil». Sobre todo, anticipa los casos límite: ¿qué debe hacer el agente si la pregunta queda fuera de su dominio? La línea sobre consultar la opinión de un abogado aborda esto con precisión. Por último, trata las instrucciones como código: las probarás y revisarás varias veces antes de que produzcan el comportamiento esperado.
Controlar la generación
Los completion_args configuran el muestreador, es decir, cómo el modelo elige sus palabras. Un agente encargado de reiterar hechos no necesita la misma libertad que un agente de lluvia de ideas.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Precise Agent",
description="Agent with controlled generation parameters.",
instructions="Respond factually and concisely.",
completion_args={
"temperature": 0.2, # Less creativity, more precision
"top_p": 0.9, # Probability nucleus
"max_tokens": 2048 # Response length limit
}
)
temperature: oscila entre 0,0 (determinista) y 1,0 (creativo). Para tareas factuales, prefiere valores entre 0,1 y 0,3.top_p: filtrado de probabilidad acumulativa. 0,9 es un buen valor por defecto.max_tokens: límite estricto en los tokens de salida.
Dotar al agente de herramientas
Un agente se vuelve realmente autónomo cuando puede actuar más allá del texto. La siguiente configuración le otorga tanto acceso a la web como ejecución de código: ante una pregunta que compare las tasas actuales, recuperará los valores y calculará el resultado sin tu intervención.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Research Agent",
description="Agent with web search and code execution.",
instructions="Use web search for current information and code for calculations.",
tools=[
{"type": "web_search"},
{"type": "code_interpreter"}
],
completion_args={"temperature": 0.3, "top_p": 0.95}
)
Las herramientas disponibles incluyen: web_search, web_search_premium, code_interpreter, image_generation, document_library.
Gestionar el ciclo de vida del agente
Tus agentes son recursos persistentes en el lado de Mistral y los administrarás como cualquier otro recurso: localizarlos, modificarlos, eliminarlos. Listarlos es especialmente útil durante el desarrollo, donde rápidamente acabas con decenas de agentes de prueba cuyos IDs has perdido.
# List all your agents
agents = client.beta.agents.list()
for a in agents.data:
print(f"{a.name} ({a.id})")
# Retrieve an agent by its ID
agent = client.beta.agents.get(agent_id="ag-xxxxxxxx")
Las actualizaciones son parciales: solo se modifican los campos proporcionados; los demás permanecen como están. Esto te permite refinar las instrucciones en producción sin redeclarar toda la configuración.
agent = client.beta.agents.update(
agent_id=agent.id,
instructions="New updated instructions.",
tools=[{"type": "web_search"}, {"type": "code_interpreter"}]
)
La eliminación, sin embargo, es permanente.
client.beta.agents.delete(agent_id=agent.id)
Ejemplo completo
Vamos a unir todo en un agente totalmente funcional: creación, conversación y lectura de la respuesta. Puedes usar este script tal cual; solo cambia el nombre y las instrucciones, y tendrás tu propio analista operativo en minutos.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Create the agent
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Tech Analyst",
description="Analyzes technology trends with web sources.",
instructions="""You are a technology analyst.
- Use web search for recent data
- Always cite your sources
- Structure your analyses into key points""",
tools=[{"type": "web_search"}],
completion_args={"temperature": 0.3}
)
# Start a conversation
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="What are the latest advancements in agentic AI in 2026?"
)
# Display the response
for entry in response.outputs:
if hasattr(entry, "content"):
print(entry.content)
El bucle final merece un momento de atención: itera sobre response.outputs en lugar de leer un único campo porque un agente equipado con herramientas produce múltiples entradas: la ejecución de la búsqueda y, luego, el texto. Este es el punto clave que debes vigilar en la siguiente lección.
Puntos clave
client.beta.agents.create()crea un agente con modelo, nombre y descripción (obligatorios).- Las instrucciones definen el comportamiento: esta es la palanca principal.
completion_argscontrolan la generación (temperature, top_p, max_tokens).- Un agente puede tener múltiples herramientas habilitadas simultáneamente.
- Los agentes son configuraciones reutilizables, no instancias de conversación.