agent-management

Files (1)

• SKILL.md

SKILL.md (first lines)

# Agent Management

Use the native runner tools for agent operations:

- `agents_search`: list or filter existing agents.
- `agents_copy`: copy an agent, including enabled/preloaded skills, agent-local skill files, private secrets that are not already public or package secrets, workspace files, and channel plus cross-channel memory. Pass `federationInstanceId` to copy onto a federated peer.
- `agents_move`: move an agent to another local runner, or pass `federationInstanceId` to move it to a federated peer with the same skill, secret, workspace, and memory bundle. A move stops the agent's running processes. Local moves keep the workspace path.
- `agents_create`: create `CLASSIC`, `RLM_REPL`, or `WRAPPED` agents.
- `agents_update`: patch an existing agent's config, lifecycle state, skills, model, workspace, or wrapped runtime config.
- `events_channel_participant_add` / `events_channel_participant_remove`: manage AGENT or HUMAN channel participants (`agentName` remains supported as a legacy alias for AGENT adds/removes).
- `events_channel_join`: add an agent to a channel when it should receive channel events.

## List Agents

Call `agents_search` first when you need to inspect existing agents, avoid duplicate names, or find runner assignments.

Example:

```json
{
  "nameContains": "coordinator",
  "limit": 20
}
```

## Create Native Agents

For a normal OrgOps-managed LLM agent, use `mode: "CLASSIC"` or omit `mode`. Pick a concrete `modelId`, set a workspace, and enable any required skills.

Example:

```json
{
  "name": "ResearchAgent",
  "mode": "CLASSIC",
  "modelId": "openai:gpt-4o-mini",
  "workspacePath": ".orgops-data/workspaces/ResearchAgent",
  "enabledSkills": ["tavily"],
  "alwaysPreloadedSkills": ["tavily"],
  "joinCurrentChannel": true
}
```

## Create Wrapped Agents

For a wrapped agent, set:

- `mode: "WRAPPED"`
- `modelId: "wrapped:none"` if you provide it explicitly
- `memoryContextMode: "OFF"` or omit it; OrgOps forces wrapped agents to memory OFF
- `enabledSkills: []` and `alwaysPreloadedSkills: []`
- a `wrappedConfig` object with `kind`, `harness`, optional `setup`, optional `sidecars`, and `runtime`

Wrapped agents do not use OrgOps model calls, prompts, memory, skills, or `allowOutsideWorkspace` for turns. The external runtime owns its session, tools, memory, prompt behavior, and filesystem policy through its own settings.

## Update Existing Agents

Use `agents_update` instead of direct database writes. For wrapped agents, prefer `wrappedConfigJson` when patching a whole config from generated JSON; it must parse to a JSON object.

Example:

```json
{
  "agentName": "OrgOpsCoordinator",
  "wrappedConfigJson": "{\"kind\":\"openclaw\",\"harness\":\"command\",\"runtime\":{\"command\":\"./run-openclaw.sh\",\"cwd\":\".orgops-data/workspaces/OrgOpsCoordinator/wrapper\",\"parse\":\"json-payloads\",\"timeoutMs\":600000}}",
  "desiredState": "RUNNING"
}
```

## OpenClaw With Gateway Sidecar

Use OpenClaw when the wrapped runtime is an OpenClaw agent. The OpenClaw sidecar should be the OpenClaw Gateway; OrgOps starts it before turns and the runtime command sends each turn through that gateway.

Example `agents_create` arguments:

```json
{
  "name": "OrgOpsCoordinator",
  "mode": "WRAPPED",
  "workspacePath": ".orgops-data/workspaces/OrgOpsCoordinator",
  "wrappedConfig": {
    "kind": "openclaw",
    "harness": "command",
    "session": { "scope": "per-channel" },
    "setup": {
      "checkCommand": "test -x node_modules/.bin/openclaw",
      "command": "npm install --no-save openclaw",
      "cwd": ".orgops-data/workspaces/OrgOpsCoordinator/wrapper",
      "timeoutMs": 600000
    },
    "sidecars": [
      {
        "name": "gateway",
        "command": "npx openclaw gateway --force",
        "cwd": ".orgops-data/workspaces/OrgOpsCoordinator/wrapper",
        "restart": true,
        "restartDelayMs": 2000,
        "timeoutMs": 0
      }
    ],
    "runtime": {
      "command": "npx openclaw agent --agent coordinator --session-id \"$ORGOPS_WRAPPED_SESSION_ID\" --message \"$ORGOPS_WRAPPED_MESSAGE\" --json",
      "cwd": ".orgops-data/workspaces/OrgOpsCoordinator/wrapper",
      "parse": "json-payloads",
      "timeoutMs": 600000
    }
  },
  "joinCurrentChannel": true
}
```

OpenClaw setup notes:

- OpenClaw is optional and is not installed with OrgOps. Install it in the wrapped agent's workspace during `setup`, or configure `source` to use an OpenClaw checkout.
- Before upgrading an existing OpenClaw agent that relied on OrgOps' root installation, add an explicit local install to its stored `wrappedConfig.setup`; otherwise `npx openclaw` may fail or download an unpinned version.
- Pin the `openclaw` version in production recipes when reproducible setup is required.
- Store wrapper source in the agent workspace or configure `source` if it comes from a repo.
- Put secrets in OrgOps package secrets, not in `wrappedConfig`; setup, sidecars, and runtime receive package secrets as env.
- Use `ORGOPS_WRAPPED_SESSION_ID` to keep OpenClaw state stable per channel or per agent.

From camplight/orgops, Apache-2.0.

More from camplight/orgops