Notas prácticas: Una guía de campo para arquitecturas multiagente
Guía paso a paso práctica: Una guía de campo para arquitecturas multiagente: contratos, verificaciones y espacios para código reutilizable para los equipos que implementan este patrón.
Esta guía reconstruye el proceso desde las materias primas hasta un sistema funcional para: Una guía de campo sobre arquitecturas multiagente. El enfoque está en pasos operativos, verificaciones explícitas y código que se puede incorporar a un repositorio sin tener que adivinar su propósito. En la etapa de visión general, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
1. Sistemas Hierárquicos Multiagente
Al trabajar en la etapa 1 de Sistemas Multiagente Jerárquicos, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Haga un punto de control después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
from fundamental_analysis_tools import evaluate_fundamentals
from langchain.agents import create_agent
from technical_analysis_tools import technical_analysis
agent = create_agent(
model=llm,
tools=[technical_analysis, evaluate_fundamentals]
)
Supervisor
├── Technical Analysis Tool
└── Fundamental Analysis Tool
Supervisor
├── Technical Analyst Agent
│ ├── Tool A
│ ├── Tool B
│ └── ...
└── Fundamental Analyst Agent
├── Tool C
├── Tool D
└── ...
from langchain.tools import tool
from langgraph_supervisor import create_supervisor
@tool
def get_weather(city: str) -> str:
"""Use this tool to get the weather of a city or location"""
return f"The weather is sunny in {city}"
weather_expert = create_agent(
model=llm,
tools=[get_weather],
name="weather_expert"
)
technical_analyst_agent = create_agent(
model=llm,
tools=[technical_analysis],
name="technical_analyst"
)
fundamental_analyst_agent = create_agent(
model=llm,
tools=[evaluate_fundamentals],
name="fundamental_analyst"
)
analysis_squad = create_supervisor(
[technical_analyst_agent, fundamental_analyst_agent],
model=llm,
supervisor_name="analysis_supervisor",
prompt=(
"You are a team supervisor managing a fundamental analyst and a "
"technical analyst..."
)
)
analysis_app = analysis_squad.compile(
name="fundamental_and_technical_analyst"
)
supervisor_graph = create_supervisor(
[analysis_app, weather_expert],
model=llm,
prompt=(
"You are a team supervisor managing a fundamental analyst, a "
"technical analyst and a weather expert..."
)
)
supervisor = supervisor_graph.compile()
¿Cuándo debería usar una arquitectura jerárquica?
Al trabajar en la sección “¿Cuándo debería usarse una etapa?”, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones en el código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
2. Flujos de trabajo explícitos con múltiples agentes
Al trabajar en la etapa 2 de Multiagente Explícito, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta de éxito como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior. Al trabajar en la etapa 2 de Multiagente Explícito, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
def execute_plan(
plan: Plan,
state: State,
) -> Command[
Literal[
"fundamental_analysis_agent",
"technical_analysis_agent",
"respond",
]
]:
gotos = [
Send(
step.action.agent_to_use,
{"query": step.action.query_to_send},
)
for step in plan.steps
]
if not gotos:
gotos.append(
Send("respond", {"messages": state["messages"]})
)
return Command(goto=gotos)
def router(state: State) -> Command[
Literal["fundamental_analysis_agent", "technical_analysis_agent", "respond"]
]:
# Get plan
query = state['messages'][-1].content
response = llm_planner.invoke(query) #invoke planner
return execute_plan(response, state)
Cuándo usar flujos de trabajo de multiagente explícito
El enfoque de “cuándo usar la etapa explícita” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Mantenga el estado del gráfico simple y con tipos definidos; los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso.
3. Agent Swarm
La etapa de 3 Agent Swarm funciona mejor cuando se trata como una superficie medible. Capture un registro dorado, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
from langgraph_swarm import (
create_handoff_tool,
create_swarm,
)
## We'll have to redefine our all agents to include the handoff tool
weather_expert = create_agent(
model=llm,
tools=[
get_weather,
create_handoff_tool(
agent_name="technical_analyst",
description="Transfer for technical analysis related questions"
),
create_handoff_tool(
agent_name="fundamental_analyst",
description="Transfer for fundamental analysis related questions"
),
],
name="weather_expert"
)
technical_analyst_agent = ...
fundamental_analyst_agent = ...
swarm_workflow = create_swarm(
[fundamental_analyst_agent, technical_analyst_agent, weather_expert],
default_active_agent="weather_expert" #a default agent must be specified.
)
swarm = swarm_workflow.compile()
¿Cuándo debería usar un swarm?
El enfoque “¿Cuándo deberías usar esta etapa?” funciona mejor cuando se trata como una superficie medible. Captura un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documenta tanto el camino óptimo como el de recuperación. Los intentos repetidos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente. Mantén el estado de los gráficos simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso. El enfoque “¿Cuándo deberías usar esta etapa?” funciona mejor cuando se trata como una superficie medible. Captura un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considera esta etapa como un contrato entre las entradas y las salidas validadas. Nombra los artefactos, define las verificaciones de éxito y rechaza las completaciones parciales silenciosas.
4. Sistemas Multiagente de Blackboard
Para la fase 4 de Blackboard Multi Agent, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Implemente la aprobación humana en aquellos casos en que se gasten fondos o se modifiquen datos de producción. La conexión durante la compilación no equivale a una solución completa desde el punto de vista empresarial.
a. La pizarra
En la etapa de la pizarra, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso desde un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Coloque la aprobación humana en las conexiones que generan gastos o modifican datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
class Blackboard(TypedDict, total=False):
query: str
# Problem frame
problem_framed: bool
ticker: str | None
location: str | None
wants_technical: bool
wants_fundamental: bool
# Specialist panels
technical: dict | None
fundamental: dict | None
environmental: dict | None
# Integrated solution
synthesis: str | None
# Control state
next_knowledge_source: str | None
cycles: int
b. Fuentes de conocimiento
En la fase de fuentes de conocimiento, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Incluya la aprobación humana en aquellos casos en que se gasten fondos o se modifiquen datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial. En la fase de fuentes de conocimiento, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Considere esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
def can_analyse_technicals(board: Blackboard) -> bool:
return (
board.get("ticker") is not None
and board.get("wants_technical", False)
and board.get("technical") is None
)
c. El componente de control
Al trabajar en la fase del c Componente de control, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Haga una verificación después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
def control_component(board: Blackboard) -> dict:
eligible = [
source
for source in KNOWLEDGE_SOURCES #these are subagents
if source.precondition(board)
]
if not eligible:
return {"next_knowledge_source": None}
chosen = max(
eligible,
key=lambda source: source.priority,
)
return {
"next_knowledge_source": chosen.name,
"cycles": board.get("cycles", 0) + 1,
}
inspect → identify eligible specialists → activate one
→ contribute → inspect again
La ejecución es deliberadamente secuencial
Cuando se trabaja en la fase de ejecución secuencial, primero escribe el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Mantén la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Haz una verificación después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
¿Cuándo deberías usar una arquitectura de pizarra negra?
Al trabajar en la etapa de “¿Cuándo deberías usarlo?”, anota primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documenta junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Haz un punto de control después de los pasos costosos. Resume no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior. Al trabajar en la etapa de “¿Cuándo deberías usarlo?”, anota primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Considera esta etapa como un contrato entre los datos de entrada y los resultados validados. Nombra los artefactos, define las verificaciones de éxito y rechaza las completaciones parciales silenciosas.
5. Sistemas Multiagente Actor-Critic (Adversariales)
El método de 5 etapas adversarial Actor-Critic funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Mantenga el estado del grafo plano y con tipos definidos; los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso.
actor → critic → judge
↑ |
└──── revise ─────┘
a. El Actor
El escenario del Actor funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
def actor(state: AdversarialState) -> dict:
if state.get("latest_critique") is None:
prompt = f"Produce a first draft.\n\nTASK: {state['task']}"
else:
prompt = (
"Revise the current draft.\n\n"
f"TASK:\n{state['task']}\n\n"
f"CURRENT DRAFT:\n{state['draft']}\n\n"
f"CRITIQUE:\n{state['latest_critique']}\n\n"
f"JUDGE'S PRIORITY:\n{state['latest_verdict']['focus']}"
)
draft = llm.invoke(prompt).content
return {
"draft": draft,
"round": state.get("round", 0) + 1,
}
b. El crítico
La etapa de crítica funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Los intentos repetidos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente. Mantenga el estado de los gráficos simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso. La etapa de crítica funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
class Issue(BaseModel):
severity: Literal["blocking", "major", "minor"]
description: str
class Critique(BaseModel):
issues: list[Issue]
summary: str
def weighted_issue_score(issues: list[dict]) -> int:
weights = {
"blocking": 5,
"major": 2,
"minor": 1,
}
return sum(
weights[issue["severity"]]
for issue in issues
)
c. El juez
En la fase de juicio, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Implemente la aprobación humana en aquellos casos en que se gastan fondos o se modifican datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
class Verdict(BaseModel):
decision: Literal["accept", "revise"]
reasoning: str
focus: str
def judge(state: AdversarialState) -> dict:
verdict = llm.with_structured_output(Verdict).invoke(
[
HumanMessage(
content=(
"Evaluate the critic's findings on their merits. "
"Accept if only minor issues remain. "
"Request revision only for blocking or material problems.\n\n"
f"DRAFT:\n{state['draft']}\n\n"
f"CRITIQUE:\n{state['latest_critique']}"
)
)
]
)
return {
"latest_verdict": verdict.model_dump(),
}
Por qué sigue siendo necesario un vigilante
Para determinar por qué un watchdog se encuentra en una etapa específica, defina las entradas, el responsable de esa etapa y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la etapa a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Coloque la aprobación humana en aquellos procesos que implican gastos o modificaciones en los datos de producción. La conexión establecida en tiempo de compilación no equivale a la completitud del proceso empresarial.
round 1: 12
round 2: 8
round 3: 8
round 4: 9
def watchdog(state: AdversarialState) -> dict:
round_number = state.get("round", 0)
scores = state.get("issue_counts", [])
if round_number >= HARD_ROUND_CAP:
return {
"halt_reason": "hard round cap reached",
}
if len(scores) >= STALEMATE_WINDOW:
window = scores[-STALEMATE_WINDOW:]
if window[-1] >= window[0]:
return {
"halt_reason": (
f"stalemate detected: {window}"
),
}
return {}
La finalización debe distinguir entre éxito y agotamiento
Para la finalización es necesario distinguir la etapa de éxito, definir las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en los datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial. Para la finalización es necesario distinguir la etapa de éxito, definir las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina las verificaciones de éxito y rechace las completaciones parciales silenciosas.
¿Cuándo debería usar una arquitectura adversarial?
Al abordar la etapa de “¿Cuándo debería usarla?”, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones en el código. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Haga un punto de control después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Elegir una arquitectura
Al trabajar en la fase de Elección de arquitectura, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
Pensamientos finales
Al trabajar en la etapa de Reflexiones Finales, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Haga una verificación después de los pasos costosos. El sistema de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior. Al trabajar en la etapa de Reflexiones Finales, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta etapa como un contrato entre los datos de entrada y los resultados validados. Asigne nombres a los artefactos, defina las verificaciones de éxito y rechace las completaciones parciales silenciosas.
Lista de verificación operativa
La etapa de lista de verificación operativa funciona mejor cuando se trata como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance.
Preferir unidades pequeñas y verificables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad en lugar de a un proceso complicado.
Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y dificultan la reanudación después de interrupciones.
Agregue una prueba básica que ejerza la ruta crítica en CI con fixtures, y no con APIs pagadas en tiempo real, siempre que lo permitan los presupuestos.
Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace completaciones parciales silenciosas.
Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y dificultan la reanudación después de interrupciones.
Antes de promocionar el conjunto de herramientas, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos para revertir cambios. Los entornos compartidos requieren límites de velocidad, verificaciones de asignación y un responsable claro para la rotación de credenciales secretas. Prefiera una fiabilidad sólida a demostraciones ingeniosas pero puntuales.
Nota para el lote f6f8c689c406: mantenga las claves del proveedor fuera del repositorio, establezca un límite para tokens por sesión y almacene las transcripciones junto a los archivos de prueba para que los cambios en los modelos posteriores sigan siendo comparables.
Lecturas relacionadas
- Notas prácticas: IA agente con LangChain — Parte 7: Construyendo Multi-Agent — Guía paso a paso de las Notas prácticas: IA agente con LangChain — Parte 7: Construyendo Multi-Agent, incluyendo contratos, verificaciones y espacios de código listos para usar por parte de los equipos que implementan este patrón.