Función create_agent() de LangChain
create_agent() es la función más central de LangChain; crea un grafo de agente completo (StateGraph) que incluye toda la lógica de invocación del modelo, ejecución de herramientas, control de bucles, etc.
Sintaxis
La sintaxis de la función create_agent() es la siguiente:
from langchain.agents import create_agent
agent = create_agent(
model, # str | BaseChatModel：语言模型
tools=None, # Sequence：工具列表
*,
system_prompt=None, # str | SystemMessage：系统提示
middleware=(), # Sequence[AgentMiddleware]：中间件列表
response_format=None, # ResponseFormat | type：结构化输出配置
state_schema=None, # type[AgentState]：自定义状态结构
context_schema=None, # type：运行时上下文结构
checkpointer=None, # Checkpointer：对话持久化
store=None, # BaseStore：跨会话存储
interrupt_before=None, # list[str]：在哪些节点前暂停
interrupt_after=None, # list[str]：在哪些节点后暂停
debug=False, # bool：是否输出详细日志
name=None, # str：Agent 名称
cache=None, # BaseCache：缓存配置
)
Parámetro model: configuración del modelo
El parámetro model puede aceptar dos formas: una cadena (procesada por init_chat_model()) o una instancia BaseChatModel ya construida.
Ejemplo
from langchain.chat_models import init_chat_model
# Forma 1: pasar una cadena (la más común)
# create_agent llamará internamente a init_chat_model() para procesarla
agent = create_agent(
model="deepseek:deepseek-v4-flash",
system_prompt="Eres el asistente de EJEMPLO (Tutorial para novatos)",
)
# Forma 2: pasar una instancia de modelo ya construida
# Adecuado para escenarios que requieren un control fino de los parámetros del modelo
model = init_chat_model("deepseek:deepseek-v4-flash", temperature=0.3, max_tokens=500)
agent = create_agent(
model=model,
system_prompt="Eres el asistente de EJEMPLO (Tutorial para novatos)",
)
# Forma 3: pasar una instancia de modelo con herramientas ya vinculadas
# menos común; normalmente se deja que create_agent gestione la vinculación de herramientas
model_with_tools = init_chat_model("deepseek:deepseek-v4-flash").bind_tools([...])
Se recomienda usar la forma 1 (pasar una cadena). create_agent() maneja automáticamente la inicialización del modelo, la vinculación de herramientas y la salida estructurada. La forma 2 es adecuada si necesitas usar la misma instancia de modelo también fuera del agente.
Parámetro tools: lista de herramientas
El parámetro tools acepta herramientas en tres formatos:
Ejemplo
from langchain.agents import create_agent
# Formato 1: función decorada con @tool (la más común)
@tool
def search_course(keyword: str) -> str:
"""Buscar cursos del tutorial de EJEMPLO"""
return f"Resultados de búsqueda: cursos relacionados con {keyword}"
# Formato 2: clase Pydantic BaseModel
from pydantic import BaseModel, Field
class WeatherQuery(BaseModel):
"""Consultar el tiempo"""
city: str = Field(description="Nombre de la ciudad")
# Formato 3: diccionario (describe herramientas remotas o integradas)
mcp_tool = {
"type": "mcp",
"server_label": "weather_server",
"server_url": "https://weather.example.com/sse",
"allowed_tools": ["get_forecast"],
}
# Uso mixto
agent = create_agent(
model="deepseek:deepseek-v4-flash",
tools=[search_course, WeatherQuery, mcp_tool],
)
Pasar None o una lista vacía indica que el agente no tiene herramientas disponibles; en ese caso, es un modelo de conversación puro:
Ejemplo
from langchain.messages import HumanMessage
# Agente sin herramientas: equivalente a invocar el modelo directamente
agent = create_agent(
model="deepseek:deepseek-v4-flash",
tools=None,
system_prompt="Eres el asistente de EJEMPLO (Tutorial para novatos)",
)
result = agent.invoke({
"messages": [HumanMessage(content="¿Es Python adecuado para aprender desde cero?")]
})
print(result["messages"][-1].content)
Parámetro system_prompt: indicación del sistema
Define el rol de comportamiento y las reglas de restricción del agente. Admite cadenas y objetos SystemMessage.
Ejemplo
from langchain.messages import SystemMessage
# Forma 1: cadena (simple y directa)
agent = create_agent(
model="deepseek:deepseek-v4-flash",
system_prompt="Eres el asesor de aprendizaje de EJEMPLO. Responde de forma concisa, sin superar los 100 caracteres.",
)
# Forma 2: objeto SystemMessage (reutilizable entre varios agentes)
system_msg = SystemMessage(
content="Eres el asesor de aprendizaje de EJEMPLO. Responde de forma concisa, sin superar los 100 caracteres."
)
agent = create_agent(
model="deepseek:deepseek-v4-flash",
system_prompt=system_msg,
)
system_prompt es opcional, pero si no se pasa, el modelo responderá con el rol de "asistente general". Para aplicaciones con escenarios de negocio claros, se recomienda establecer siempre system_prompt para limitar el comportamiento del modelo.
Parámetro state_schema: estado personalizado
El AgentState predeterminado solo contiene messages, jump_to y structured_response. Si necesitas campos de estado adicionales, puedes extenderlo:
Ejemplo
from langchain.agents import create_agent, AgentState
from langchain.messages import HumanMessage
from langchain.tools import tool, InjectedState
from typing_extensions import TypedDict
# Extender AgentState y añadir campos personalizados
class LearningAgentState(AgentState):
"""Estado personalizado, con campos adicionales de progreso de aprendizaje"""
user_level: str # Nivel del usuario
completed_topics: list[str] # Lista de temas completados
@tool
def track_progress(
topic: str,
state: Annotated[dict, InjectedState],
) -> str:
"""Registra el progreso de aprendizaje del usuario.
Args:
topic: nombre del tema que acaba de completarse
"""
completed = state.get("completed_topics", [])
completed.append(topic)
return (
f"Progreso registrado. Temas completados actualmente: {len(completed)}:"
f"{', '.join(completed)}"
)
agent = create_agent(
model="deepseek:deepseek-v4-flash",
tools=[track_progress],
state_schema=LearningAgentState, # Usar estado personalizado
system_prompt="Eres el asistente de aprendizaje de EJEMPLO.",
)
# En tiempo de ejecución, se debe proporcionar el valor inicial del estado personalizado
result = agent.invoke({
"messages": [HumanMessage(content="He terminado los fundamentos de Python, regístralo para mí")],
"user_level": "Principiante",
"completed_topics": ["Fundamentos de HTML"],
})
print(f"Nivel de usuario: {result.get('user_level')}")
print(f"Temas completados: {result.get('completed_topics')}")
print(f"Respuesta: {result['messages'][-1].content[:100]}")
Resultado de la ejecución:
Nivel de usuario: 入门 Temas completados: ['HTML 基础', 'Python 基础'] Respuesta: Progreso de aprendizaje registrado. Temas completados: 2 (Fundamentos de HTML, Fundamentos de Python)
Valor de retorno: CompiledStateGraph
create_agent() devuelve unCompiledStateGraphobjeto, que es el grafo compilado de LangGraph y proporciona múltiples formas de ejecución:
| Método | Descripción | Escenario de uso |
|---|---|---|
| invoke(input, config) | Ejecución síncrona, espera el resultado completo | Scripts, interfaces sencillas |
| ainvoke(input, config) | Ejecución asíncrona, espera el resultado completo | Servicios web |
| stream(input, config, stream_mode) | Ejecución síncrona en streaming | Mostrar los pasos intermedios en tiempo real |
| astream(input, config, stream_mode) | Ejecución asíncrona en streaming | WebSocket、SSE |
| get_state(config) | Obtener el estado actual | Ver/restaurar el estado de la conversación |
| update_state(config, values) | Actualizar el estado | Modificar manualmente el estado de la conversación |