Build a workflow around the job
A workflow is a published, repeatable graph of typed steps. Use it for explicit sequences, event-driven jobs, branching, API integrations and auditable actions. An agent handles conversation and judgment; a routine schedules an agent; a workflow coordinates explicit steps. A workflow can call an agent for one decision. Avoid creating all three when one solves the request.
Discover, build, verify
- Read
list_workflow_definitionsbefore making another automation. Inspect a match withget_workflow_definitionand preserve its graph and revision. - Use
list_workflow_nodes, thenget_workflow_nodefor the steps needed. Inspect exact config/input schemas, port IDs, versions and resource references. Never invent a step, property, binding path, account, table or model ID. - Establish the event, input, actions and expected answer. Explain external effects plainly. Put operational records in a Virtual Table; retrieve prose from a knowledge base instead. Load virtual-tables when available.
- Create a private draft. Build nodes with unique UUIDs, edges naming actual
output/input ports and bindings naming the data passed between steps. Start
with the smallest complete path. Save against
expected_revision. - Test with agreed sample data. Test mode calls real APIs and can send messages
or write records. Read the returned run with
get_workflow_execution, thenget_workflow_execution_steps. Queued does not mean succeeded. Check returned values, errors and the intended effects before declaring the automation ready. - Present the trigger and effects before publication. Publication freezes a version and activates its unattended triggers. A key cannot supply a retained human principal: if refused, direct the person to Publish in the console.
- To make it an agent's tool, bind the AgenticOS platform MCP server
(
account: platform) and allow the workflow discovery,run_workflowand execution-reading tools it needs. Read its declared input first. MCP writes retain approval and run as the requesting member. Existingworkflowscapability bindings remain compatible with their resource grants; do not silently replace one with broader MCP access. A workflow's agent step must use aworkflow.runnode to call another workflow instead of starting a root.
A service missing from the MCP gallery
A missing gallery entry does not mean the service is unavailable. First look for
an existing connected server. A custom MCP URL can be connected in the console.
For a documented HTTP API, a workflow with http.request can implement the action
and return a small typed result through core.output; an agent can then call that
workflow. Read the API's official documentation to verify the URL, method, request,
authentication, pagination and response shape. Use the deployment's existing vault
picker for credentials; never request or embed a raw token in chat, instructions,
a graph, a URL, a table, logs or a skill. Preserve the HTTP step's authorization,
egress and approval controls. A missing permission or connection is a concrete
setup step for the person, not a reason to invent a working integration.
Reliability
Choose stable external IDs and idempotency keys for writes. Do not retry an action whose effects may already have occurred without an idempotency contract. Bound loops and API pages, handle expected failures explicitly, and choose budgets. Keep resource access within the caller's organization. Read and reconcile revision conflicts. Do not use another tool to bypass a refusal. Publish only after actual verification, and name any verification the deployment could not perform.
A graph may have independent trigger roots. Keep existing starts when adding another; each run follows one reachable branch. Use one of each unattended kind. Shared steps must not read a different start's unavailable output. Test each entry using its entry_node_id, and explain that publication activates all configured unattended entries.
Prepare once, verify the right thing
For new workflows prefer prepare_workflow_draft: the reviewed graph and optional private table commit together after one approval. Use a local UUID as table_placeholder_id in node config.table or TableIORef sources; leave column IDs unset and address record values by label. Nothing executes or publishes. Use check_workflow_draft for structural validation without side effects; its integration_verified=false is deliberate. A skeleton containing only a trigger and output needs no live test. For action steps, obtain test approval and verify the actual effect. Schedule tests accept ordinary sample input: the server adds fired_at and configured defaults. Link missing providers with /mcp-servers?connect=<catalog key> using a discovered catalog key.
