Build a workflow with natural language through the API

Send data sources, processing requirements, and output destinations to the workflow assistant. Review its candidate, accept it, then deploy and run it. Generation, acceptance, deployment, and execution are separate steps.

Prepare the environment and workflow assistant

Prepare a personal access token with access to the target workspace and permission to create workflows, and the workspace ID. Examples use $AI_STUDIO_API_KEY and $WORKSPACE_ID.

  1. Query the agent list and find an active system workflow assistant. Do not restrict discovery to a display scene intended only for ordinary chat.

  2. Save id and workspace_id from the same item as $AGENT_ID and $AGENT_WORKSPACE_ID. The agent may belong to a different workspace from the task.

  3. Get the Agent Card using the target workspace and agent ID in the path and the agent’s owning workspace in the query. Check text input and A2A capabilities.

  4. List available models and use a returned model as $MODEL. Workflow generation requires params.model. This generation model is separate from models selected for AI nodes at runtime. The saved model configuration list is not the available model list; an empty configuration list does not establish that no models are available.

The workspace-scoped paths below use the task’s $WORKSPACE_ID, matching the request header. $AGENT_WORKSPACE_ID in the query identifies the agent’s owning workspace. For a system assistant, use system in the query and the actual target workspace in the path.

If the Card’s url contains an internal deployment address, use the public workspace-scoped path below and do not send credentials to the internal address. Generic /v5/agents/card and /v5/agents/a2a are separate endpoints; their errors do not replace diagnosis through the workspace-scoped endpoints.

Submit natural-language requirements

Send an A2A message/send request. Generate a unique $MESSAGE_ID; conversation_purpose marks the conversation for workflow generation. An existing conversation is not required for the first message. For revisions in the same conversation, set params.message.contextId to the previous task’s result.contextId, generate a new messageId, and supply params.model again.

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/a2a?agent_workspace_id=$AGENT_WORKSPACE_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "generate-workflow-1",
    "method": "message/send",
    "params": {
      "model": "'"$MODEL"'",
      "metadata": {
        "conversation_purpose": "workflow"
      },
      "message": {
        "kind": "message",
        "role": "user",
        "messageId": "'"$MESSAGE_ID"'",
        "parts": [
          {
            "kind": "text",
            "text": "Create a manually triggered text-cleaning workflow with a required string input text. Use a registered text-cleaning operator and enable HTML tag removal by default. Submit a deployable candidate and runtime form; do not deploy or run it."
          }
        ]
      }
    }
  }'

Replace the example text with your requirements, including input types, all processing steps, output format, target resources, and failure handling. This text-cleaning example needs no external business data or storage destination. Add a save step and target resource if you need a file artifact. Configure credentials through supported platform mechanisms, not in the prompt.

Track generation and inspect the candidate

When the response contains an A2A task, save result.id as $TASK_ID. Query it using the same agent selectors:

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/a2a?agent_workspace_id=$AGENT_WORKSPACE_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "get-workflow-candidate-1",
    "method": "tasks/get",
    "params": {
      "id": "'"$TASK_ID"'"
    }
  }'

submitted and working are not terminal. For input-required or auth-required, provide the requested information or authorization. Stop deployment for failed, canceled, or rejected. See Call an agent from another agent for details.

After completed, check result.artifacts for a deployable workflow.candidate. Its metadata.matrixflow_type identifies the artifact type; a kind=data part in parts carries the candidate in data. Save that artifact’s artifactId as $ARTIFACT_ID. Do not substitute a conversation, message, or JSON-RPC request ID.

Inspect ok, workflow, runtime_fields, runtime_layout, and diagnostics:

  • Nodes and input bindings cover all requirements, and referenced operators, models, and resources are available.

  • Required form fields, types, and output destinations are correct.

  • The candidate is valid and has no deployment-blocking diagnostics.

Text explanations, tool logs, and completed tasks without a valid candidate cannot be deployed. Request revisions in natural language, then accept the new candidate reference. Do not edit candidate content and reuse its original reference.

Accept and deploy the candidate

  1. Accept the workflow candidate using $TASK_ID and $ARTIFACT_ID. Acceptance saves a confirmation record and does not start the workflow.

  2. Prepare default_values from runtime_fields.fields, providing actual values for every required field. Create the workflow with source_type=nl2dsl, the accepted candidate_ref, execution_mode=one_shot, and these defaults. Missing required values prevent deployment. Do not submit dsl_yaml, runtime_fields, runtime_layout, or design_graph; the server obtains the definition and form from the accepted candidate.

  3. Save data.workflow.id and the deployment version. Read workflow details to verify the saved definition.

Run and verify results

Start a workflow job using the workflow ID, actual form-compatible values, and trigger_now=true when immediate execution is needed. Do not send run_once; the deployed execution_mode=one_shot already determines single-run behavior.

Save data.workflow_run.execution_id, then read job details and job results to verify the terminal state and artifacts. Deployment success or a queued job is not processing success. For file outputs, also verify that the file was saved and can be downloaded.

Troubleshooting

  • workflow agent model is required: provide params.model from the available model list, not a model configuration ID.

  • A completed task has no workflow.candidate: save the task and tool results, then ask the assistant to continue or revise in the same conversation. Do not deploy based only on completed.

  • HTTP 500 with generic ErrServer: save the request time, request/trace IDs, and JSON-RPC ID. Check the workspace-scoped endpoint described in Call an agent from another agent; do not infer a model, permission, or missing-agent problem from a generic error.

  • A request ends without a definitive response: list runtime tasks and match agent, context, and input summary, or query sessions to recover the active task. Query the actual task ID before resubmitting. A JSON-RPC, message, or conversation ID is not a task ID.

Last updated on