Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(temporal): AgentWorkflow + agent activities infrastructure (F4.B)
trohitga4d009e4b12d
diff --git a/server/core/config.py b/server/core/config.pyindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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 AgentWorkflowper_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 branchesmax_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.pynew file mode 100644index 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."+ )