Skip to content

Self-improving AI Employees for everyone

feat(temporal): orchestrator-side AgentWorkflow dispatch + prepare_payload activity (F4.B per-agent wiring)

trohitg04591315ad84
diff --git a/server/services/temporal/agent_activities.py b/server/services/temporal/agent_activities.py
index 480336ab..2606c0f5 100644
--- a/server/services/temporal/agent_activities.py
+++ b/server/services/temporal/agent_activities.py
@@ -320,12 +320,261 @@ async def compact_agent_memory(payload: Dict[str, Any]) -> Dict[str, Any]:
return result
[email protected](name="agent.prepare_payload.v1")
+async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:
+ """Resolve everything ``AgentWorkflow`` needs from the canvas + DB.
+
+ The workflow itself cannot do DB lookups or LangChain tool builds
+ (deterministic-replay constraint). This activity runs *before* the
+ workflow is scheduled and returns the fully-resolved payload.
+
+ Mirrors the prep half of ``services.ai.AIService.execute_agent``,
+ minus the LangGraph loop (which now lives in ``AgentWorkflow.run``):
+
+ 1. Read node parameters from DB via ``database.get_node_parameters``.
+ 2. Walk edges via ``services.plugin.edge_walker.collect_agent_connections``
+ for ``memory_data``, ``skill_data``, ``tool_data``, ``input_data``.
+ 3. Resolve api_key / proxy from ``auth_service``.
+ 4. Resolve max_tokens / temperature / thinking config via the
+ model-registry helpers.
+ 5. Build tool schemas — call ``AIService._build_tool_from_node`` per
+ tool entry and serialise each ``StructuredTool.args_schema``
+ Pydantic class to a JSON-schema dict (so the workflow can pass
+ it back into the LLM activity for ``bind_tools``).
+ 6. Compose ``system_message`` (skill prompt injection + delegation
+ contract).
+
+ ``context`` shape (same as the legacy execute_node_activity context)::
+
+ {
+ "node_id": str,
+ "node_type": str,
+ "node_data": dict, # node parameters from canvas
+ "workflow_id": str,
+ "session_id": str,
+ "nodes": list, # full canvas (for edge walking)
+ "edges": list,
+ "inputs": dict, # upstream node outputs
+ }
+
+ Returns the dict that ``AgentWorkflow.run`` expects (see its
+ docstring for the canonical shape).
+
+ Falls back gracefully when fields are missing — agents with no
+ connected tools / skills / memory still produce a valid payload
+ that AgentWorkflow can run.
+ """
+ activity.logger.info(
+ f"Preparing AgentWorkflow payload for {context.get('node_type')!r} "
+ f"node_id={context.get('node_id')!r}"
+ )
+
+ # Lazy imports — keep agent_activities.py top-level light so the
+ # worker can register this activity without dragging the whole
+ # AI service in for every plugin.
+ from core.container import container
+ from services.ai import AIService, _resolve_max_tokens, _resolve_temperature
+ from services.ai import ThinkingConfig, get_default_model_async, is_model_valid_for_provider
+ from services.plugin.edge_walker import collect_agent_connections
+
+ node_id = context["node_id"]
+ node_type = context["node_type"]
+ workflow_id = context.get("workflow_id")
+ session_id = context.get("session_id", "default")
+
+ database = container.database()
+ auth = container.auth_service()
+ ai_service = AIService()
+
+ # ---- Node parameters ------------------------------------------------
+ # The orchestrator passes context["node_data"] but DB has the
+ # authoritative version (UI saves edit -> DB; node_data is a
+ # snapshot at scheduling time). Prefer DB for liveness.
+ db_params = await database.get_node_parameters(node_id) or {}
+ parameters = {**(context.get("node_data") or {}), **db_params}
+
+ options = parameters.get("options") or {}
+ flattened = {**parameters, **options}
+
+ prompt = parameters.get("prompt", "")
+ system_message = parameters.get("system_message") or "You are a helpful assistant"
+
+ api_key = flattened.get("api_key")
+ provider = parameters.get("provider", "openai")
+ model = parameters.get("model", "")
+ if isinstance(model, str) and model.startswith("[FREE] "):
+ model = model[7:]
+
+ if not model or not is_model_valid_for_provider(model, provider):
+ model = await get_default_model_async(provider, database)
+
+ if not api_key:
+ # Try auth_service one more time (covers chatAgent flow where
+ # node params don't carry the api_key directly).
+ api_key = await auth.get_api_key(provider) or await auth.get_api_key(f"{provider}_api_key")
+ if not api_key:
+ raise RuntimeError(
+ f"API key for provider {provider!r} required for AgentWorkflow "
+ f"node {node_id!r}; configure it in the Credentials Modal."
+ )
+
+ max_tokens = _resolve_max_tokens(flattened, model, provider)
+
+ thinking_config_obj: Any = None
+ thinking_config_dict: Any = None
+ if flattened.get("thinking_enabled"):
+ thinking_config_obj = ThinkingConfig(
+ enabled=True,
+ budget=int(flattened.get("thinking_budget", 2048)),
+ effort=flattened.get("reasoning_effort", "medium"),
+ level=flattened.get("thinking_level", "medium"),
+ format=flattened.get("reasoning_format", "parsed"),
+ )
+ thinking_config_dict = {
+ "enabled": True,
+ "budget": thinking_config_obj.budget,
+ "effort": thinking_config_obj.effort,
+ "level": thinking_config_obj.level,
+ "format": thinking_config_obj.format,
+ }
+
+ temperature = _resolve_temperature(
+ flattened, model, provider,
+ bool(thinking_config_obj and thinking_config_obj.enabled),
+ )
+
+ # ---- Edge walking ---------------------------------------------------
+ walk_context = {
+ "nodes": context.get("nodes") or [],
+ "edges": context.get("edges") or [],
+ "workflow_id": workflow_id,
+ }
+ memory_data, skill_data, tool_data, input_data, _task_data = (
+ await collect_agent_connections(
+ node_id, walk_context, database, log_prefix=f"[AgentWorkflow:{node_type}]",
+ )
+ )
+
+ # ---- Skill prompt injection ----------------------------------------
+ from services.ai import _build_skill_system_prompt
+ skill_prompt, has_personality = _build_skill_system_prompt(
+ skill_data, log_prefix=f"[AgentWorkflow:{node_type}]",
+ )
+ if skill_prompt:
+ system_message = skill_prompt if has_personality else f"{system_message}\n\n{skill_prompt}"
+
+ # ---- Memory ---------------------------------------------------------
+ memory_node_id = ""
+ memory_content = ""
+ memory_window_size = 10
+ if memory_data:
+ memory_node_id = memory_data.get("node_id") or ""
+ memory_content = memory_data.get("memory_content") or ""
+ memory_window_size = int(memory_data.get("window_size") or 10)
+
+ # ---- Tools ----------------------------------------------------------
+ # Build LangChain StructuredTool per tool entry, then serialise its
+ # args_schema to JSON Schema so the AgentWorkflow's LLM step can
+ # rebuild a placeholder StructuredTool from it.
+ tools_payload: List[Dict[str, Any]] = []
+ for tool_info in tool_data or []:
+ try:
+ tool, config = await ai_service._build_tool_from_node(tool_info)
+ except Exception as e: # noqa: BLE001 — defensive: skip a broken tool
+ activity.logger.warning(
+ f"prepare_payload: failed to build tool {tool_info.get('node_type')!r}: {e}"
+ )
+ continue
+ if tool is None:
+ continue
+ # Look up plugin class for activity-dispatch metadata.
+ from services.node_registry import get_node_class
+ cls = get_node_class(tool_info.get("node_type", ""))
+ version = getattr(cls, "version", 1) if cls else 1
+ task_queue = getattr(cls, "task_queue", "machina-default") if cls else "machina-default"
+
+ # Serialise args_schema to JSON Schema. StructuredTool.args_schema
+ # is a Pydantic model; .model_json_schema() returns a dict the
+ # LLM activity can use to bind a placeholder tool.
+ args_schema_dict: Dict[str, Any] = {}
+ try:
+ if tool.args_schema is not None:
+ args_schema_dict = tool.args_schema.model_json_schema()
+ except Exception as e: # noqa: BLE001 — defensive
+ activity.logger.debug(
+ f"prepare_payload: failed to serialise args_schema for "
+ f"{tool_info.get('node_type')!r}: {e}"
+ )
+
+ tools_payload.append({
+ "name": tool.name,
+ "description": tool.description or "",
+ "args_schema": args_schema_dict,
+ "node_type": tool_info.get("node_type", ""),
+ "version": version,
+ "task_queue": task_queue,
+ "tool_node_id": tool_info.get("node_id", ""),
+ "parameters": tool_info.get("parameters") or {},
+ })
+
+ # ---- Compaction threshold ------------------------------------------
+ # Model-aware threshold (50% of context window per agent.compaction.ratio
+ # in llm_defaults.json). Reuse the existing CompactionService helper.
+ compaction_threshold: int | None = None
+ try:
+ from services.compaction import get_compaction_service
+ svc = get_compaction_service()
+ cfg = svc.anthropic_config(model=model, provider=provider)
+ compaction_threshold = int(cfg.get("context_token_threshold") or 0) or None
+ except Exception: # noqa: BLE001 — defensive, optional feature
+ compaction_threshold = None
+
+ # ---- Optional auto-prompt fallback from input_data -----------------
+ # When `prompt` is empty AND a chatTrigger / whatsappReceive / etc.
+ # is connected via input-main, use the upstream output's `message`
+ # / `text` / `content` as the user prompt. Same fallback the legacy
+ # agent path uses.
+ if not prompt and input_data:
+ out = input_data.get("result") or input_data
+ for field in ("message", "text", "content"):
+ if field in out and out[field]:
+ prompt = str(out[field])
+ break
+
+ return {
+ "node_id": node_id,
+ "node_type": node_type,
+ "workflow_id": workflow_id,
+ "session_id": session_id,
+ "provider": provider,
+ "model": model,
+ "api_key": api_key,
+ "max_tokens": max_tokens,
+ "temperature": temperature,
+ "system_message": system_message,
+ "user_prompt": prompt,
+ "tools": tools_payload,
+ "memory_node_id": memory_node_id,
+ "memory_content": memory_content,
+ "memory_window_size": memory_window_size,
+ "max_iterations": int(parameters.get("max_iterations") or 50),
+ "thinking_config": thinking_config_dict,
+ "compaction_threshold": compaction_threshold,
+ }
+
+
def collect_agent_activities() -> List[Any]:
- """Return the three F4.B agent activities for worker registration.
+ """Return the four F4.B agent activities for worker registration.
Mirrors :func:`services.temporal.plugin_activities.collect_plugin_activities`
for the workflow-orchestrated agent loop. Workers register these so
- ``AgentWorkflow`` can schedule them; ``MachinaWorkflow`` doesn't
- invoke them directly.
+ ``AgentWorkflow`` can schedule them; ``MachinaWorkflow`` invokes
+ only :func:`prepare_agent_payload` directly (to build the
+ AgentWorkflow input payload before scheduling the child workflow).
"""
- return [execute_llm_step, persist_agent_turn, compact_agent_memory]
+ return [
+ execute_llm_step,
+ persist_agent_turn,
+ compact_agent_memory,
+ prepare_agent_payload,
+ ]
diff --git a/server/services/temporal/agent_workflow.py b/server/services/temporal/agent_workflow.py
index fcbcc12d..0f94af00 100644
--- a/server/services/temporal/agent_workflow.py
+++ b/server/services/temporal/agent_workflow.py
@@ -94,16 +94,34 @@ class AgentWorkflow:
"""
@workflow.run
- async def run(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+ async def run(self, context: Dict[str, Any]) -> Dict[str, Any]:
"""Run the agent loop.
- ``payload`` shape::
+ ``context`` shape (same as the legacy ``execute_node_activity``
+ context — the orchestrator passes the same dict it would have
+ passed to an activity)::
{
"node_id": str,
"node_type": str,
+ "node_data": dict, # node parameters from canvas
"workflow_id": Optional[str],
"session_id": str,
+ "nodes": list, # full canvas (for edge walking)
+ "edges": list,
+ "inputs": dict, # upstream node outputs
+ }
+
+ The workflow's FIRST step is to schedule
+ ``agent.prepare_payload.v1`` which returns the fully-resolved
+ payload (provider, model, api_key, tools, memory, ...). Doing
+ prep INSIDE the workflow (as an activity) keeps the orchestrator
+ ignorant of agent-specific concerns and means the workflow
+ owns its setup — Temporal's recommended structure.
+
+ The resolved payload looks like::
+
+ {
"provider": str,
"model": str,
"api_key": str,
@@ -135,6 +153,15 @@ class AgentWorkflow:
``services/ai.py:execute_agent`` returns today so downstream
code (OutputPanel, edge inputs, etc.) doesn't change.
"""
+ # ---- Step 0: Resolve payload via the prep activity --------------
+ # DB lookups + edge walking + tool schema build happen here, NOT
+ # in the workflow body (workflows must be deterministic).
+ payload = await workflow.execute_activity(
+ "agent.prepare_payload.v1",
+ args=[context],
+ start_to_close_timeout=PERSIST_TURN_TIMEOUT * 2, # 60s default
+ retry_policy=AGENT_ACTIVITY_RETRY,
+ )
# ---- Build initial message list ---------------------------------
# Workflow state is JSON dicts. Activities rehydrate LangChain
# message objects from these dicts (see agent_activities.py).
diff --git a/server/services/temporal/workflow.py b/server/services/temporal/workflow.py
index 9dcddfeb..74cb2e8f 100644
--- a/server/services/temporal/workflow.py
+++ b/server/services/temporal/workflow.py
@@ -38,6 +38,35 @@ SKILL_NODE_TYPES = {
"masterSkill",
}
+# F4.B: agent types that migrate to AgentWorkflow (Temporal child workflow).
+# When ``temporal_agent_workflow_enabled`` is True the orchestrator schedules
+# AgentWorkflow for these node types instead of an activity. Tool calls
+# inside the agent loop become per-type activities (F4.A path).
+#
+# Excluded: ``deep_agent``, ``rlm_agent``, ``claude_code_agent``. Their
+# internal session state (deepagents package / RLM REPL / Claude CLI
+# --resume with stable cwd) requires single-process continuity and breaks
+# across activity boundaries. They continue via F4.A per-type activities.
+AGENT_WORKFLOW_TYPES = frozenset([
+ "aiAgent",
+ "chatAgent",
+ # Specialized agents (12)
+ "android_agent",
+ "coding_agent",
+ "web_agent",
+ "task_agent",
+ "social_agent",
+ "travel_agent",
+ "tool_agent",
+ "productivity_agent",
+ "payments_agent",
+ "consumer_agent",
+ "autonomous_agent",
+ # Team leads (2)
+ "orchestrator_agent",
+ "ai_employee",
+])
+
@workflow.defn(sandboxed=False)
class MachinaWorkflow:
"""Distributed workflow orchestrator.
@@ -172,28 +201,44 @@ class MachinaWorkflow:
"trigger_output": node.get("_trigger_output"),
}
- # F4.A: per-type dispatch when the plugin class is registered
- # AND the settings flag is on. Frozen-dict lookup is deterministic
- # so it's safe inside the workflow (Temporal Workflow Definition
- # determinism contract). Falls back to the legacy single activity
- # name for any node type without a class registration.
- activity_name, activity_queue = self._resolve_activity(node_type)
- start_kwargs: Dict[str, Any] = dict(
- args=[context],
- start_to_close_timeout=timedelta(minutes=10),
- heartbeat_timeout=timedelta(minutes=2),
- retry_policy=retry_policy,
- )
- if activity_queue is not None:
- start_kwargs["task_queue"] = activity_queue
-
- handle = workflow.start_activity(activity_name, **start_kwargs)
- running[node_id] = handle
-
- workflow.logger.info(
- f"Scheduled activity for node: {node_id} "
- f"(activity={activity_name}, queue={activity_queue or 'default'})"
- )
+ # F4.B: agent-as-child-workflow takes precedence over the
+ # activity path for the 15 migrating agent types when its
+ # flag is on. Tool calls inside the agent loop become
+ # per-type activities (F4.A path) automatically.
+ dispatch = self._resolve_dispatch(node_type)
+ if dispatch["kind"] == "child_workflow":
+ handle = workflow.start_child_workflow(
+ dispatch["name"],
+ args=[context],
+ # Child workflow execution timeout: agent loops can run
+ # 10+ minutes with multiple LLM turns. Set generously.
+ execution_timeout=timedelta(hours=1),
+ run_timeout=timedelta(hours=1),
+ )
+ running[node_id] = handle
+ workflow.logger.info(
+ f"Scheduled child workflow for node: {node_id} "
+ f"(workflow={dispatch['name']})"
+ )
+ else:
+ # F4.A activity path: per-type when the plugin class is
+ # registered AND the per-type flag is on; legacy
+ # execute_node_activity otherwise.
+ start_kwargs: Dict[str, Any] = dict(
+ args=[context],
+ start_to_close_timeout=timedelta(minutes=10),
+ heartbeat_timeout=timedelta(minutes=2),
+ retry_policy=retry_policy,
+ )
+ if dispatch.get("queue") is not None:
+ start_kwargs["task_queue"] = dispatch["queue"]
+
+ handle = workflow.start_activity(dispatch["name"], **start_kwargs)
+ running[node_id] = handle
+ workflow.logger.info(
+ f"Scheduled activity for node: {node_id} "
+ f"(activity={dispatch['name']}, queue={dispatch.get('queue') or 'default'})"
+ )
# Exit if nothing running and nothing ready
if not running:
@@ -248,6 +293,32 @@ class MachinaWorkflow:
inputs[dep_id] = outputs[dep_id].get("result", {})
return inputs
+ def _resolve_dispatch(self, node_type: str) -> Dict[str, Any]:
+ """Resolve dispatch kind for a node type.
+
+ Returns one of:
+ - ``{"kind": "child_workflow", "name": "AgentWorkflow"}`` — when
+ F4.B is enabled AND node_type is in ``AGENT_WORKFLOW_TYPES``.
+ - ``{"kind": "activity", "name": <activity_name>, "queue": <queue|None>}``
+ — F4.A per-type activity OR legacy fallback, depending on
+ ``temporal_per_type_dispatch``.
+
+ Deterministic: all lookups go through frozen dicts (Settings,
+ _NODE_CLASS_REGISTRY, AGENT_WORKFLOW_TYPES). Safe inside
+ ``MachinaWorkflow.run`` per the workflow-definition contract.
+ """
+ from core.config import Settings
+
+ settings = Settings()
+ if (
+ getattr(settings, "temporal_agent_workflow_enabled", False)
+ and node_type in AGENT_WORKFLOW_TYPES
+ ):
+ return {"kind": "child_workflow", "name": "AgentWorkflow"}
+
+ name, queue = self._resolve_activity(node_type)
+ return {"kind": "activity", "name": name, "queue": queue}
+
def _resolve_activity(self, node_type: str) -> tuple[str, str | None]:
"""Resolve (activity_name, task_queue) for a node type.
diff --git a/server/tests/temporal/test_agent_workflow.py b/server/tests/temporal/test_agent_workflow.py
index 8c736411..0ae834b6 100644
--- a/server/tests/temporal/test_agent_workflow.py
+++ b/server/tests/temporal/test_agent_workflow.py
@@ -67,7 +67,10 @@ class TestAgentActivities:
defn = getattr(compact_agent_memory, "__temporal_activity_definition")
assert defn.name == "agent.compact_memory.v1"
- def test_collect_returns_all_three(self):
+ def test_collect_returns_all_four(self):
+ """F4.B canary wiring added ``agent.prepare_payload.v1``. The
+ collector must surface all four so the worker registration covers
+ the orchestrator's prep + the workflow's loop activities."""
from services.temporal.agent_activities import collect_agent_activities
activities = collect_agent_activities()
@@ -78,8 +81,15 @@ class TestAgentActivities:
"agent.compact_memory.v1",
"agent.execute_llm_step.v1",
"agent.persist_turn.v1",
+ "agent.prepare_payload.v1",
]
+ def test_prepare_payload_registered(self):
+ from services.temporal.agent_activities import prepare_agent_payload
+
+ defn = getattr(prepare_agent_payload, "__temporal_activity_definition")
+ assert defn.name == "agent.prepare_payload.v1"
+
class TestWorkerWiring:
"""Worker registration must include AgentWorkflow + activities so the
diff --git a/server/tests/temporal/test_dispatch.py b/server/tests/temporal/test_dispatch.py
index df389cda..14d382b4 100644
--- a/server/tests/temporal/test_dispatch.py
+++ b/server/tests/temporal/test_dispatch.py
@@ -103,6 +103,72 @@ class TestResolveActivityFlagOn:
assert name == f"node.coding_agent.v{cls.version}"
+class TestAgentWorkflowDispatch:
+ """F4.B: when the agent-workflow flag is on AND the node type is in
+ AGENT_WORKFLOW_TYPES, dispatch must route through the child workflow
+ instead of an activity. Excluded types (deep_agent / rlm_agent /
+ claude_code_agent) keep using the activity path."""
+
+ def _set_flags(self, *, per_type: bool, agent_wf: bool):
+ from types import SimpleNamespace
+ from unittest.mock import patch as _patch
+
+ def fake_settings():
+ return SimpleNamespace(
+ temporal_per_type_dispatch=per_type,
+ temporal_agent_workflow_enabled=agent_wf,
+ )
+
+ return _patch("core.config.Settings", side_effect=lambda: fake_settings())
+
+ def test_chat_agent_routes_to_child_workflow(self, workflow_instance):
+ with self._set_flags(per_type=True, agent_wf=True):
+ dispatch = workflow_instance._resolve_dispatch("chatAgent")
+ assert dispatch["kind"] == "child_workflow"
+ assert dispatch["name"] == "AgentWorkflow"
+
+ def test_ai_agent_routes_to_child_workflow(self, workflow_instance):
+ with self._set_flags(per_type=True, agent_wf=True):
+ dispatch = workflow_instance._resolve_dispatch("aiAgent")
+ assert dispatch["kind"] == "child_workflow"
+
+ def test_specialized_agent_routes_to_child_workflow(self, workflow_instance):
+ for t in ("coding_agent", "web_agent", "orchestrator_agent", "ai_employee"):
+ with self._set_flags(per_type=True, agent_wf=True):
+ dispatch = workflow_instance._resolve_dispatch(t)
+ assert dispatch["kind"] == "child_workflow", (
+ f"{t} should route to AgentWorkflow when F4.B is on"
+ )
+
+ def test_excluded_agents_stay_on_activity_path(self, workflow_instance):
+ """deep_agent / rlm_agent / claude_code_agent are NOT migrated
+ (externalised session state). They must use the per-type activity
+ path even when F4.B is on."""
+ for t in ("deep_agent", "rlm_agent", "claude_code_agent"):
+ with self._set_flags(per_type=True, agent_wf=True):
+ dispatch = workflow_instance._resolve_dispatch(t)
+ assert dispatch["kind"] == "activity", (
+ f"{t} must NOT migrate to AgentWorkflow (externalised session)"
+ )
+ assert dispatch["name"] == f"node.{t}.v1"
+
+ def test_agent_workflow_flag_off_falls_back_to_activity(self, workflow_instance):
+ with self._set_flags(per_type=True, agent_wf=False):
+ dispatch = workflow_instance._resolve_dispatch("chatAgent")
+ assert dispatch["kind"] == "activity"
+ assert dispatch["name"] == "node.chatAgent.v1"
+
+ def test_non_agent_types_stay_on_activity_path(self, workflow_instance):
+ """Tool / utility / model nodes shouldn't accidentally route
+ through AgentWorkflow even when F4.B is on."""
+ for t in ("pythonExecutor", "calculatorTool", "openaiChatModel"):
+ with self._set_flags(per_type=True, agent_wf=True):
+ dispatch = workflow_instance._resolve_dispatch(t)
+ assert dispatch["kind"] == "activity", (
+ f"{t} is not an agent type; must NOT route to AgentWorkflow"
+ )
+
+
class TestPerTypeActivityCollection:
"""`collect_plugin_activities()` must return one callable per registered
plugin class — TemporalWorkerManager's per-type registration depends on