> ## Documentation Index > Fetch the complete documentation index at: https://docs.acornops.dev/llms.txt > Use this file to discover all available pages before exploring further. # Use Agents and Workflows > Create reusable specialists, launch Workflows, and review their runs Every new workspace receives the starter automation bundle during provisioning. The workspace, owner membership, definitions, completed installation marker, and audit events commit atomically before workspace creation returns. Definitions record an origin of `manual` or `template`. Origin does not add capabilities, bypass authorization, alter readiness, or choose a different execution path. Workspace-owned starter definitions may be edited, disabled, duplicated, or deleted. A completed installation marker remains as a tombstone, so deleting starter content does not silently recreate it. Existing workspaces and operator edits are not overwritten when the shipped starter bundle changes. An explicit **Use template** reinstall is required to restore deleted starter content. Readiness is explicit for every definition: * `ready` means the saved definition and its assigned Agents can provide their reviewed capability ceiling. * `needs_setup` lists missing live prerequisites such as a reviewed capability mapping or installed integration. * `blocked` identifies a policy or capability mismatch that an administrator must resolve. Missing configuration never activates fallback Agents, tools, MCP servers, credentials, or workflows. ## Specialist Agents Workspace administrators create specialist Agents through the editor or API. A specialist receives reviewed semantic capabilities and exact operational resources from the live catalog. New workspaces start with two workspace-owned specialists: * **Kubernetes Agent** specializes in Kubernetes operations. It can use reviewed read and write tools exposed through the generic **Targets** MCP server. Every write remains approval-gated. * **Virtual Machine Agent** specializes in Linux virtual-machine diagnostics. It requests read-only diagnostic capability and does not request remediation capability, so it is ready without AgentV's optional privileged helper. When AgentK or AgentV connects, AcornOps records the built-in tools advertised by that target. Reviewed built-in tools are projected through a workspace-level `targets` MCP facade; Agents and Workflows do not store target IDs or target types. Each target is selected and validated from `target_id` and `target_type` only when the tool is called. An administrator can disable the built-in server or individual tools. If AgentV advertises `restart_service`, its catalog entry is enabled, but an administrator must explicitly grant remediation capability before an Agent can use it. The starter Agents also retain the PDF tool used by the current reporting Workflows. Coordination is system-owned. The coordinator is a code-owned Workflow executor, not an Agent. Its profile is snapshotted into each new coordinator root attempt and is never exposed through Agent APIs. A coordinated workflow asks AcornOps to perform work for a semantic capability. Delegation selects an eligible specialist from the Workflow's assigned Agents by reviewed mapping priority and stable Agent ID. It intersects Agent capabilities, principal permissions, workspace policy, and connection readiness. If the specialist calls the generic `targets` MCP server, that individual call supplies the target identity. Semantic labels never authorize tools on their own. Coordination is one level deep and allows at most four concurrent child runs and eight child runs total. These limits are server-owned. Writes require approval for the exact tool and arguments. AcornOps does not automatically retry after execution starts or after a write has an uncertain result. Successful child results remain available if another child fails; required and optional failures are reported separately. ## Workflows A Workflow contains a plain-text prompt, required `agentIds`, a semantic capability policy, and optional schedule configuration. Agent selection is a set; array order has no routing meaning and IDs must be unique and non-empty. Select one Agent to run the Workflow directly. Select two or more Agents for AcornOps to coordinate. Workflow responses derive `executionMode` as `direct` or `coordinated`; it is not an authoring input. Creating a Workflow session records a non-executable capability ceiling. The first structured launch message contains only `kind: "launch"` and an optional idempotency key. The control plane compiles the saved prompt and revalidates current authorization under the authenticated user. Semantic capability IDs such as `infrastructure.diagnostics.read` describe routing requirements but never authorize a tool by themselves. Existing runs keep their pinned execution mode and scope when you edit a Workflow. Future runs use the new definition and live provider state. ## Saved prompts Workflow prompts are saved plain text and do not accept runtime parameters. Launches from the console, schedules, webhooks, and external integrations all run the same saved definition. Literal `{{...}}` text has no template meaning. Workflows do not bind targets. Name a target in the prompt when the task needs one. The model interprets that text and may call an eligible target MCP tool with the corresponding `target_id`. This is intentionally non-deterministic: an ambiguous, unknown, or unavailable target is reported only if the model attempts that tool call. Workflows that do not concern infrastructure targets, such as source-control automation, simply use the other tools on their assigned Agents. The capability policy has two explicit modes: * `inherit` uses the selected Agents' current combined reviewed ceiling. `semanticCapabilityIds` must be empty. Each new session resolves and pins the effective set, so an Agent grant or revocation affects future sessions without expanding an existing run. * `restrict` uses `semanticCapabilityIds` as an explicit subset of the selected Agents' combined ceiling. An empty array intentionally creates a zero-capability workflow. The management console sends the capability-policy mode explicitly. Manual Workflow defaults are server-owned. When policy fields are omitted, the control plane uses read-only mode, inherited Agent capabilities, workspace metadata context, workspace-data permission, and no approval requirements. The management console sends only the operator-controlled restriction choice and semantic subset. Execution duration and generated-document retention are deployment policies, not per-Workflow settings. `AGENT_MAX_RUNTIME_MS` sets the execution limit. `GENERATED_DOCUMENT_RETENTION_DAYS` sets document retention. Legacy API requests may still include `maxRuntimeSeconds` or `retentionDays`, but the control plane ignores those values and returns the effective deployment policy. Direct readiness checks the selected specialist. Coordinated readiness requires an eligible selected specialist mapping for every effective capability. Each automatic health check selects its matching specialist directly. Kubernetes-only remediation selects the Kubernetes Agent, while Incident investigation coordinates both Agents. Before **Launch**, the console requests a capability preview. Definition review keeps semantic capabilities separate from direct MCP servers, installed skills, and directly attached tools. It lists target MCP tools inherited from the assigned Agents without selecting or evaluating a target. Write rows identify their approval requirement. Credentialed MCP dependencies appear in a **Required auth** row with the server name, personal or workspace ownership, credential label, and required setup information. The preview never returns the credential value. The preview does not create a session or reserve access; launch revalidates current authority and the dispatched run's compiled scope is the final source of truth. The signed run scope limits target MCP calls to exact generic Targets MCP tool references allowed by reviewed mappings. The automatic VM health check and starter VM Agent remain read-only even when AgentV advertises `restart_service`. The current opt-in Infrastructure remediation template instructs its assigned Kubernetes specialist to operate on a Kubernetes target named in the request; the Agent's Targets MCP policy remains authoritative. The template drawer exposes these Workflow records: | Workflow | Install mode | Behavior | | ---------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Kubernetes health check | Automatic, active | Reviews available Kubernetes targets for workload readiness, pod restarts, warning events, resource pressure, and relevant logs without making changes. | | Virtual machine health check | Automatic, active | Reviews available Linux VMs for host and filesystem pressure, processes, listeners, degraded systemd services, and allowlisted journal logs without making changes. | | Infrastructure remediation | Opt-in, paused | Diagnoses and changes a Kubernetes environment named in the request. Approval is required before every write. | | Incident investigation | Opt-in, paused | Coordinates diagnostics and reporting from the targets and context named in the request. | Template manifests contain prose, safe policy defaults, semantic requirements, and symbolic relationships only. Provisioning generates record IDs and resolves relationships inside the workspace transaction. It does not contain workspace or target IDs, MCP server IDs or URLs, external tool aliases, skill installation IDs, credentials, or connection assumptions. Shipped bundle changes do not overwrite existing workspace-owned definitions. Schedules store cadence and principal—not launch inputs or access grants. Every occurrence compiles the current active saved prompt and execution scope from the assigned Agent capabilities. An invalid definition, deletion, integration outage, membership change, or authorization failure auto-pauses the schedule with a bounded actionable reason; repair the cause and resume it manually. ## Organize workflows and Activity Open **Workflows** in the management console to use three views: * **All Workflows** contains installed Workflow definitions and manual launch. * **Schedules** contains recurring Workflow dispatches. * **Incoming Webhooks** contains signed endpoints that start Workflows from external systems. Open **Activity** from Automation to see open and historical executions across the workspace. Its navigation badge shows the number of open executions. The Activity ledger defaults to open work. You can search it or filter by state, origin, Workflow, and issue. Each row identifies the Workflow, the schedule or webhook that started it, its current state, start or completion time, and an exact execution link. A target appears only on a recorded target tool call or approval. Issue rows show related automation directly on the workspace, Kubernetes, and virtual-machine issue surfaces. Use **Review run** for approval or review states, **Open run** for one active execution, or **View activity** when several executions relate to the same issue. Manual triage remains available. Schedule and incoming-webhook rows keep three facts separate: * **Configuration** shows whether the schedule or webhook is enabled or paused. * **Last dispatch** shows whether the latest occurrence dispatched, failed, was rejected, or was skipped. * **Latest execution** shows the actual run state when dispatch created one. A dispatch failure does not appear as a running execution and does not erase the previous successful run link. AcornOps retains the run's origin label even if you later delete the schedule or webhook. **Outbound webhooks** is a separate Automation destination. Outbound webhooks send AcornOps events to another system; incoming workflow webhooks start an AcornOps Workflow. ## Create a custom workflow AcornOps does not install a repository-review Agent or workflow. When you need a repository-oriented or other external workflow: 1. Create a specialist Agent with the instructions and permission mode you need. 2. Attach a compatible MCP server from the Agent's **MCP** page. 3. Connect personal authentication when required, discover its tools, and review each exact tool. 4. Create a workflow and select that Agent. 5. Preview the effective scope before activation. The same user-created path works for any compatible MCP integration; there is no provider-specific workflow template or hidden Agent identity. Visible starter Workflows can be deleted. Deleting a starter specialist Agent first returns a conflict that lists dependent Workflows; remove it from those Workflows, then delete the Agent. AcornOps keeps its coordination infrastructure available even when no coordinated Workflow exists. For a coordinated execution, `GET /api/v1/workflow-executions/{executionId}` includes an `AcornOps coordination` summary. Each child shows its capability, selected Agent, status, and a bounded failure when applicable. The response excludes internal coordinator identity, task prompts, compiled scopes, results, credentials, and tool arguments. ## Target-native chat Kubernetes and virtual-machine chat does not select, pin, or hand off to a workspace Agent. Each session automatically uses the target's generic assistant. At run creation, AcornOps queries the live target capability registry and pins the exact native tools, target MCP tools, and target skill snapshots permitted by the user, requested tool-access mode, AgentK or AgentV advertisement, and current target/workspace policy. Configured third-party target MCP tools are eligible when their real connection is ready. Authorization is rechecked before every tool call, and target instructions come from the target adapter contract rather than a workspace Agent profile. ## External integration sessions A linked external integration can launch an active Workflow when its client ceiling, user-approved workspace grant, and linked user role include the required capability. Ungated read-only Workflows require `create_read_only_runs`. Read-write and approval-gated Workflows also require `create_read_write_runs`. The Workflow session is the persistent conversation. It accepts one successful `launch` message, followed by ordinary `follow_up` messages. Every interactive launch creates a fresh session. An idempotent retry of the same launch returns the original execution; a second launch is rejected. A direct execution creates a specialist root run; a coordinated execution creates a coordinator root and its specialist child runs. Keep the session ID as the external thread mapping. Resource parameter IDs are retained by the session and reauthorized on each follow-up. Replies after completion use the same stored Workflow snapshot and retained history, but require a new `clientRequestId` and fresh approvals. Use the sanitized execution endpoint for current state and the aggregate execution SSE stream for step/run discovery, approvals, safe outputs, and the terminal event. Workspace readers may inspect these safe views regardless of origin. Only the exact originating integration link/client may post external replies, decide approvals, or retrieve reports. ## Delivery guarantees The control plane acknowledges a run only after Postgres commits the run and its dispatch intent. Workers claim work with database row locks, so multiple replicas can recover pending work after a restart. Dispatch is at least once, and the execution engine treats the run idempotency key as a stable identity. Dispatch, continuation, approval, and tool execution consume the persisted compiled scope and may only narrow it. Membership, RBAC, status, connection readiness, and token validity are rechecked at dispatch; live authorization is rechecked before every tool call. Approvals expire after 15 minutes by default. Expiry fails the attempt and does not grant the requested capability. ## Workflow execution Workflows are the only runnable automation aggregate. Agents are reusable, versioned specialist capability profiles; they never own or start runs. A one-Agent Workflow creates a specialist root. A multi-Agent Workflow creates a coordinator root, and delegation creates specialist children beneath that root. Rootness is represented by the absence of a parent run, not by a separate executor role. Use a Workflow schedule when you need unattended execution. A linked external integration can launch an active Workflow when its grant permits it. AcornOps does not currently expose a generic public inbound webhook that starts a Workflow. Platform administrators control rollout modes, runtime limits, and operational alerts separately from Workflow authoring. See [Configure automation runtime](/deploy/automation-runtime).