# Author with an agent

Source: https://openflow.run/en/docs/guides/agent-authoring/
Language: en
Product version: 0.1.0-beta.77

Use the CLI or MCP to discover, inspect, and edit workflows through the same deployment service as the Workbench.

Connect your agent to the deployment you intend to use. The Workbench, CLI, and MCP operate on that deployment’s Flows; changing clients does not create a separate workspace or execution service.

The quickstart explains [agent environment configuration](https://openflow.run/en/quickstart/). The commands below use the `oo flow` command group. MCP exposes the corresponding `flow_read`, `flow_schema`, `flow_edit`, `flow_check`, and Run tools.

## Discover before editing

```bash
oo flow schema code --json
oo flow read FLOW_ID --json
```

Read the relevant node details and long code or prompt fields before changing them. Node schemas describe supported configuration, input sources, defaults, and examples. Discover Actions and Trigger keys from the deployment’s catalog rather than inventing their identifiers.

## Submit a revision-aware edit

An edit request contains the observed `baseRevision`, a stable `requestId`, and ordered operations. This example creates a Start node, a Code node, an execution edge, and a data binding:

```json
{
  "baseRevision": "OBSERVED_REVISION",
  "requestId": "UNIQUE_REQUEST_ID",
  "edits": [
    {
      "op": "node.add", "as": "start", "type": "start", "name": "Start",
      "config": { "inputDefs": { "name": { "schema": { "type": "string" }, "nullable": false } } }
    },
    {
      "op": "node.add", "as": "greet", "type": "code", "name": "Compose greeting",
      "code": "export default ({name}) => ({message: `Hello, ${name}!`});",
      "config": { "outputs": { "message": { "schema": { "type": "string" }, "nullable": false } } },
      "inputs": { "name": { "kind": "output", "node": "$start", "port": "name" } }
    },
    { "op": "edge.connect", "source": "$start", "target": "$greet" }
  ]
}
```

```bash
oo flow edit FLOW_ID --file edits.json --json
oo flow check FLOW_ID --json
```

`as` declares an alias without `$`. Later operations in that batch use `$alias`; subsequent requests use node references returned by the service. The batch commits atomically. A saved Draft may still have validation diagnostics.

## Preserve unrelated configuration

Updates recursively merge objects, including schemas. Arrays replace whole arrays. Omitted fields remain unchanged; an empty object does not clear existing configuration.

```json
{
  "op": "node.update",
  "node": "NODE_REFERENCE",
  "clear": [["retry"]]
}
```

Explicit `clear`, JSON `null`, unset input, and inherited default have different meanings. Read before updating and use the current schema for supported sources.

## Handle conflicts and uncertain responses

For an uncertain submission, retry the identical request with the same request identity. Do not invent a new identity until you know whether the original edit succeeded. A revision conflict requires reading the new Draft and deciding how to apply the change; it does not authorize silently overwriting another edit.

Validation does not execute a workflow or prove external account readiness. Test the relevant entry and inspect its Run before publishing. See [test and publish](https://openflow.run/en/docs/guides/test-and-publish/index.md).

## Sources

*   [docs/authoring/node-authoring.md](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/docs/authoring/node-authoring.md)
*   [docs/control/contracts/control-api.md](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/docs/control/contracts/control-api.md#node-authoring)
*   [docs/distribution/command.md](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/docs/distribution/command.md)