Skip to content

Self-improving AI Employees for everyone

feat(temporal): AgentWorkflow + agent activities infrastructure (F4.B)

trohitga4d009e4b12d
diff --git a/server/core/config.py b/server/core/config.py
index e2ae7417..d80d1ca0 100644
--- a/server/core/config.py
+++ b/server/core/config.py
@@ -58,6 +58,17 @@ class Settings(BaseSettings):
# activities alongside the legacy one. Default off so existing deployments
# behave identically; flip via TEMPORAL_PER_TYPE_DISPATCH=true.
temporal_per_type_dispatch: bool = Field(default=False, env="TEMPORAL_PER_TYPE_DISPATCH")
+ # F4.B: agent-as-child-workflow. When True, MachinaWorkflow.run() schedules
+ # AgentWorkflow (child workflow) for the 15 migrating agent types
+ # (aiAgent / chatAgent / 12 specialized agents / 2 team leads) instead of
+ # an activity. Tool calls inside the agent become per-type Temporal
+ # activities. `deep_agent`, `rlm_agent`, `claude_code_agent` continue to
+ # run as F4.A per-type activities (NOT migrated -- their external session
+ # state would break across activity boundaries). Default off. Implies
+ # temporal_per_type_dispatch=True.
+ temporal_agent_workflow_enabled: bool = Field(
+ default=False, env="TEMPORAL_AGENT_WORKFLOW_ENABLED",
+ )
# API Keys (all optional, injected at runtime)
google_maps_api_key: Optional[str] = Field(default=None, env="GOOGLE_MAPS_API_KEY")
diff --git a/server/services/temporal/agent_activities.py b/server/services/temporal/agent_activities.py
new file mode 100644
index 00000000..480336ab
--- /dev/null
+++ b/server/services/temporal/agent_activities.py
@@ -0,0 +1,331 @@
+"""F4.B: per-turn agent activities for ``AgentWorkflow``.
+
+The legacy ``execute_agent`` / ``execute_chat_agent`` in ``services/ai.py``
+run an entire LangGraph loop inside a single Temporal activity. F4.B
+splits that loop across Temporal workflow boundaries so tool calls can
+land as separate activities on per-type worker pools (per RFC §6.3
+plus the F4 deferred follow-up). Activities defined here:
+
+- :func:`execute_llm_step` — one ``chat_model.ainvoke()`` turn. Returns
+ either ``{"kind": "final", ...}`` (no tool calls) or
+ ``{"kind": "tool_calls", "calls": [...], ...}`` for the workflow to
+ schedule. **Lives on TaskQueue.AI_HEAVY** when the per-queue pool is
+ wired (until then, default queue is fine).
+- :func:`persist_agent_turn` — append one human/AI message pair to the
+ connected ``simpleMemory`` markdown via the same helpers
+ ``services.ai`` uses today. Per user decision (plan §15) memory
+ appends per turn, not on completion, so workflow failures don't lose
+ progress.
+- :func:`compact_agent_memory` — invoke ``CompactionService.compact_context``
+ when token thresholds trip. Returns the compacted summary message
+ list. Token accounting stays in the workflow state.
+
+Determinism: every activity is a leaf computation (LLM ainvoke, DB
+write, summarisation). The workflow that calls them is sandboxed=False
+and may read frozen registry dicts deterministically.
+
+References:
+- Temporal AI Cookbook -- https://docs.temporal.io/ai-cookbook
+- ``temporalio.contrib.openai_agents.activity_as_tool`` mirrors this
+ pattern; we re-implement manually because MachinaOs uses LangChain
+ (``chat_model.bind_tools`` for schema generation) rather than the
+ OpenAI Agents SDK.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from temporalio import activity
+
+logger = logging.getLogger(__name__)
+
+
+# Activity result shapes — keep these in sync with AgentWorkflow's
+# expectations. Pydantic was considered but plain dicts keep the
+# payload-serialisation cost flat (Temporal serialises via JSON anyway)
+# and avoid pulling Pydantic into the workflow sandbox boundary.
+
+# {"kind": "final", "content": str, "thinking": Optional[str], "usage": dict}
+# {"kind": "tool_calls", "calls": [{"id": str, "name": str, "args": dict}], "usage": dict}
+
+
[email protected](name="agent.execute_llm_step.v1")
+async def execute_llm_step(payload: Dict[str, Any]) -> Dict[str, Any]:
+ """Run one LLM turn with bound tools and return the structured response.
+
+ ``payload`` shape::
+
+ {
+ "provider": "anthropic" | "openai" | ...,
+ "model": "claude-sonnet-4-6",
+ "api_key": "...", # already resolved
+ "messages": [{"role": "user", "content": "..."}, ...],
+ "tools": [ # tool schemas (already built)
+ {"name": "calculator", "description": "...", "args_schema": {...}}
+ ],
+ "system_message": Optional[str],
+ "temperature": float,
+ "max_tokens": int,
+ "thinking_config": Optional[dict],
+ }
+
+ Returns one of:
+ - ``{"kind": "final", "content": str, "thinking": Optional[str], "usage": dict}``
+ - ``{"kind": "tool_calls", "calls": [{"id", "name", "args"}], "usage": dict}``
+
+ The activity intentionally keeps no state across turns; the workflow
+ owns the messages list. This makes replay safe per Temporal's
+ determinism contract — each activity is a pure transformation.
+
+ Heartbeats every 30 s so long LLM streams don't trip
+ ``heartbeat_timeout``.
+ """
+ activity.logger.info(
+ f"Agent LLM step: provider={payload.get('provider')} "
+ f"model={payload.get('model')} messages={len(payload.get('messages', []))}"
+ )
+ activity.heartbeat(f"LLM step starting: {payload.get('model')}")
+
+ # Lazy import — keep top-level light so the worker can register this
+ # activity without pulling LangChain in for every plugin.
+ from services.ai import AIService, extract_thinking_from_response
+
+ provider = payload["provider"]
+ model = payload["model"]
+ api_key = payload["api_key"]
+ messages = payload.get("messages", [])
+ tools_schemas = payload.get("tools", [])
+ temperature = payload.get("temperature", 0.7)
+ max_tokens = payload.get("max_tokens", 4096)
+ thinking_config = payload.get("thinking_config")
+
+ ai_service = AIService()
+
+ chat_model = ai_service.create_model(
+ provider=provider,
+ api_key=api_key,
+ model=model,
+ temperature=temperature,
+ max_tokens=max_tokens,
+ thinking=thinking_config,
+ )
+
+ # Bind tools so the LLM sees their schemas. Tool schemas in the
+ # payload are already serialised StructuredTool definitions — we
+ # rebuild LangChain StructuredTool wrappers from them. The tools
+ # themselves are NOT executed here; the workflow schedules them as
+ # separate activities once the LLM emits tool_calls.
+ if tools_schemas:
+ from langchain_core.tools import StructuredTool
+ from pydantic import create_model
+
+ bound_tools: List[Any] = []
+ for ts in tools_schemas:
+ # Materialise a no-op StructuredTool — execution is deferred
+ # to the workflow's tool activity dispatch.
+ def _placeholder(**kwargs): # noqa: ARG001
+ raise NotImplementedError("Tool is dispatched via Temporal activity")
+
+ # Recreate a minimal Pydantic args schema. The real type
+ # safety lives in the plugin's Params model; here we just
+ # need names + descriptions for the LLM.
+ args_schema = ts.get("args_schema") or {}
+ fields = {
+ k: (Any, v.get("description", "") if isinstance(v, dict) else "")
+ for k, v in args_schema.get("properties", {}).items()
+ }
+ Args = create_model(f"{ts['name']}Args", **fields) if fields else None
+
+ bound_tools.append(
+ StructuredTool.from_function(
+ func=_placeholder,
+ name=ts["name"],
+ description=ts.get("description", ""),
+ args_schema=Args,
+ )
+ )
+ chat_model = chat_model.bind_tools(bound_tools)
+
+ # Reconstruct LangChain message objects from the workflow's dict
+ # representation. Workflow state is serialisable JSON dicts; the
+ # activity rehydrates them.
+ from langchain_core.messages import (
+ AIMessage,
+ HumanMessage,
+ SystemMessage,
+ ToolMessage,
+ )
+
+ rehydrated = []
+ for m in messages:
+ role = m.get("role")
+ content = m.get("content", "")
+ if role == "system":
+ rehydrated.append(SystemMessage(content=content))
+ elif role == "user":
+ rehydrated.append(HumanMessage(content=content))
+ elif role == "assistant":
+ ai = AIMessage(content=content)
+ if m.get("tool_calls"):
+ ai.tool_calls = m["tool_calls"]
+ rehydrated.append(ai)
+ elif role == "tool":
+ rehydrated.append(
+ ToolMessage(
+ content=content,
+ tool_call_id=m.get("tool_call_id", ""),
+ name=m.get("name", ""),
+ )
+ )
+
+ activity.heartbeat("LLM step: invoking model")
+ response = await chat_model.ainvoke(rehydrated)
+ activity.heartbeat("LLM step: model returned")
+
+ # Extract usage if present (anthropic-style token counts).
+ usage: Dict[str, Any] = {}
+ if hasattr(response, "usage_metadata") and response.usage_metadata:
+ usage = dict(response.usage_metadata)
+ elif hasattr(response, "response_metadata"):
+ meta_usage = response.response_metadata.get("usage", {})
+ if meta_usage:
+ usage = dict(meta_usage)
+
+ # Tool calls → return them for the workflow to schedule.
+ if hasattr(response, "tool_calls") and response.tool_calls:
+ return {
+ "kind": "tool_calls",
+ "calls": [
+ {
+ "id": tc.get("id", ""),
+ "name": tc.get("name", ""),
+ "args": tc.get("args", {}),
+ }
+ for tc in response.tool_calls
+ ],
+ "usage": usage,
+ }
+
+ # No tool calls → final response.
+ text, thinking = extract_thinking_from_response(response)
+ return {
+ "kind": "final",
+ "content": text or "",
+ "thinking": thinking,
+ "usage": usage,
+ }
+
+
[email protected](name="agent.persist_turn.v1")
+async def persist_agent_turn(payload: Dict[str, Any]) -> Dict[str, Any]:
+ """Append one ``(human, assistant)`` pair to the connected memory.
+
+ Per user decision in plan §15 (F4.B), memory appends per turn so
+ failure mid-loop doesn't lose progress. Uses the same markdown
+ helpers ``services/ai.py`` calls today via
+ ``services.memory.markdown.append_to_memory_markdown``.
+
+ ``payload``::
+
+ {
+ "memory_node_id": str, # the simpleMemory node
+ "human_text": str,
+ "assistant_text": str,
+ "window_size": int,
+ }
+
+ Returns ``{"appended": bool, "trimmed_count": int}``.
+
+ No-op when ``memory_node_id`` is empty (the agent has no memory
+ connected).
+ """
+ memory_node_id = payload.get("memory_node_id") or ""
+ if not memory_node_id:
+ return {"appended": False, "trimmed_count": 0}
+
+ from core.container import container
+ from services.memory.markdown import (
+ append_to_memory_markdown,
+ trim_markdown_window,
+ )
+
+ database = container.database()
+ params = await database.get_node_parameters(memory_node_id) or {}
+ current = params.get("memory_content", "")
+
+ updated = append_to_memory_markdown(
+ current,
+ human_text=payload.get("human_text", ""),
+ assistant_text=payload.get("assistant_text", ""),
+ )
+
+ window_size = int(payload.get("window_size", 10))
+ trimmed_content, trimmed_pairs = trim_markdown_window(updated, window_size)
+
+ params["memory_content"] = trimmed_content
+ await database.save_node_parameters(memory_node_id, params)
+
+ # Broadcast so the parameter panel auto-refetches mid-run.
+ broadcaster = container.status_broadcaster()
+ await broadcaster.broadcast(
+ {
+ "type": "node_parameters_updated",
+ "node_id": memory_node_id,
+ "parameters": params,
+ }
+ )
+
+ return {"appended": True, "trimmed_count": len(trimmed_pairs)}
+
+
[email protected](name="agent.compact_memory.v1")
+async def compact_agent_memory(payload: Dict[str, Any]) -> Dict[str, Any]:
+ """Compact the running conversation when token budget exceeded.
+
+ Wraps ``CompactionService.compact_context`` (existing, in
+ ``services/compaction.py``) so the workflow can replace its
+ ``messages`` list with the summary message when needed.
+
+ ``payload``::
+
+ {
+ "session_id": str,
+ "node_id": str,
+ "memory_content": str,
+ "provider": str,
+ "api_key": str,
+ "model": str,
+ }
+
+ Returns ``{"success": bool, "summary": str, "tokens_before": int, "tokens_after": int}``.
+ Caller (workflow) replaces its ``messages`` with a single system
+ message wrapping the summary, resets token counters, and continues.
+ """
+ from services.compaction import get_compaction_service
+
+ activity.heartbeat("Compacting agent memory")
+ svc = get_compaction_service()
+ result = await svc.compact_context(
+ session_id=payload["session_id"],
+ node_id=payload["node_id"],
+ memory_content=payload.get("memory_content", ""),
+ provider=payload["provider"],
+ api_key=payload["api_key"],
+ model=payload["model"],
+ )
+ return result
+
+
+def collect_agent_activities() -> List[Any]:
+ """Return the three 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.
+ """
+ return [execute_llm_step, persist_agent_turn, compact_agent_memory]
diff --git a/server/services/temporal/agent_workflow.py b/server/services/temporal/agent_workflow.py
new file mode 100644
index 00000000..fcbcc12d
--- /dev/null
+++ b/server/services/temporal/agent_workflow.py
@@ -0,0 +1,429 @@
+"""F4.B: ``AgentWorkflow`` — Temporal child workflow for AI agent loops.
+
+Replaces the inline LangGraph loop inside ``services/ai.py:execute_agent``
+with a workflow-orchestrated loop: each LLM turn is an activity, each
+tool call is a per-type activity (registered via
+``BaseNode.as_activity()``, F4.A), and memory persistence happens per
+turn so a workflow failure mid-loop doesn't lose progress.
+
+Architecture (matches Temporal's AI Cookbook canonical pattern):
+
+ MachinaWorkflow.run()
+ └─> execute_child_workflow(AgentWorkflow, payload)
+ loop:
+ ├─> execute_activity(agent.execute_llm_step.v1)
+ │ → returns "final" OR "tool_calls"
+ ├─> if tool_calls:
+ │ execute_activity(node.{tool_type}.v1) for each
+ ├─> execute_activity(agent.persist_turn.v1)
+ ├─> token check; if over threshold:
+ │ execute_activity(agent.compact_memory.v1)
+ └─> repeat until "final" or max_iterations
+
+User decisions baked in (plan §15):
+- **Path 1** (agent-as-child-workflow), confirmed.
+- ``deep_agent``, ``rlm_agent``, ``claude_code_agent`` are NOT migrated
+ here. Their loops are externalised (deepagents / RLM REPL / Claude
+ CLI ``--resume`` session) and live in single Temporal activities via
+ the F4.A per-type dispatch path. They never enter ``AgentWorkflow``.
+- Memory appends per turn (not on completion).
+- Tool activity failure (after retries) returns an error to the LLM as
+ a ``ToolMessage`` and the agent continues — matches today's LangGraph
+ behaviour.
+
+Determinism:
+- ``sandboxed=False`` so we can import frozen registry dicts
+ (``services.node_registry``) for tool name resolution.
+- All non-deterministic operations (LLM calls, DB writes, broadcasts)
+ go through activities. The workflow itself only mutates its own
+ ``messages`` / ``iteration`` / ``token_total`` state.
+
+References:
+- https://docs.temporal.io/ai-cookbook
+- https://github.com/temporal-community/temporal-ai-agent
+- ``temporalio/sdk-python contrib/openai_agents/``
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Any, Dict, List, Optional
+
+from temporalio import workflow
+from temporalio.common import RetryPolicy
+
+
+# Activity timeouts. LLM step can stream for several minutes on
+# reasoning models; tool calls vary widely (python: seconds, browser:
+# minutes). Tool activities use the plugin-declared
+# ``start_to_close_timeout`` automatically — we only set defaults here
+# for the agent-specific activities.
+LLM_STEP_TIMEOUT = timedelta(minutes=10)
+PERSIST_TURN_TIMEOUT = timedelta(seconds=30)
+COMPACT_MEMORY_TIMEOUT = timedelta(minutes=5)
+
+# Tool activity defaults — plugin classes can override via
+# ``cls.start_to_close_timeout`` (F4.A); these are floor values.
+TOOL_STEP_TIMEOUT = timedelta(minutes=10)
+TOOL_HEARTBEAT_TIMEOUT = timedelta(minutes=2)
+
+# Bounded loop count to defend against a runaway LLM. Plugin classes
+# can override via ``payload["max_iterations"]``; this is the hard cap.
+DEFAULT_MAX_ITERATIONS = 50
+
+# Retry policy for the agent's own activities (LLM step, persist,
+# compact). Tool activities use their plugin's policy.
+AGENT_ACTIVITY_RETRY = RetryPolicy(
+ initial_interval=timedelta(seconds=1),
+ maximum_interval=timedelta(seconds=30),
+ maximum_attempts=3,
+)
+
+
[email protected](sandboxed=False, name="AgentWorkflow")
+class AgentWorkflow:
+ """Run an AI agent as a Temporal child workflow.
+
+ Scheduled by ``MachinaWorkflow.run()`` when:
+ - ``settings.temporal_agent_workflow_enabled`` is True, AND
+ - the node type is in the migrating set (``aiAgent``,
+ ``chatAgent``, 12 specialized agents, 2 team leads).
+
+ ``deep_agent`` / ``rlm_agent`` / ``claude_code_agent`` skip this
+ workflow and stay as F4.A per-type activities.
+ """
+
+ @workflow.run
+ async def run(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+ """Run the agent loop.
+
+ ``payload`` shape::
+
+ {
+ "node_id": str,
+ "node_type": str,
+ "workflow_id": Optional[str],
+ "session_id": str,
+ "provider": str,
+ "model": str,
+ "api_key": str,
+ "max_tokens": int,
+ "temperature": float,
+ "system_message": str,
+ "user_prompt": str,
+ "tools": [ # already-resolved tool schemas
+ {
+ "name": str, # LLM-facing name
+ "node_type": str, # plugin type for activity dispatch
+ "version": int, # plugin class version
+ "description": str,
+ "args_schema": dict,
+ "tool_node_id": str,
+ "parameters": dict, # plugin params from DB
+ "task_queue": str, # plugin task_queue (queue routing future)
+ },
+ ],
+ "memory_node_id": Optional[str],
+ "memory_content": str, # pre-loaded markdown
+ "memory_window_size": int,
+ "max_iterations": int,
+ "thinking_config": Optional[dict],
+ "compaction_threshold": Optional[int],
+ }
+
+ Returns the final agent response, mirroring the shape
+ ``services/ai.py:execute_agent`` returns today so downstream
+ code (OutputPanel, edge inputs, etc.) doesn't change.
+ """
+ # ---- Build initial message list ---------------------------------
+ # Workflow state is JSON dicts. Activities rehydrate LangChain
+ # message objects from these dicts (see agent_activities.py).
+ messages: List[Dict[str, Any]] = []
+
+ system = payload.get("system_message") or ""
+ if system:
+ messages.append({"role": "system", "content": system})
+
+ # Pre-loaded memory becomes an additional system note. The actual
+ # parse / append happens in the persist_turn activity, but the
+ # current markdown content seeds the conversation here.
+ memory_markdown = payload.get("memory_content") or ""
+ if memory_markdown:
+ messages.append({
+ "role": "system",
+ "content": f"## Prior conversation:\n{memory_markdown}",
+ })
+
+ user_prompt = payload.get("user_prompt") or ""
+ if user_prompt:
+ messages.append({"role": "user", "content": user_prompt})
+
+ # Map LLM tool name -> {node_type, version, task_queue, node_id,
+ # parameters} so the workflow can schedule the right activity
+ # when the LLM emits a tool_call.
+ tools = payload.get("tools") or []
+ tool_index: Dict[str, Dict[str, Any]] = {
+ t["name"]: t for t in tools
+ }
+
+ max_iterations = int(payload.get("max_iterations") or DEFAULT_MAX_ITERATIONS)
+ token_total = 0
+ compaction_threshold = payload.get("compaction_threshold")
+ thinking_accumulated = ""
+ final_content: Optional[str] = None
+ usage_total: Dict[str, int] = {}
+
+ # ---- Main loop --------------------------------------------------
+ for iteration in range(max_iterations):
+ workflow.logger.info(
+ f"AgentWorkflow iteration {iteration} "
+ f"(messages={len(messages)} tools={len(tools)})"
+ )
+
+ # Strip per-turn fields the activity doesn't need.
+ llm_payload = {
+ "provider": payload["provider"],
+ "model": payload["model"],
+ "api_key": payload["api_key"],
+ "messages": messages,
+ "tools": [
+ {
+ "name": t["name"],
+ "description": t.get("description", ""),
+ "args_schema": t.get("args_schema", {}),
+ }
+ for t in tools
+ ],
+ "system_message": system,
+ "temperature": payload.get("temperature", 0.7),
+ "max_tokens": payload.get("max_tokens", 4096),
+ "thinking_config": payload.get("thinking_config"),
+ }
+
+ step_result = await workflow.execute_activity(
+ "agent.execute_llm_step.v1",
+ args=[llm_payload],
+ start_to_close_timeout=LLM_STEP_TIMEOUT,
+ retry_policy=AGENT_ACTIVITY_RETRY,
+ )
+
+ # Accumulate usage + thinking for the eventual return value.
+ for k, v in (step_result.get("usage") or {}).items():
+ if isinstance(v, int):
+ usage_total[k] = usage_total.get(k, 0) + v
+ if step_result.get("thinking"):
+ if thinking_accumulated:
+ thinking_accumulated += (
+ f"\n\n--- Iteration {iteration + 1} ---\n"
+ + step_result["thinking"]
+ )
+ else:
+ thinking_accumulated = step_result["thinking"]
+
+ kind = step_result.get("kind")
+
+ if kind == "final":
+ # Persist the final turn and exit.
+ final_content = step_result.get("content", "")
+ messages.append({"role": "assistant", "content": final_content})
+ await self._persist_turn(
+ payload, human_text=user_prompt, assistant_text=final_content
+ )
+ break
+
+ if kind != "tool_calls":
+ workflow.logger.error(
+ f"AgentWorkflow: unexpected LLM step kind={kind!r}"
+ )
+ break
+
+ # ---- Schedule tool activities -------------------------------
+ calls = step_result.get("calls") or []
+ workflow.logger.info(f"AgentWorkflow scheduling {len(calls)} tool call(s)")
+
+ # Append the assistant turn with tool_calls before scheduling
+ # so subsequent ToolMessage entries reference back to it.
+ messages.append({
+ "role": "assistant",
+ "content": "",
+ "tool_calls": calls,
+ })
+
+ for call in calls:
+ tool_info = tool_index.get(call.get("name", ""))
+ if tool_info is None:
+ workflow.logger.warning(
+ f"AgentWorkflow: LLM called unknown tool {call.get('name')!r}; "
+ "returning error to model"
+ )
+ messages.append({
+ "role": "tool",
+ "tool_call_id": call.get("id", ""),
+ "name": call.get("name", ""),
+ "content": (
+ f"Error: tool {call.get('name')!r} is not "
+ "connected to this agent."
+ ),
+ })
+ continue
+
+ tool_payload = {
+ "node_id": tool_info["tool_node_id"],
+ "node_type": tool_info["node_type"],
+ "node_data": {**(tool_info.get("parameters") or {}), **(call.get("args") or {})},
+ "inputs": {},
+ "workflow_id": payload.get("workflow_id"),
+ "session_id": payload.get("session_id", "default"),
+ "nodes": [], # tool activity doesn't need full canvas
+ "edges": [],
+ }
+
+ tool_activity_name = (
+ f"node.{tool_info['node_type']}.v{tool_info['version']}"
+ )
+
+ try:
+ tool_result = await workflow.execute_activity(
+ tool_activity_name,
+ args=[tool_payload],
+ start_to_close_timeout=TOOL_STEP_TIMEOUT,
+ heartbeat_timeout=TOOL_HEARTBEAT_TIMEOUT,
+ )
+ tool_content = _serialise_tool_result(tool_result)
+ except Exception as e: # noqa: BLE001 — Temporal handles retries
+ # After all retries exhausted, surface the error to
+ # the LLM (per user decision: LLM sees error and
+ # continues — matches LangGraph today).
+ workflow.logger.warning(
+ f"AgentWorkflow tool {tool_info['node_type']!r} failed: {e}"
+ )
+ tool_content = (
+ f'{{"error": "{type(e).__name__}: {e}"}}'
+ )
+
+ messages.append({
+ "role": "tool",
+ "tool_call_id": call.get("id", ""),
+ "name": call.get("name", ""),
+ "content": tool_content,
+ })
+
+ # ---- Persist this turn (append-per-turn) -------------------
+ # Snapshot the most recent user/assistant pair into memory.
+ await self._persist_turn(
+ payload,
+ human_text=user_prompt,
+ assistant_text="", # interim turn — body lives in tool_results
+ interim=True,
+ )
+
+ # ---- Compaction check --------------------------------------
+ token_total = sum(
+ v for k, v in usage_total.items()
+ if k in ("input_tokens", "output_tokens")
+ )
+ if (
+ compaction_threshold
+ and token_total >= compaction_threshold
+ and memory_markdown
+ ):
+ workflow.logger.info(
+ f"AgentWorkflow compaction triggered: {token_total} tokens"
+ )
+ compact_result = await workflow.execute_activity(
+ "agent.compact_memory.v1",
+ args=[{
+ "session_id": payload.get("session_id", "default"),
+ "node_id": payload["node_id"],
+ "memory_content": memory_markdown,
+ "provider": payload["provider"],
+ "api_key": payload["api_key"],
+ "model": payload["model"],
+ }],
+ start_to_close_timeout=COMPACT_MEMORY_TIMEOUT,
+ retry_policy=AGENT_ACTIVITY_RETRY,
+ )
+ summary = compact_result.get("summary", "")
+ if summary:
+ # Replace the running messages with the summary
+ # plus the last user prompt — same pattern
+ # ``CompactionService`` uses today in services/ai.py.
+ messages = [
+ {"role": "system", "content": system},
+ {"role": "system", "content": f"## Compacted summary:\n{summary}"},
+ {"role": "user", "content": user_prompt},
+ ]
+ memory_markdown = summary
+ usage_total = {}
+
+ else:
+ # Loop exited without break -- hit max_iterations.
+ workflow.logger.warning(
+ f"AgentWorkflow hit max_iterations={max_iterations}; truncating"
+ )
+ final_content = final_content or (
+ "[AgentWorkflow truncated after max_iterations; "
+ "the model did not produce a final response]"
+ )
+
+ return {
+ "success": True,
+ "result": {
+ "response": final_content,
+ "thinking": thinking_accumulated or None,
+ "model": payload.get("model"),
+ "provider": payload.get("provider"),
+ "usage": usage_total,
+ },
+ }
+
+ # ---- Private helpers ------------------------------------------------
+
+ async def _persist_turn(
+ self,
+ payload: Dict[str, Any],
+ *,
+ human_text: str,
+ assistant_text: str,
+ interim: bool = False,
+ ) -> None:
+ """Schedule the ``agent.persist_turn.v1`` activity.
+
+ Skips when no memory node is connected (the agent has no
+ ``simpleMemory`` neighbour).
+ """
+ memory_node_id = payload.get("memory_node_id") or ""
+ if not memory_node_id:
+ return
+ # Interim turns (tool-call mid-loops) are append-only with
+ # empty assistant text; the next final turn fills it in.
+ if interim and not assistant_text:
+ return
+ await workflow.execute_activity(
+ "agent.persist_turn.v1",
+ args=[{
+ "memory_node_id": memory_node_id,
+ "human_text": human_text,
+ "assistant_text": assistant_text,
+ "window_size": int(payload.get("memory_window_size") or 10),
+ }],
+ start_to_close_timeout=PERSIST_TURN_TIMEOUT,
+ retry_policy=AGENT_ACTIVITY_RETRY,
+ )
+
+
+def _serialise_tool_result(result: Any) -> str:
+ """Return a string body for a ``ToolMessage``.
+
+ LangChain's ``ToolMessage.content`` expects a string. The plugin's
+ activity returned a dict; serialise it as JSON. Falls back to
+ ``str(result)`` if the dict isn't JSON-serialisable (rare).
+ """
+ import json as _json
+
+ if isinstance(result, str):
+ return result
+ try:
+ return _json.dumps(result, default=str)
+ except Exception: # noqa: BLE001 — defensive
+ return str(result)
diff --git a/server/services/temporal/worker.py b/server/services/temporal/worker.py
index e9e57d23..29ad565e 100644
--- a/server/services/temporal/worker.py
+++ b/server/services/temporal/worker.py
@@ -112,16 +112,26 @@ class TemporalWorkerManager:
# filtering will move there. Registration cost: ~1.6s startup;
# zero runtime cost when the flag is off (orchestrator routes to
# execute_node_activity, per-type entries sit idle).
+ #
+ # F4.B: register AgentWorkflow + its three activities
+ # (execute_llm_step / persist_turn / compact_memory). The
+ # orchestrator schedules AgentWorkflow as a child workflow
+ # for the 15 migrating agent types when
+ # ``temporal_agent_workflow_enabled`` is on.
from services.temporal.plugin_activities import collect_plugin_activities
+ from services.temporal.agent_activities import collect_agent_activities
+ from services.temporal.agent_workflow import AgentWorkflow
per_type = collect_plugin_activities() # no queue filter; all plugins
+ agent_activities = collect_agent_activities()
self._worker = Worker(
self.client,
task_queue=self.task_queue,
- workflows=[MachinaWorkflow],
+ workflows=[MachinaWorkflow, AgentWorkflow],
activities=[
self._activities.execute_node_activity,
*per_type,
+ *agent_activities,
],
# Allow concurrent activity execution for parallel branches
max_concurrent_activities=self.pool_size,
@@ -131,6 +141,7 @@ class TemporalWorkerManager:
"Registered Temporal activities",
legacy=1,
per_type=len(per_type),
+ agent=len(agent_activities),
task_queue=self.task_queue,
)
span.set_attribute("task_queue", self.task_queue)
diff --git a/server/tests/temporal/test_agent_workflow.py b/server/tests/temporal/test_agent_workflow.py
new file mode 100644
index 00000000..8c736411
--- /dev/null
+++ b/server/tests/temporal/test_agent_workflow.py
@@ -0,0 +1,130 @@
+"""F4.B infrastructure tests for ``AgentWorkflow`` + agent activities.
+
+Smoke-level coverage so the worker bootstraps cleanly and the activity
+shapes match what ``AgentWorkflow`` expects to schedule. Full
+end-to-end testing of the agent loop (LLM step → tool dispatch →
+persist → compaction) requires a Temporal test cluster + real plugin
+classes — that lives in test_agent_workflow_integration.py once the
+canary agent migration lands. This file locks the static contracts:
+
+- AgentWorkflow class is decorated with ``@workflow.defn``.
+- Three activities are decorated with ``@activity.defn`` and carry the
+ expected ``node`` names.
+- ``collect_agent_activities()`` returns them in a stable order.
+- The orchestrator's worker registration imports both without error.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+class TestAgentWorkflowDefinition:
+ """``AgentWorkflow`` must be a valid Temporal workflow definition
+ so workers can register it."""
+
+ def test_class_is_workflow_defn(self):
+ from services.temporal.agent_workflow import AgentWorkflow
+
+ # ``@workflow.defn`` attaches metadata as ``__temporal_workflow_definition``.
+ defn = getattr(AgentWorkflow, "__temporal_workflow_definition", None)
+ assert defn is not None, "AgentWorkflow missing @workflow.defn"
+ assert defn.name == "AgentWorkflow"
+
+ def test_class_is_sandboxed_false(self):
+ """Workflow needs to import frozen registry dicts deterministically
+ (for tool type → activity name resolution). Sandboxing must be off
+ — same as MachinaWorkflow."""
+ from services.temporal.agent_workflow import AgentWorkflow
+
+ defn = getattr(AgentWorkflow, "__temporal_workflow_definition")
+ assert defn.sandboxed is False, (
+ "AgentWorkflow must be sandboxed=False so it can read "
+ "services.node_registry deterministically"
+ )
+
+
+class TestAgentActivities:
+ """The three agent activities must register under stable names so
+ ``AgentWorkflow`` can schedule them by string."""
+
+ def test_execute_llm_step_registered(self):
+ from services.temporal.agent_activities import execute_llm_step
+
+ defn = getattr(execute_llm_step, "__temporal_activity_definition", None)
+ assert defn is not None
+ assert defn.name == "agent.execute_llm_step.v1"
+
+ def test_persist_agent_turn_registered(self):
+ from services.temporal.agent_activities import persist_agent_turn
+
+ defn = getattr(persist_agent_turn, "__temporal_activity_definition")
+ assert defn.name == "agent.persist_turn.v1"
+
+ def test_compact_agent_memory_registered(self):
+ from services.temporal.agent_activities import compact_agent_memory
+
+ defn = getattr(compact_agent_memory, "__temporal_activity_definition")
+ assert defn.name == "agent.compact_memory.v1"
+
+ def test_collect_returns_all_three(self):
+ from services.temporal.agent_activities import collect_agent_activities
+
+ activities = collect_agent_activities()
+ names = sorted(
+ getattr(a, "__temporal_activity_definition").name for a in activities
+ )
+ assert names == [
+ "agent.compact_memory.v1",
+ "agent.execute_llm_step.v1",
+ "agent.persist_turn.v1",
+ ]
+
+
+class TestWorkerWiring:
+ """Worker registration must include AgentWorkflow + activities so the
+ orchestrator can schedule them once the flag flips on. We can't
+ spin up a real Temporal client here, but we can verify the
+ registration list is built without import errors."""
+
+ def test_agent_workflow_importable_from_worker(self):
+ """The worker module imports AgentWorkflow at registration time.
+ If that import fails (circular dep, missing symbol, etc.) the
+ whole Temporal worker bootstrap dies — catch it here."""
+ # Just importing is enough; ImportError would surface in the test
+ # output.
+ from services.temporal.worker import TemporalWorkerManager # noqa: F401
+ from services.temporal.agent_workflow import AgentWorkflow # noqa: F401
+ from services.temporal.agent_activities import collect_agent_activities # noqa: F401
+
+
+class TestPayloadShape:
+ """Static checks on the workflow's payload contract — keeps the
+ seams visible to anyone refactoring the input pipeline. If a
+ required key disappears, this test surfaces it before runtime."""
+
+ REQUIRED_KEYS = (
+ "node_id",
+ "node_type",
+ "provider",
+ "model",
+ "api_key",
+ "system_message",
+ "user_prompt",
+ "tools",
+ "max_iterations",
+ )
+
+ def test_required_keys_documented(self):
+ """The README-style payload comment in ``AgentWorkflow.run``'s
+ docstring must list every required key. Drift = unreadable
+ docs + broken callers. Cross-check against an explicit
+ constant here so the docstring can't quietly shrink."""
+ from services.temporal.agent_workflow import AgentWorkflow
+
+ docstring = AgentWorkflow.run.__doc__ or ""
+ missing = [k for k in self.REQUIRED_KEYS if f'"{k}"' not in docstring]
+ assert not missing, (
+ f"AgentWorkflow.run docstring missing payload keys: {missing}. "
+ "If you renamed a field, update both the docstring and the body."
+ )