Set Workflow State

State File Protocol

CRITICAL: You must maintain the workflow state file throughout your work using the sgai_update_workflow_state tool.

State Schema

{
  "status": "working" | "agent-done" | "complete",
  "message": "Status message describing current state",
  "task": "Current task description or null",
  "progress": ["note1", "note2", "note3"]
}

Field Meanings

status - Overall workflow status

• •"working" - Actively working, may need another iteration
• •"agent-done" - Agent finished its work and the sgai should move to the next agent.
• •"complete" - Work is done successfully

message - Status message

• •Brief description of current state
• •When complete, provide a summary of what was accomplished
• •Be clear and specific

task - Current task being worked on (required)

• •Set to describe your current task: "Writing tests for login endpoint"
• •Set to empty string ("") when no specific task or when complete
• •Helps human understand your progress in real-time

progress - Progress log (array of strings)

• •Append entries as you work - this is your audit trail
• •Document major steps completed
• •Note decisions made and why
• •Track issues encountered and how you resolved them
• •This helps humans understand your thought process

How to Update State File

IMPORTANT: Use the sgai_update_workflow_state tool to update the state file. Do NOT use bash/jq commands directly.

Tool: sgai_update_workflow_state

Available parameters:

• •status (required): "working" | "agent-done" | "complete"
• •task (required): Current task being worked on. Use empty string to clear.
• •addProgress (required): Add a progress note (appended to progress array). Document your steps frequently.

Examples:

Update task and add progress note:
Tool: sgai_update_workflow_state
Parameters: {
  "task": "Writing tests for authentication endpoints",
  "addProgress": "Created User model with bcrypt password hashing"
}

Mark as complete:
Tool: sgai_update_workflow_state
Parameters: {
  "status": "complete",
  "task": "",
  "addProgress": "All 15 tests passing, feature verified working"
}

Signal work is done for this agent:
Tool: sgai_update_workflow_state
Parameters: {
  "status": "agent-done",
  "task": "",
  "addProgress": "Review complete, ready for next step"
}

Update frequency:

• •After completing each major step
• •When changing tasks
• •Before requesting another iteration
• •Before marking complete
• •At least every few turns of work

Human Communication

Use ask_user_question to present structured multi-choice questions to the human partner. This is the sole channel for human communication.

Message-Driven Navigation

In flow mode, navigation between agents is driven by inter-agent messages using sgai_send_message() and sgai_check_inbox().

How Navigation Works

1. •

   Send a message to route work: Use sgai_send_message({toAgent: "agent-name", body: "..."}) to send work to another agent.

2. •

   Message-based routing: When you set status: "agent-done", the system checks for pending messages and routes to the agent with the oldest unread message.

3. •

   Default to coordinator: When no messages are pending, control returns to the coordinator.

4. •

   Terminal Nodes: If your agent has no successors (terminal node), control returns to the coordinator.

Key Points

• •Messages drive the workflow - send a message to an agent to have work routed to them
• •Only coordinator can set status: "complete" to end the entire workflow
• •The DAG (flow definition) represents intention and provides predecessor/successor information for context
• •Any agent can message any other agent