Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs: F4.B Temporal-native delegation + Perplexity probe-skip note
trohitgfb58ab74a682
diff --git a/CLAUDE.md b/CLAUDE.mdindex 4ca4a4c9..cf4fe12a 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -932,6 +932,8 @@ Search API nodes that work BOTH as standalone workflow nodes AND as AI Agent too- Brave Search and Perplexity in **Search** category- Serper in **Scrapers** category (Google SERP scraping)+**Perplexity validation note:** `PerplexityCredential._probe` short-circuits to `ProbeResult(valid=True)` without an HTTP call — Perplexity exposes no cheap auth-gated endpoint (`/v1/models` returns 200 for any key including garbage; every other endpoint charges tokens, and `chat/completions` rejects `max_tokens<16` for `sonar` with HTTP 400 before checking auth). Runtime calls will surface 401 if the key is wrong. `ProbeResult` is exported from `services.plugin` for `_probe` overrides like this.+### Specialized AI Agents (15 nodes)Specialized agents are AI Agents pre-configured for specific domains. They inherit full AI Agent functionality (provider, model, prompt, system message, thinking/reasoning) while being tailored for specific capabilities. All specialized agents dispatch through `BaseNode.execute()` via the node registry (Wave 11) and support the same input handles. Node colors use centralized dracula theme constants imported from `client/src/styles/theme.ts`.@@ -1630,7 +1632,7 @@ server/nodes/document/Workflows execute via Temporal for durability and horizontal scaling. Three dispatch paths (legacy `execute_node_activity` / per-type `node.{type}.v{version}` (F4.A) / Agent-as-child-workflow (F4.B)) gated by `TEMPORAL_PER_TYPE_DISPATCH` and `TEMPORAL_AGENT_WORKFLOW_ENABLED` settings flags.-Full architecture, dispatch matrix, per-node lifecycle, heartbeat semantics, the 14 migrating agent types + 2 bypass agents (rlm_agent / claude_code_agent), the 6 F4.B agent activities (`prepare_payload.v1` / `execute_llm_step.v1` / `persist_turn.v1` / `compact_memory.v1` / `store_output.v1` / `broadcast_progress.v1`), and the future `TemporalWorkerPool` per-queue routing live in [docs-internal/TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md). Tool-call dispatch under F4.A documented at [docs-internal/tool_building_pipeline.md §9](./docs-internal/tool_building_pipeline.md).+Full architecture, dispatch matrix, per-node lifecycle, heartbeat semantics, the 14 migrating agent types + 2 bypass agents (rlm_agent / claude_code_agent), the 6 F4.B agent activities (`prepare_payload.v1` / `execute_llm_step.v1` / `persist_turn.v1` / `compact_memory.v1` / `store_output.v1` / `broadcast_progress.v1`), the **`delegate_to_<x>` Temporal-native dispatch** (child agent type in `AGENT_WORKFLOW_TYPES` → `workflow.execute_child_workflow` with `parent_node_id` propagation + parent-mirror in `_emit_phase` so the parent's canvas badge advances live; falls through to `execute_activity` otherwise), and the future `TemporalWorkerPool` per-queue routing live in [docs-internal/TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md). Tool-call dispatch under F4.A documented at [docs-internal/tool_building_pipeline.md §9](./docs-internal/tool_building_pipeline.md).**Configuration** (`.env.template` — canonical defaults; `.env` layers user overrides):```env@@ -2486,7 +2488,12 @@ Both call corresponding AI service methods:AI Agents can delegate tasks to other agents connected to their `input-tools` handle. This enables hierarchical agent architectures where a parent agent can spawn child agents that work independently.-**Architecture: Fire-and-Forget Pattern**+**Two execution paths** depending on whether the parent runs under Temporal F4.B:++- **F4.B (default)**: parent `AgentWorkflow` spawns the child as a **child `AgentWorkflow`** via `workflow.execute_child_workflow` when the child type is in `AGENT_WORKFLOW_TYPES`. Parent's `node_id` is passed in `child_context["parent_node_id"]` so the child's `_emit_phase` mirrors progress onto the parent's canvas badge (parent badge advances live alongside child iteration counter instead of freezing). Deterministic child workflow id `f"{parent_workflow_id}-delegate-{child_node_id}-{iteration}"`. Parent waits for child result through the child-workflow handle — synchronous within the parent's loop.+- **Legacy / F4.A-only**: the fire-and-forget pattern below. Still the path for `rlm_agent` / `claude_code_agent` (excluded from `AGENT_WORKFLOW_TYPES`) and any deployment with `TEMPORAL_AGENT_WORKFLOW_ENABLED=false`.++**Architecture: Fire-and-Forget Pattern (legacy / F4.A)**```Parent Agent calls "delegate_to_ai_agent" tool|@@ -2501,7 +2508,7 @@ Child Agent executes independently in backgroundChild broadcasts its own status updates (executing, success, error)```-**How It Works:**+**How It Works (legacy / F4.A):**1. Connect a Child Agent (aiAgent/chatAgent) to Parent Agent's `input-tools` handle2. Parent sees a tool like `delegate_to_ai_agent` with schema `{task: string, context?: string}`3. When Parent calls the tool, handler spawns Child as `asyncio.create_task()`diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.mdindex 4dca5890..a6803ba0 100644--- a/docs-internal/TEMPORAL_ARCHITECTURE.md+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md@@ -301,7 +301,12 @@ AgentWorkflow.run(context):3. if kind == "tool_calls":for each call:emit_phase("executing_tool", tool_name=...)- execute_activity(f"node.{tool_node_type}.v{version}")+ if delegate_to_* AND child type in AGENT_WORKFLOW_TYPES:+ execute_child_workflow("AgentWorkflow", child_context)+ child_context = {**tool_payload, "parent_node_id": <self>}+ id = f"{parent_workflow_id}-delegate-{child_node_id}-{iter}"+ else:+ execute_activity(f"node.{tool_node_type}.v{version}")emit_phase("tool_completed", tool_name=...)_serialise_tool_result unwraps F4.A's {success, result, ...}envelope so the LLM sees only the handler's return value@@ -323,9 +328,9 @@ AgentWorkflow.run(context):emit_phase("completed", status="success")```-`emit_phase(phase, status?)` is a thin helper that schedules `agent.broadcast_progress.v1`. The activity emits `WorkflowEvent.agent_progress` (CloudEvents v1.0, `type="com.machinaos.agent.progress"`) for FE consumers; when `status` is supplied it also drives a raw-dict `update_node_status` for the canvas-glow color (executing / success / error). Same dual-channel pattern F4.A's `_node_activity` uses.+`emit_phase(phase, status?)` is a thin helper that schedules `agent.broadcast_progress.v1`. The activity emits `WorkflowEvent.agent_progress` (CloudEvents v1.0, `type="com.machinaos.agent.progress"`) for FE consumers; when `status` is supplied it also drives a raw-dict `update_node_status` for the canvas-glow color (executing / success / error). Same dual-channel pattern F4.A's `_node_activity` uses. When this workflow is itself a delegated child (`context["parent_node_id"]` set), every `emit_phase` call ALSO schedules a second broadcast against the parent's `node_id` with `phase="delegating"` — the parent's canvas badge then advances in real time while the child loops, instead of freezing at "executing" glow until the child completes.-Each LLM step is one activity, each tool call is one per-type activity (the same activities F4.A registered). Failures of tool activities surface as error messages back to the LLM (matching the in-process agent loop behaviour); the agent loop continues.+Each LLM step is one activity, each tool call is one per-type activity (the same activities F4.A registered). **Delegation tool calls** (`delegate_to_<x>`) where the child type is in `AGENT_WORKFLOW_TYPES` are the exception: they spawn a child `AgentWorkflow` via `workflow.execute_child_workflow` instead of a per-type activity, with `parent_node_id` injected into `child_context` to enable the parent-mirror broadcast above. Deterministic child workflow id is `f"{parent_workflow_id}-delegate-{child_node_id}-{iteration}"` so Temporal retries don't spawn duplicates. Non-agent tools and excluded types (`rlm_agent`, `claude_code_agent`) still go through `execute_activity` as before. Failures of tool activities surface as error messages back to the LLM (matching the in-process agent loop behaviour); the agent loop continues.**Broadcasts inside the loop** wrap `WorkflowEvent` (CloudEvents v1.0) per RFC §6.4: `agent_progress` events (`com.machinaos.agent.progress`) and `node_parameters_updated` events (`com.machinaos.node.parameters.updated`) flow through the `StatusBroadcaster.broadcast_agent_progress` and `StatusBroadcaster.broadcast_node_parameters_updated` wrappers respectively. The latter is reused by the legacy `routers/websocket.py:handle_save_node_parameters` (user-source) and `services/cli_agent/service.py:_persist_memory` (cli-source) — all three emission sites share the same envelope, distinguished by `source_hint` (`"user"` / `"cli"` / `"agent"`).diff --git a/docs-internal/agent_delegation.md b/docs-internal/agent_delegation.mdindex bbb7072a..43c086c8 100644--- a/docs-internal/agent_delegation.md+++ b/docs-internal/agent_delegation.md@@ -6,9 +6,14 @@ How memory, parameters, and execution context flow when one AI agent delegates w## Overview-AI Agents can delegate tasks to other agents connected to their `input-tools` handle. The parent agent's LLM decides when to call the child agent by invoking a `delegate_to_<agent>` tool. The child spawns as an independent `asyncio.Task` and the parent continues working immediately -- a **fire-and-forget** pattern.+AI Agents can delegate tasks to other agents connected to their `input-tools` handle. The parent agent's LLM decides when to call the child agent by invoking a `delegate_to_<agent>` tool.-The parent passes only a `task` string and optional `context` string. Everything else -- the child's provider, model, system message, memory, skills, and tools -- comes from the child's own configuration and workflow connections.+**Two execution paths** depending on whether the parent is running under Temporal F4.B:++- **F4.B (default, `TEMPORAL_AGENT_WORKFLOW_ENABLED=true`):** the delegation tool dispatch inside `AgentWorkflow` spawns the child as a **child `AgentWorkflow`** via `workflow.execute_child_workflow`. Parent's `node_id` is passed in `child_context["parent_node_id"]` so the child's `_emit_phase` mirrors progress onto the parent canvas badge. Parent awaits the child's result synchronously through the Temporal child-workflow handle — see [TEMPORAL_ARCHITECTURE.md §F4.B](./TEMPORAL_ARCHITECTURE.md#agent-as-child-workflow-f4b).+- **Legacy / F4.A-only:** the rest of this doc. `_execute_delegated_agent` spawns the child as an independent `asyncio.Task` and the parent continues working immediately — the **fire-and-forget** pattern. Still the path for `rlm_agent` / `claude_code_agent` (excluded from `AGENT_WORKFLOW_TYPES`) and any deployment with F4.B disabled.++In both paths the parent passes only a `task` string and optional `context` string. Everything else -- the child's provider, model, system message, memory, skills, and tools -- comes from the child's own configuration and workflow connections.## Architecturediff --git a/docs-internal/agent_teams.md b/docs-internal/agent_teams.mdindex 942a4918..60d1302e 100644--- a/docs-internal/agent_teams.md+++ b/docs-internal/agent_teams.md@@ -47,7 +47,7 @@ Both are defined in `TEAM_LEAD_TYPES` in `server/services/handlers/ai.py`.- For "hi" or simple questions → responds directly (no delegation)- For complex tasks → uses appropriate delegation tools-5. **Delegated agents execute** via the standard `_execute_delegated_agent()` flow in `handlers/tools.py`+5. **Delegated agents execute** via the standard `_execute_delegated_agent()` flow in `handlers/tools.py` (legacy / F4.A path), OR — when the parent runs as a Temporal `AgentWorkflow` under F4.B and the child type is in `AGENT_WORKFLOW_TYPES` — as a child `AgentWorkflow` spawned via `workflow.execute_child_workflow` with `parent_node_id` plumbed through `child_context` so the parent canvas badge mirrors child progress. See [agent_delegation.md](./agent_delegation.md#overview) for both paths.## Input Handlesdiff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.mdindex e2ff57f4..b6c64775 100644--- a/docs-internal/plugin_system.md+++ b/docs-internal/plugin_system.md@@ -350,6 +350,16 @@ Declarative credentials live **in each node folder's `_credentials.py`**auto-refresh via `auth_service.get_oauth_tokens`.- `Credential` — fully custom (override `resolve()` + `inject()`).+**Validation probe**: subclasses normally declare `probe_url` /+`probe_method` / `probe_json` so the default `_probe` issues a probe+HTTP request and reads the status code through `_classify_status`. When+the provider has no cheap auth-gated endpoint (Perplexity's `/v1/models`+returns 200 for any key including garbage; every other endpoint charges+tokens), override `_probe` to return `ProbeResult(valid=True)` directly+and let runtime calls surface the 401 — see `nodes/search/perplexity_search/__init__.py`+for the canonical no-probe pattern. `ProbeResult` is exported from+`services.plugin` for this override.+Auto-discovery rides on node-package import. When`nodes/__init__.py:pkgutil.walk_packages` imports a plugin module,that module's `from ._credentials import XCredential` statement