Create & Test

Protocol for creating approved flows in Noukai via MCP and verifying them with test cases.

Entry condition: Only proceed here after the user has approved the migration plan from Audit & Design. You should have a list of approved flows with their block trees, prompts, and schemas.

Pre-Flight

Before creating any flows:

Confirm the user has a project_id. If not, they need to create an org and project first — see Quickstart.
Call hydrate_project(project_id) to see what already exists.
Do NOT delete or modify any existing flows. Only create new ones.

Creation Protocol

Create each approved flow one at a time. Follow this sequence per flow:

Create the Flow

create_flow(
  project_id = "{project_id}",
  name       = "{flow name from design}",
  slug       = "{slug from design}",
  description = "{description from design}"
)
→ flow_id

If the slug is taken, append a suffix (e.g. -v2) and inform the user. Do not overwrite existing flows.

Add Blocks

Add blocks following the designed tree topology. Use the MCP tool sequences from Common Workflows.

Sequential blocks — add each after the previous one:

add_block(flow_id, name="Block 1", processor_type="llm", prompt="...")
→ step_1_id

add_block(flow_id, name="Block 2", processor_type="llm",
  target_id=step_1_id, direction="right", prompt="...")
→ step_2_id

Parallel blocks — add sequentially first, then wrap in a container:

add_block(flow_id, name="Branch A", processor_type="llm", prompt="...")
→ branch_a_id

add_block(flow_id, name="Branch B", processor_type="llm",
  target_id=branch_a_id, direction="right", prompt="...")
→ branch_b_id

wrap_in_container(flow_id, node_ids=[branch_a_id, branch_b_id], container_type="v")
→ container_id

Loop blocks — add the inner block, then wrap in a loop:

add_block(flow_id, name="Process Item", processor_type="llm", prompt="...")
→ item_block_id

wrap_in_loop(flow_id, node_ids=[item_block_id], array_field="items")
→ loop_id

Configure Each Block

For every block, set the full configuration:

update_block_draft(flow_id, step_id, content="{full prompt text}")

update_block_config(flow_id, step_id,
  model = "{model from design, e.g. anthropic/claude-sonnet-4-6}",
  config = { "maxTokens": 1024, "temperature": 0.7 }
)

If the design specifies output schemas:

update_block_output_schema(flow_id, step_id, content={
  "type": "object",
  "properties": { ... },
  "required": [ ... ]
})

If the flow has a global input schema:

update_flow_global_input(flow_id, content={
  "type": "object",
  "properties": { ... },
  "required": [ ... ]
})

Create Test Cases

Create test cases to verify the flow works correctly. Derive test inputs from the user's existing codebase:

Check for existing tests — search for test files that exercise the original chain. Extract their input data.
Check for examples — look for example inputs in docstrings, comments, or README files.
Check for hardcoded data — look for test/demo data in the codebase.
If nothing found — generate representative inputs based on the flow's input schema.

Create at minimum two test cases per flow:

create_test_case(
  project_id = "{project_id}",
  flow_id    = "{flow_id}",
  scope      = "flow",
  name       = "Happy path — {description}",
  input_data = { "message": "{realistic input}", "parameters": {} }
)

create_test_case(
  project_id = "{project_id}",
  flow_id    = "{flow_id}",
  scope      = "flow",
  name       = "Edge case — minimal input",
  input_data = { "message": "", "parameters": {} }
)

Publish and Set Live

publish_version(flow_id, note="Migration v1 — initial creation from {original chain name}")
→ version_id

set_production_version(flow_id, version_id)

Present Test Interface

Provide the user with everything they need to test:

1. The API URL:

POST https://api.noukai.xyz/api/v1/seq/{org_slug}/{project_slug}/{flow_slug}/execute

2. A ready-to-run curl command using one of the test case inputs:

curl -X POST https://api.noukai.xyz/api/v1/seq/{org}/{project}/{slug}/execute \
  -H "Authorization: Bearer $NOUKAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "{test input}", "parameters": {}}'

3. The web UI link:

https://app.noukai.xyz → Project → {flow name} → Test tab

4. Ask the user to verify:

"I've created the following flows and published them:

Flow Slug Blocks Test Cases
{name} {slug} {count} {count}

You can test them using the curl commands above or in the web UI at app.noukai.xyz. When you're satisfied and ready to integrate into your code, say continue or implement."

Flow	Slug	Blocks	Test Cases
{name}	{slug}	{count}	{count}

Do not proceed to the Integration phase until the user signals readiness.

If Something Goes Wrong

Slug conflict: Append -migrated or -v2 to the slug. Inform the user of the name change.
Block creation fails: Check the flow structure with get_flow_structure(flow_id) and retry with corrected parameters.
Prompt too long: Split into multiple blocks. Update the design document if the user saved one.
User wants changes: Use update_block_draft, update_block_config, or structural tools (move_block, remove_block) to adjust. Do not delete the flow — modify in place.

After any changes, republish:

publish_version(flow_id, note="Migration v1.1 — {what changed}")
set_production_version(flow_id, new_version_id)

On this page