Workflows

Chain tools, models, and approvals into a graph with defined inputs and outputs.

A workflow is a graph of steps with data flowing along the edges. Use one when you already know the procedure — an agent session is for when you do not.

Node types

Type	Does	Key config
`input`	Emits the run's `inputData`	—
`output`	Marks the final result	—
`tool`	Invokes a registered tool	`toolId` or `toolName`
`agent_processor`	Runs an LLM step	`agentId`, prompt in `config`
`transform`	Reshapes fields without a model	`config.mapping`
`condition`	Routes on an expression	`config.expression`
`loop`	Iterates	`config.iterations` or `config.itemsPath`
`workflow`	Invokes another workflow	`workflowId`
`human_approval`	Pauses for a person	Approval prompt in `config`

A condition node emits { result: boolean }; edges leaving it use sourceHandle: 'true' or 'false'.

Build one

const { data: workflow } = await commons.workflows.create({
  name: 'Summarise a page',
  description: 'Fetch a URL, summarise it, and return the summary',
  definition: {
    nodes: [
      { id: 'in',      type: 'input' },
      { id: 'fetch',   type: 'tool', toolName: 'webSearch' },
      { id: 'check',   type: 'condition', config: { expression: 'results.length > 0' } },
      { id: 'summary', type: 'agent_processor', agentId },
      { id: 'out',     type: 'output' },
    ],
    edges: [
      { id: 'e1', source: 'in',    target: 'fetch' },
      { id: 'e2', source: 'fetch', target: 'check' },
      { id: 'e3', source: 'check', target: 'summary', sourceHandle: 'true' },
      { id: 'e4', source: 'check', target: 'out',     sourceHandle: 'false' },
      { id: 'e5', source: 'summary', target: 'out' },
    ],
    outputMapping: { summary: 'summary.output' },
  },
});

Or in the browser: Studio → Workflows → Create opens a canvas where you drag nodes, connect handles, and run from the editor with results streaming onto the graph.

Run one

const execution = await commons.workflows.execute(workflow.workflowId, {
  inputData: { url: 'https://example.com' },
  agentId,
});
 
for await (const event of commons.workflows.stream(workflow.workflowId, execution.executionId)) {
  console.log(event.type, event.stage, event.status);
}

Human approval

A human_approval node pauses the execution and waits. The run resumes when someone approves or rejects it:

agc workflow approve <workflowId> <executionId> <token>
agc workflow reject  <workflowId> <executionId> <token> --reason "Wrong source"

await commons.workflows.approveExecution(workflowId, executionId, {
  approvalToken: token,
  approvalData: { reviewedBy: userId },
});

The token comes from the paused execution. Approvals are recorded in provenance: who approved, what they were shown, and what they chose.

Webhooks

Trigger a workflow from anything that can make an HTTP request — no bearer token needed, the token in the path is the credential.

agc workflow get <workflowId>              # shows the webhook, if one exists

const hook = await commons.workflows.rotateWebhookToken(workflowId);
// POST to hook.webhookUrl to trigger a run
await commons.workflows.disableWebhook(workflowId);

Rotate the token if it leaks; disable the webhook when the integration retires.

Templates

agc workflow templates list
agc workflow templates create <templateName> --agent <agentId> --run

Templates create the workflow and register the API tools it needs, so a template run works out of the box. --prefix keeps generated names stable across repeated runs; --reviewer-agent supplies the second agent for multi-agent templates.

import { listWorkflowTemplates, buildWorkflowTemplate } from '@agent-commons/sdk';

await commons.workflows.update(workflowId, { isPublic: true });
const { data: publicOnes } = await commons.workflows.discoverPublic();
const mine = await commons.workflows.fork(someonesWorkflowId, {
  newOwnerId: userId,
  newOwnerType: 'user',
});

A fork is a copy you own — edit it freely without affecting the original.

Running a workflow from an agent

Give the agent the runWorkflow tool and it can call a workflow as one step of a larger job:

await commons.agents.update(agentId, {
  commonTools: ['runWorkflow', 'processWithinWorkflow'],
});

Debugging

agc workflow executions <workflowId> --limit 5

Stream an execution and watch stage and status per node — a workflow that "does nothing" is usually a condition routing down the branch you did not expect, or an edge whose sourceHandle was never set.

POST /v1/workflows/:id/executions/:executionId/cancel stops a run that is looping or stuck.

On this page