SowonFlow

https://sowonai.github.io/sowonflow-docs/
Admin
SowonFlow is an AI-powered workflow automation platform that uses YAML-based definitions to enable...
Tokens:23,141
Snippets:116
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Complete Document Setup for Sowonflow Workflow

Source: https://sowonai.github.io/sowonflow-docs/documentation

Provides a comprehensive example of setting up various document types for a Sowonflow Workflow. It includes simple text, structured markdown, and a lazy-loaded document using file system access. The example also shows how to initialize the Workflow and query it.

```typescript
import { Workflow } from '@sowonai/sowonflow';
import fs from 'fs/promises';

const documents = {
  // Simple text document
  'welcome_message': 'Welcome to our AI assistant!',

  // Structured Markdown document
  'company_handbook': {
    type: 'markdown',
    content: `
# Company Handbook
## Code of Conduct
Treat each other with respect and professionalism.
## Policies
### Work-from-home Policy
...
    `
  },

  // Lazy-loaded document
  'product_specs': async () => {
    const content = await fs.readFile('./docs/specs.md', 'utf-8');
    return {
      type: 'markdown',
      content
    };
  }
};

const workflow = new Workflow({
  mainWorkflow: yamlContent,
  documents,
  interceptor: myInterceptor
});

const response = await workflow.ask('What is our work-from-home policy?');
```

--------------------------------

### Tools with Caching: Search Tool Example (JavaScript)

Source: https://sowonai.github.io/sowonflow-docs/tools

Illustrates how to implement caching within a tool to improve performance for frequently accessed data. This example creates a search tool that caches results based on the query and a specified duration.

```javascript
const cachedSearchTool = new DynamicStructuredTool({
  name: "cached_search",
  description: "A search tool with caching applied.",
  schema: z.object({
    query: z.string().describe("Search query"),
    cache_duration: z.number().default(300).describe("Cache retention time (seconds)")
  }),
  func: async ({ query, cache_duration }) => {
    const cacheKey = `search:${query}`;
      
    // Check cache
    const cached = await cache.get(cacheKey);
    if (cached) {
      return `[Cached] ${cached}`;
    }
      
    // Perform actual search
    const result = await searchEngine.search(query);
      
    // Cache result
    await cache.set(cacheKey, result, cache_duration);
      
    return result;
  }
});
```

--------------------------------

### Chaining Tools: Data Processing Example (JavaScript)

Source: https://sowonai.github.io/sowonflow-docs/tools

Demonstrates creating a tool that processes and analyzes data by chaining multiple internal steps like data collection, cleaning, and analysis. It utilizes a schema for input validation and returns structured results.

```javascript
const dataProcessingTool = new DynamicStructuredTool({
  name: "process_and_analyze",
  description: "Processes and analyzes data.",
  schema: z.object({
    data_source: z.string().describe("Data source"),
    analysis_type: z.enum(["statistical", "trend", "correlation"])
  }),
  func: async ({ data_source, analysis_type }) => {
    // Step 1: Data collection
    const rawData = await dataCollector.fetch(data_source);
      
    // Step 2: Data cleaning
    const cleanData = await dataProcessor.clean(rawData);
      
    // Step 3: Perform analysis
    const analysis = await analyzer.analyze(cleanData, analysis_type);
      
    return {
      data_points: cleanData.length,
      analysis_result: analysis,
      recommendations: analysis.recommendations
    };
  }
});
```

--------------------------------

### Integrated Example: Multi-Tool Workflow (YAML)

Source: https://sowonai.github.io/sowonflow-docs/tools

A comprehensive workflow specification in YAML for a 'Comprehensive Business Assistant'. It defines multiple agents (coordinator, data specialist, business specialist), their roles, tools, and a state machine to route tasks based on user input.

```yaml
version: "agentflow/v1"
kind: "WorkflowSpec"
metadata:
  name: "Comprehensive Business Assistant"
  description: "A multi-agent system utilizing various tools"
  
state:
  variables:
    - name: "task_type"
      initial_value: null
    - name: "results"
      initial_value: {}
  
agents:
  - id: "coordinator"
    inline:
      type: "agent"
      model: "openai/gpt-4.1-mini"
      system_prompt: "You are a coordinator who analyzes tasks and assigns them to the appropriate expert."
        
  - id: "data_specialist"
    inline:
      type: "agent"
      model: "openai/gpt-4.1-mini"
      system_prompt: "You are an expert responsible for data retrieval and analysis."
      tools: ["search_database", "process_document", "cached_search"]
        
  - id: "business_specialist"
    inline:
      type: "agent"
      model: "openai/gpt-4.1-mini"
      system_prompt: "You are an expert responsible for business processes and policies."
      tools: ["search_calendar", "search_hr_policies", "update_employee_info"]
  
nodes:
  start:
    type: "agent_task"
    agent: "coordinator"
    input:
      template: "Determine the task type: {{user_query}}"
    output:
      to_state: "task_type"
    next: "route_task"
      
  route_task:
    type: "branch"
    method: "condition"
    condition: "task_type"
    branches:
      "DATA": "data_processing"
      "BUSINESS": "business_processing"
      "MIXED": "parallel_processing"
    default: "general_response"
      
  parallel_processing:
    type: "parallel"
    branches: ["data_processing", "business_processing"]
      
  data_processing:
    type: "agent_task"
    agent: "data_specialist"
    input:
      template: "Perform data-related tasks: {{user_query}}"
    next: "join_results"
      
  business_processing:
    type: "agent_task"
    agent: "business_specialist"
    input:
      template: "Perform business-related tasks: {{user_query}}"
    next: "join_results"
      
  join_results:
    type: "join"
    next: "final_summary"
      
  final_summary:
    type: "agent_task"
    agent: "coordinator"
    input:
      template: "Consolidate all results and provide a final answer."
    next: "end"
      
  general_response:
    type: "agent_task"
    agent: "coordinator"
    next: "end"
      
  end:
    type: "end"

```

--------------------------------

### Define a Workflow Spec for Tool Usage

Source: https://sowonai.github.io/sowonflow-docs/tools

This YAML defines a SowonFlow workflow named 'Tool Usage Example'. It configures a 'research_agent' to use specific tools ('search_database', 'analyze_data') and outlines the agent's task to research a user-provided topic.

```yaml
version: "agentflow/v1"
kind: "WorkflowSpec"
metadata:
  name: "Tool Usage Example"

agents:
  - id: "research_agent"
    inline:
      type: "agent"
      model: "openai/gpt-4.1-mini"
      system_prompt: "You are a research expert. Use tools to search and analyze information."
      tools: ["search_database", "analyze_data"]

nodes:
  start:
    type: "agent_task"
    agent: "research_agent"
    input:
      template: "Please research the following topic: {{user_query}}"
    next: "end"
  end:
    type: "end"

```

--------------------------------

### Tool Design: Clear Schema Definition

Source: https://sowonai.github.io/sowonflow-docs/tools

Illustrates the importance of clear and specific descriptions within a schema definition for tool parameters. A good example provides context for each field, aiding user understanding and preventing ambiguity.

```javascript
// Good example: Clear and specific description
schema: z.object({
  user_id: z.string().describe("Unique identifier for the user (e.g., emp_12345)"),
  start_date: z.string().describe("Start date (YYYY-MM-DD format)"),
  end_date: z.string().describe("End date (YYYY-MM-DD format)"),
  include_weekends: z.boolean().default(false).describe("Whether to include weekends")
})

// Bad example: Ambiguous description
schema: z.object({
  id: z.string().describe("ID"),
  date: z.string().describe("Date"),
  flag: z.boolean().describe("Flag")
})
```

--------------------------------

### Tool Design: Appropriate Response Format

Source: https://sowonai.github.io/sowonflow-docs/tools

Provides examples of formatting tool responses based on whether JSON or plain text is more appropriate. This ensures data is returned in a usable and understandable format for the calling application or user.

```javascript
// If JSON response is needed
func: async (params) => {
  const result = await processData(params);
  return JSON.stringify({
    status: "success",
    data: result,
    timestamp: new Date().toISOString()
  });
}

// If text response is appropriate
func: async (params) => {
  const count = await database.count(params.query);
  return `Search results: Found ${count} items.`;
}
```

--------------------------------

### Gmail Credentials Installation Command

Source: https://sowonai.github.io/sowonflow-docs/examples/1

Provides the command-line instruction to install and set up Gmail credentials using the '@sowonai/mcp-gmail' package. This command facilitates the OAuth flow and generates a credentials file.

```bash
npx @sowonai/mcp-gmail --install --credentials ./credentials.json
```

--------------------------------

### State Management Example

Source: https://sowonai.github.io/sowonflow-docs/multi-agent-workflows

Demonstrates effective state management in Sowonflow by using descriptive variable names and initializing them appropriately.

```yaml
state:
  variables:
    - name: "analysis_result" 
      initial_value: null 
    - name: "report_status" 
      initial_value: "pending"

```

--------------------------------

### Example Well-Structured System Prompt

Source: https://sowonai.github.io/sowonflow-docs/agent

Demonstrates a detailed system prompt for a customer service agent, outlining expertise, guidelines, and response formatting for a SaaS company.

```yaml
system_prompt: |
  You are a customer service agent for a SaaS company.

  Areas of Expertise:
  - Product features and limitations
  - Billing and subscription management
  - Basic technical troubleshooting
  - Account management procedures

  Guidelines:
  - Always be helpful, professional, and empathetic in your responses.
  - Provide step-by-step instructions when necessary.
  - Escalate appropriately if you cannot resolve an issue.
  - Ask clarifying questions to better understand the issue.

  Response Format:
  - Use clear and concise language.
  - Structure responses with headers and bullet points.
  - Include relevant links or references when helpful.

```

--------------------------------

### Install SowonFlow Package (npm)

Source: https://sowonai.github.io/sowonflow-docs/intro

Installs the core SowonFlow runtime library using npm, which is necessary for creating and executing AI workflows.

```bash
npm install @sowonai/sowonflow  

```

--------------------------------

### Example Query: Find and Summarize Work Emails

Source: https://sowonai.github.io/sowonflow-docs/examples/1

An example natural language query to instruct the AI agent to find and summarize work-related emails from the user's inbox. This demonstrates a typical input for the email management workflow.

```text
Find and summarize any work-related emails from my recent mail.
```

--------------------------------

### Instantiate Workflow with Tools

Source: https://sowonai.github.io/sowonflow-docs/tools

Shows how to instantiate a SowonFlow Workflow object. It takes the workflow's YAML content, configuration, and an array of tool instances (like 'searchTool' and 'analysisTool') as arguments.

```typescript
const workflow = new Workflow({
  mainWorkflow: yamlContent,
  config: config,
  tools: [searchTool, analysisTool] // Pass array of tools
});

```

--------------------------------

### Sowonflow System Prompt: Supervisor Best Practices

Source: https://sowonai.github.io/sowonflow-docs/supervisor

An example system prompt for a Sowonflow supervisor, detailing its role, supervisor modes (sequential, parallel, branch, auto), and available expert agents with their specializations.

```yaml
system_prompt: |
  You are a project supervisor managing a team of expert consultants.
  Determine the workflow pattern based on supervisor_mode.

  supervisor_mode:
    - sequential: When tasks need to be performed in a specific order.
    - parallel: When diverse perspectives are needed.
    - branch: When only one expert needs to be selected based on conditions.
    - auto: AI determines and selects the optimal pattern.

  Available experts:
    - legal_expert: Contract analysis, compliance, legal risks
    - tech_expert: Technical feasibility, architecture, implementation
    - business_analyst: Strategy, market analysis, business impact

  Always explain the supervisor_mode and workflow selection, and provide comprehensive results.

```

--------------------------------

### Start Node Configuration

Source: https://sowonai.github.io/sowonflow-docs/examples/multi-agent-business

Defines the 'start' node of a workflow. It's an agent task that analyzes user queries to determine information needs (scheduling, HR, both, or none) and routes the decision.

```yaml
nodes:
  start:
    type: "agent_task"
    agent: "master_agent"
    input:
      template: |
        Analyze this user query and determine the type of information needed.
          
        User query: {{user_query}}
          
        Respond with exactly one of the following values:
        - scheduling: If scheduling/calendar information is needed.
        - HR: If HR policy/benefits information is needed.
        - both: If both scheduling and HR information are needed.
        - none: If you can answer directly without expert help.
    output:
      to_state: "routing_decision"
      format: "enum"
      schema:
        type: string
        enum: [both, scheduling, HR, none]
    next: "route_decision"

```

--------------------------------

### Configure a Simple Agent in SowonFlow

Source: https://sowonai.github.io/sowonflow-docs/agent

Defines a basic agent configuration with an ID, model, and system prompt. This serves as a foundational setup for AI entities within SowonFlow.

```yaml
agents:
  - id: "research_agent"
    inline:
      type: "agent"
      model: "openai/gpt-4.1"
      system_prompt: |
        You are a professional researcher,
        skilled at finding and gathering information from various sources.
        Always provide systematic and fact-based answers.

```

--------------------------------

### Table of Contents (TOC) Output Example

Source: https://sowonai.github.io/sowonflow-docs/documentation

An example illustrating the hierarchical structure of a Table of Contents generated from a Markdown document's headers.

```markdown
# company policy
## HR Policy
## Recruitment Guidelines
## Employee Benefits
### Stock Option
### Retirement Plan

```

--------------------------------

### SowonFlow Workflow Example with a Single Agent

Source: https://sowonai.github.io/sowonflow-docs/agent

Illustrates a complete workflow definition using a single specialized agent for document analysis. It includes workflow metadata, agent configuration, and task node definitions.

```yaml
version: "agentflow/v1"
kind: "WorkflowSpec"
metadata:
  name: "Document Analysis"
  description: "Document analysis with a specialized agent"
  
agents:
  - id: "document_analyst"
    inline:
      type: "agent"
      model: "openai/gpt-4.1"
      system_prompt: |
        You are a document analysis expert. Thoroughly analyze documents and
        provide structured insights including:
        - Key findings and important points
        - Potential issues or concerns
        - Actionable recommendations
        Always clearly structure your responses with headers and bullet points
        for readability.
  
nodes:
  start:
    type: "agent_task"
    agent: "document_analyst"
    next: "end"
    
  end:
    type: "end"

```

--------------------------------

### Example Query: Search Emails by Date Range

Source: https://sowonai.github.io/sowonflow-docs/examples/1

An example query to summarize important emails within a specified date range (yesterday to today). This demonstrates the workflow's ability to process emails based on time.

```text
Summarize important emails from yesterday to today.
```

--------------------------------

### Initialize Workflow with MCP Servers (JavaScript)

Source: https://sowonai.github.io/sowonflow-docs/mcp

Instantiate a `Workflow` object in JavaScript, providing the main workflow definition and configuring MCP servers. This example shows how to set up the 'gmail' MCP server with specific command, arguments, and environment variables.

```javascript
const workflow = new Workflow({
  mainWorkflow: workflowYaml,
  mcpServers: {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@sowonai/mcp-gmail"]
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN_FROM_INSTALL_STEP"
      }
    }
  }
});

```

--------------------------------

### Master-Worker Pattern Example

Source: https://sowonai.github.io/sowonflow-docs/multi-agent-workflows

An example demonstrating the Master-Worker pattern, where a central 'master' agent coordinates tasks assigned to multiple specialized 'worker' agents.

```yaml
agents:
  - id: "master" 
    system_prompt: "You coordinate and delegate tasks to experts." 
  - id: "worker_1" 
    system_prompt: "You handle specific task type A." 
  - id: "worker_2" 
    system_prompt: "You handle specific task type B."

```

--------------------------------

### Agent Specialization Best Practice

Source: https://sowonai.github.io/sowonflow-docs/multi-agent-workflows

Example showcasing the best practice of defining agents with specialized roles, ensuring clear responsibilities for each agent in the workflow.

```yaml
agents:
  - id: "data_analyst" 
    system_prompt: "You analyze data and provide insights." 
  - id: "report_writer" 
    system_prompt: "You write professional reports."

```

--------------------------------

### Example Query: Search Emails with Attachments

Source: https://sowonai.github.io/sowonflow-docs/examples/1

An example query to find emails that contain attachments and retrieve their subjects and senders. This highlights the workflow's capability to identify emails with specific characteristics.

```text
Find emails with attachments and tell me their subjects and senders.
```

--------------------------------

### Parallel Node Example

Source: https://sowonai.github.io/sowonflow-docs/multi-agent-workflows

Demonstrates the structure of a 'parallel' node in Sowonflow, which allows for the concurrent execution of multiple branches or tasks.

```yaml
parallel_node:
  type: "parallel" 
  branches: ["task1", "task2", "task3"]

```

--------------------------------

### HR Policy Search Tool

Source: https://sowonai.github.io/sowonflow-docs/tools

A tool to search for HR policies and regulations based on a topic and an optional department. It integrates with an HR system to retrieve policy details.

```javascript
const hrTool = new DynamicStructuredTool({
  name: "search_hr_policies",
  description: "Searches for HR policies and regulations.",
  schema: z.object({
    topic: z.string().describe("Search topic (e.g., business travel expenses, vacation, welfare)"),
    department: z.string().optional().describe("Department name (optional)")
  }),
  func: async ({ topic, department }) => {
    try {
      // Integrate HR system or document database
      const policies = await hrSystem.searchPolicies(topic, department);

      if (policies.length === 0) {
        return `No HR policies found for "${topic}".`;
      }

      return policies.map(policy => ({
        title: policy.title,
        summary: policy.summary,
        source: policy.document_name,
        last_updated: policy.updated_date
      }));
    } catch (error) {
      return `An error occurred while searching for HR policies: ${error.message}`;
    }
  }
});
```

--------------------------------

### Example Query: Search Emails by Sender

Source: https://sowonai.github.io/sowonflow-docs/examples/1

An example query to find all emails from a specific sender's email address. This showcases the workflow's ability to filter emails based on sender information.

```text
Find all emails from example@company.com.
```

--------------------------------

### Branch Node Example

Source: https://sowonai.github.io/sowonflow-docs/multi-agent-workflows

Shows the configuration of a 'branch' node in Sowonflow, which controls workflow execution by routing based on specified conditions and their corresponding paths.

```yaml
branch_node:
  type: "branch" 
  method: "condition" 
  condition: "state_variable" 
  branches: 
    "value1": "path1" 
    "value2": "path2" 
  default: "default_path"

```

--------------------------------

### Performance Optimization for Searches

Source: https://sowonai.github.io/sowonflow-docs/mcp

Performance guidelines for Sowonflow, including using specific search criteria, batch processing, result caching, and setting reasonable limits. Provides examples of search optimization techniques.

```text
Performance Guidelines:  
  - Use specific search criteria to limit results  
  - Process tasks in batches if possible  
  - Cache results when appropriate  
  - Set reasonable limits (maxResults: 10-50)  
    
  Search Optimization:  
  - Combine criteria: "from:team@company.com after:2024/01/01"  
  - Use date ranges for scope limitation  
  - Filter by category when relevant  
```

--------------------------------

### Configure SowonFlow Access (JavaScript)

Source: https://sowonai.github.io/sowonflow-docs/intro

Creates a configuration object for SowonFlow, requiring an API key and a space ID to access AI models. This setup is a prerequisite for using the workflow execution capabilities.

```javascript
import { Workflow, createConfig } from '@sowonai/sowonflow';  
  
// Create configuration  
const config = createConfig({  
  apiKey: 'your-api-key',  
  spaceId: 'your-space-id'
});  

```

--------------------------------

### Gmail MCP Server Integration (YAML)

Source: https://sowonai.github.io/sowonflow-docs/mcp

Configure an agent to use the 'gmail' MCP server. The `system_prompt` specifies available Gmail MCP tools for searching, retrieving, and sending emails, along with example search syntax.

```yaml
agents:  
  - id: "email_assistant"  
    inline:  
      type: "agent"  
      model: "openai/gpt-4.1"  
      system_prompt: |
        You are an email management assistant.  
          
        Available Gmail MCP tools:  
        - mcp__gmail__search_emails: Search emails using Gmail syntax  
        - mcp__gmail__get_email: Retrieve detailed email content  
        - mcp__gmail__send_email: Send a new email  
          
        Example Gmail search syntax:  
        - from:sender@example.com  
        - subject:meeting  
        - has:attachment  
        - after:2024/01/01  
        - is:unread  
      mcp: ["gmail"]  

```

--------------------------------

### Agent System Prompt with Document Template Binding

Source: https://sowonai.github.io/sowonflow-docs/documentation

An example of how to use Handlebars template syntax within an agent's system prompt to inject document content and Table of Contents (TOC).

```yaml
agents:
  - id: "support_agent"
    inline:
      type: "agent"
      model: "openai/gpt-4.1"
      system_prompt: |
        You are a customer support agent. Use the following documents to help the user:
          
        <document name="user_guide">
          {{{documents.user_guide.content}}}
        </document>
          
        <document name="faq">
          Table of Contents:
          <toc>
          {{{documents.faq.toc}}}
          </toc>
        </document>

```

--------------------------------

### Implement Database Search Tool with DynamicStructuredTool

Source: https://sowonai.github.io/sowonflow-docs/tools

Demonstrates creating a LangChain compatible tool for searching a database. It uses Zod for schema definition, allowing structured input parameters like 'query' and an optional 'category'. The 'func' property contains the asynchronous logic to interact with a database.

```typescript
import { DynamicStructuredTool } from '@langchain/core/tools';
import { z } from 'zod';

const searchTool = new DynamicStructuredTool({
  name: "search_database",
  description: "Searches for information in the database.",
  schema: z.object({
    query: z.string().describe("Search query"),
    category: z.string().optional().describe("Search category (optional)")
  }),
  func: async ({ query, category }) => {
    // Implement actual search logic
    const results = await database.search(query, category);
    return JSON.stringify(results);
  }
});

```

--------------------------------

### Debugging SowonFlow Tool Execution and Workflow Monitoring

Source: https://sowonai.github.io/sowonflow-docs/tools

This snippet demonstrates how to add logging for tool execution within a SowonFlow DynamicStructuredTool. It includes error handling and logging of inputs and results. It also shows how to monitor workflow states and tool execution results.

```javascript
// Tool execution logging  
const debugTool = new DynamicStructuredTool({
  name: "debug_tool",  
  description: "Example tool with debugging.",  
  schema: z.object({
    input: z.string()
  }),  
  func: async ({ input }) => {
    console.log(`[DEBUG] Tool called with input: ${input}`);  
      
    try {
      const result = await processInput(input);
      console.log(`[DEBUG] Tool result: ${JSON.stringify(result)}`);
      return result;
    } catch (error) {
      console.error(`[DEBUG] Tool error: ${error.message}`);
      throw error;
    }
  }
});
  
// Monitor tool usage in workflow  
workflow.addStateListener((state) => {
  console.log("Current state:", state);
  // Check tool execution results  
});


```

--------------------------------

### Error Handling for Lazy-Loaded Documents

Source: https://sowonai.github.io/sowonflow-docs/documentation

Provides an example of robust error handling for asynchronous document loading, including a fallback mechanism if a file cannot be read.

```javascript
documents = {  
  'optional_doc': async () => {  
    try {  
      const content = await fs.readFile('./optional.md', 'utf-8');
      return { type: 'markdown', content };
    } catch (error) {  
      console.warn('cannot found:', error.message);
      return { type: 'text', content: 'not found!' };
    }
  }
}

```

--------------------------------

### Join Node Example

Source: https://sowonai.github.io/sowonflow-docs/multi-agent-workflows

Illustrates the 'join' node type in Sowonflow, used to wait for the completion of all branches initiated by a 'parallel' node before proceeding.

```yaml
join_node:
  type: "join" 
  next: "next_step"

```

--------------------------------

### Multiple MCP Server Configuration (JavaScript)

Source: https://sowonai.github.io/sowonflow-docs/mcp

Shows how to configure multiple MCP servers within the SowonFlow `Workflow` class. This example includes configurations for Gmail, a hypothetical Calendar MCP server, and a File system MCP server, each with their respective commands and arguments.

```javascript
const workflow = new Workflow({
  mainWorkflow: workflowYaml,
  mcpServers: {
    "gmail": {
      "command": "npx",
      "args": ["@gongrzhe/server-gmail-autoauth-mcp"]
    },
    "calendar": {
      "command": "npx",
      "args": ["@example/calendar-mcp-server"]
    },
    "files": {
      "command": "node",
      "args": ["./servers/file-server.js"]
    }
  }
});


```

--------------------------------

### Robust Error Handling for MCP Tools

Source: https://sowonai.github.io/sowonflow-docs/mcp

Guidelines for handling errors when using MCP tools. Emphasizes clear issue explanation, suggesting alternatives, parameter validation, and graceful authentication error management. Includes an example for Gmail search failures.

```text
Error Handling:  
  - If an MCP tool fails, clearly explain the issue  
  - Suggest alternative approaches if possible  
  - Always validate parameters before calling a tool  
  - Handle authentication issues gracefully  
    
  Example:  
  If a Gmail search fails:  
  1. Check if the search syntax is correct  
  2. Try a simplified search criterion  
  3. Inform the user about limitations  
```

--------------------------------

### MCP Server Setup for Gmail

Source: https://sowonai.github.io/sowonflow-docs/examples/1

Configures the MCP server to use the '@sowonai/mcp-gmail' package for Gmail integration. It specifies the command to run the MCP server and the necessary environment variables for Google OAuth authentication. Requires Google API credentials to be set up.

```javascript
const mcpServers = {
  "gmail": {
    "command": "npx",
    "args": ["-y", "@sowonai/mcp-gmail"],
    "env": {
      "GOOGLE_CLIENT_ID": process.env.GOOGLE_CLIENT_ID,
      "GOOGLE_CLIENT_SECRET": process.env.GOOGLE_CLIENT_SECRET,
      "GOOGLE_REFRESH_TOKEN": process.env.GOOGLE_REFRESH_TOKEN
    }
  }
};
```

--------------------------------

### SowonFlow Tool Security: User Permission Management

Source: https://sowonai.github.io/sowonflow-docs/tools

This snippet demonstrates permission management within a SowonFlow tool. It retrieves user permissions and checks if the user has the necessary authorization to perform a requested action before proceeding.

```javascript
func: async ({ user_id, action }) => {
  // Check user permissions  
  const permissions = await getUserPermissions(user_id);
  if (!permissions.includes(action)) {
    return "You do not have permission to perform this action.";
  }
    
  return await performAction(action);
}


```

--------------------------------

### Task Execution Agent Pattern

Source: https://sowonai.github.io/sowonflow-docs/agent

Configures a 'task_agent' for executing tasks, breaking down complex requests, and providing implementation guides, including calculator and current_time tools.

```yaml
agents:
  - id: "task_agent"
    inline:
      type: "agent"
      model: "openai/gpt-4.1"
      system_prompt: |
        You are a task execution expert. Break down complex requests into
        actionable steps and provide detailed implementation guides.
      tools: ["calculator", "current_time"]

```

--------------------------------

### File Processing Tool

Source: https://sowonai.github.io/sowonflow-docs/tools

A tool designed to process document files, allowing for text extraction, summarization, or analysis. It takes a file path and an action as input, with optional parameters for length and language.

```javascript
const fileProcessorTool = new DynamicStructuredTool({
  name: "process_document",
  description: "Processes document files and extracts content.",
  schema: z.object({
    file_path: z.string().describe("Path to the file to process"),
    action: z.enum(["extract_text", "summarize", "analyze"]).describe("Action to perform"),
    options: z.object({
      max_length: z.number().optional().describe("Maximum character limit"),
      language: z.string().optional().describe("Document language")
    }).optional()
  }),
  func: async ({ file_path, action, options = {} }) => {
    try {
      const fileContent = await fileSystem.readFile(file_path);

      switch (action) {
        case "extract_text":
          const text = await documentProcessor.extractText(fileContent);
          return options.max_length ? text.substring(0, options.max_length) : text;

        case "summarize":
          const summary = await documentProcessor.summarize(fileContent, options);
          return summary;

        case "analyze":
          const analysis = await documentProcessor.analyze(fileContent, options);
          return JSON.stringify(analysis);

        default:
          return "Unsupported action.";
      }
    } catch (error) {
      return `An error occurred while processing the file: ${error.message}`;
    }
  }
});
```

--------------------------------

### Tool Design: Safe Error Handling

Source: https://sowonai.github.io/sowonflow-docs/tools

Demonstrates best practices for error handling within a tool's function. This includes input validation, handling potential errors from external API calls, and providing informative error messages to the user.

```javascript
func: async (params) => {
  try {
    // Input validation
    if (!params.required_field) {
      return "Required field is missing.";
    }

    // Execute business logic
    const result = await externalAPI.call(params);

    // Result validation
    if (!result || result.error) {
      return `API call failed: ${result?.error || 'Unknown error'}`;
    }

    return result.data;
  } catch (error) {
    console.error('Tool execution error:', error);
    return `An error occurred during tool execution: ${error.message}`;
  }
}
```

--------------------------------

### Add New Department Agent Configuration

Source: https://sowonai.github.io/sowonflow-docs/examples/multi-agent-business

Demonstrates how to define a new agent for a department, specifying its ID, type, system prompt for guiding its behavior, and the tools it can access. This is a YAML configuration snippet.

```yaml
agents:  
  - id: "finance_agent"  
    inline:  
      type: "agent"  
      system_prompt: "You handle budget and financial queries."  
      tools: ["search_budget"]  


```

--------------------------------

### Gmail Email Analysis Prompt Pattern (System Prompt)

Source: https://sowonai.github.io/sowonflow-docs/mcp

Illustrates a system prompt pattern for email analysis using Gmail MCP tools. It guides the agent through a four-step process: searching, filtering important emails, retrieving detailed content, and analyzing/summarizing the findings.

```text
system_prompt: |
  Follow this pattern for email analysis:  
    
  1. Search: Use mcp__gmail__search_emails with relevant criteria  
  2. Filter: Identify important emails from the search results  
  3. Retrieve: Use mcp__gmail__get_email for detailed content  
  4. Analyze: Categorize and summarize findings  
    
  Workflow example:  
  - Search: Recent unread emails  
  - Filter: Work-related communications  
  - Retrieve: Full content of important emails  
  - Analyze: Provide a structured summary  


```

--------------------------------

### Optimize Workflow with Parallel Processing and Caching (TypeScript)

Source: https://sowonai.github.io/sowonflow-docs/custom-nodes

Demonstrates optimizing workflow handlers by executing multiple asynchronous tasks in parallel using Promise.all and implementing a caching mechanism to reduce redundant data fetching. Suitable for improving response times in I/O-bound operations.

```typescript
const optimizedHandler = async (state: WorkflowState) => {
  const userId = state.variables.userId;
    
  // Execute multiple asynchronous tasks in parallel
  const [userInfo, permissions, settings] = await Promise.all([
    userService.getInfo(userId),
    permissionService.getPermissions(userId),
    settingsService.getUserSettings(userId)
  ]);
    
  // Integrate results
  state.variables.userData = {
    info: userInfo,
    permissions: permissions,
    settings: settings,
    loadedAt: new Date().toISOString()
  };
    
  return { 
    messages: [new SystemMessage('User data loaded')]
  };
};
  
// Performance improvement using caching
const cache = new Map();

const cachedHandler = async (state: WorkflowState) => {
  const cacheKey = `user_${state.variables.userId}`;
    
  // Check cache
  if (cache.has(cacheKey)) {
    console.log('Returning data from cache');
    state.variables.userInfo = cache.get(cacheKey);
    return { messages: [new SystemMessage('Using cached data')] };
  }
    
  // Fetch new data
  const userInfo = await userService.getInfo(state.variables.userId);
    
  // Save to cache (5 min TTL)
  cache.set(cacheKey, userInfo);
  setTimeout(() => cache.delete(cacheKey), 5 * 60 * 1000);
    
  state.variables.userInfo = userInfo;
    
  return { messages: [new SystemMessage('New data fetched')] };
};

```

--------------------------------

### Gmail Search Syntax Documentation (Markdown)

Source: https://sowonai.github.io/sowonflow-docs/mcp

Provides the syntax for searching emails in Gmail, including common operators like 'from', 'to', 'subject', 'has:attachment', date filters, and status filters. Also includes advanced examples combining multiple operators.

```markdown
## Gmail Search Syntax  
  
### Common Operators:  
- from:sender@example.com - Find emails from a specific sender  
- to:recipient@example.com - Find emails sent to a specific recipient  
- subject:keyword - Search in the subject line  
- has:attachment - Emails with attachments  
- after:2024/01/01 - Emails after a specific date  
- before:2024/12/31 - Emails before a specific date  
- is:unread - Unread emails only  
- is:important - Important emails  
- category:primary - Emails in the primary category  
  
### Advanced Examples:  
- from:team@company.com after:2024/01/01 has:attachment  
- subject:(meeting OR call) -category:promotions  
- is:unread from:clients after:2024/01/15  

```

--------------------------------

### Data Pipeline Handlers for Extraction, Transformation, and Loading (TypeScript)

Source: https://sowonai.github.io/sowonflow-docs/custom-nodes

Defines handlers for a data pipeline, encompassing data extraction from various sources, transformation of records, and batch loading into a database. Employs asynchronous loops and array manipulation for data processing.

```typescript
const dataPipelineHandlers = {
  extractData: async (state: WorkflowState) => {
    const sources = state.variables.dataSources;
    const rawData = [];
      
    for (const source of sources) {
      const data = await dataExtractor.extract(source);
      rawData.push(...data);
    }
      
    state.variables.rawData = rawData;
      
    return { messages: [new SystemMessage(`${rawData.length} records extracted`)] };
  },
  
  transformData: async (state: WorkflowState) => {
    const rawData = state.variables.rawData;
      
    // Data transformation logic
    const transformed = rawData.map(record => ({
      ...record,
      normalizedAt: new Date().toISOString(),
      processed: true
    }));
      
    state.variables.transformedData = transformed;
      
    return { messages: [new SystemMessage('Data transformation complete')] };
  },
  
  loadData: async (state: WorkflowState) => {
    const transformedData = state.variables.transformedData;
      
    // Save to database in batches
    const batchSize = 1000;
    let inserted = 0;
      
    for (let i = 0; i < transformedData.length; i += batchSize) {
      const batch = transformedData.slice(i, i + batchSize);
      await database.insertBatch(batch);
      inserted += batch.length;
    }
      
    state.variables.insertedCount = inserted;
      
    return { messages: [new SystemMessage(`${inserted} records saved`)] };
  }
};

```

--------------------------------

### Sowonflow Workflow Handler Implementation (TypeScript)

Source: https://sowonai.github.io/sowonflow-docs/custom-nodes

Implements various workflow handlers including initialization, parallel data validation, user info fetching, and permission checks. It utilizes Langchain messages for communication and mock APIs for simulating external services.

```typescript
import { WorkflowState } from 'sowonflow';
import { SystemMessage, HumanMessage } from '@langchain/core/messages';

const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));

const workflow = new Workflow({
  mainWorkflow: yamlContent,
  handlers: {
    // Initialization handler
    initializeData: async (state: WorkflowState) => {
      console.log('Data initialization started');

      // Extract user ID (from message or input)
      const userInput = state.messages?.[0]?.content || '';
      const userId = extractUserIdFromInput(userInput);

      // Update state variable
      state.variables.userId = userId;

      console.log(`User ID set: ${userId}`);

      return {
        messages: [new SystemMessage(`Initialization complete - User: ${userId}`)]
      };
    },

    // Data validation (parallel execution 1)
    validateInput: async (state: WorkflowState) => {
      console.log('Input data validation started');
      await delay(1500); // Simulate validation

      const userId = state.variables.userId;
      const isValid = userId && userId.length > 0;

      // Save results to state
      if (!state.variables.results) {
        state.variables.results = {};
      }
      state.variables.results.validation = {
        valid: isValid,
        message: isValid ? 'Valid input' : 'Invalid input'
      };

      console.log('Input data validation completed');

      return {
        messages: [new SystemMessage(`Validation result: ${isValid ? 'Success' : 'Failure'}`)]
      };
    },

    // Fetch user information (parallel execution 2)
    fetchUserInfo: async (state: WorkflowState) => {
      console.log('User information lookup started');
      await delay(2000); // Simulate API call

      const userId = state.variables.userId;

      // Simulate external API call
      const userInfo = await mockUserAPI.getUserInfo(userId);

      // Save results
      if (!state.variables.results) {
        state.variables.results = {};
      }
      state.variables.results.userInfo = userInfo;

      console.log('User information lookup completed');

      return {
        messages: [new SystemMessage(`User info: ${userInfo.name}`)]
      };
    },

    // Check permissions (parallel execution 3)
    checkPermissions: async (state: WorkflowState) => {
      console.log('Permission check started');
      await delay(1000); // Simulate permission system lookup

      const userId = state.variables.userId;

      // Permission check logic
      const permissions = await mockPermissionAPI.checkPermissions(userId);

      // Save results
      if (!state.variables.results) {
        state.variables.results = {};
      }
      state.variables.results.permissions = permissions;

      console.log('Permission check completed');

      return {
        messages: [new SystemMessage(`Permissions: ${permissions.join(', ')}`)]
      };
    },

    // Final processing (executed after join)
    processResults: async (state: WorkflowState) => {
      console.log('Final result processing started');

      const results = state.variables.results;

      // Integrate all parallel task results
      const summary = {
        validation: results.validation,
        user: results.userInfo,
        permissions: results.permissions,
        status: results.validation?.valid ? 'approved' : 'rejected'
      };

      console.log('Final processing completed:', summary);

      return {
        messages: [new SystemMessage(`Processing complete: ${JSON.stringify(summary, null, 2)}`)]
      };
    }
  }
});

// Mock functions
const mockUserAPI = {
  getUserInfo: async (userId: string) => {
    await delay(100);
    return {
      id: userId,
      name: `User_${userId}`,
      email: `${userId}@example.com`,
      department: 'Engineering'
    };
  }
};

const mockPermissionAPI = {
  checkPermissions: async (userId: string) => {
    await delay(100);
    return ['read', 'write', 'admin'];
  }
};

const extractUserIdFromInput = (input: string): string => {
  // Simple user ID extraction logic
  const match = input.match(/user[_s]*(\w+)/i);
  return match ? match[1] : 'default_user';
};

```

--------------------------------

### Define SowonFlow Email Agent Workflow (YAML)

Source: https://sowonai.github.io/sowonflow-docs/intro

This YAML configuration defines an AI workflow for an email agent. It specifies the agent's model (google/gemini-2.5-flash) and its ability to use the 'gmail' MCP server, along with the workflow's execution flow from start to end.

```yaml
version: "agentflow/v1"  
kind: "WorkflowSpec"  
metadata:  
  name: "Email Agent"  
  description: "An agent that can perform mail-related functions using the gmail mcp server."  
  
agents:  
  - id: "email_agent"  
    inline:  
      type: "agent"  
      model: "google/gemini-2.5-flash"  
      system_prompt: "You are an email agent."  
      mcp: ["gmail"]
  
nodes:
  start:
    type: "agent_task"
    agent: "email_agent"
    next: "end"
  end:
    type: "end"

```

--------------------------------

### Complex Routing Logic for Department Analysis

Source: https://sowonai.github.io/sowonflow-docs/examples/multi-agent-business

Illustrates a routing node configuration that analyzes user queries and determines which departments should be consulted. It uses a template to guide the analysis and specifies a comma-separated list for the output. This is a YAML configuration snippet.

```yaml
nodes:
  start:
    input:
      template: |
        Analyze: {{user_query}}

        Consider the following departments:
        - HR: Policies, benefits, personnel
        - Scheduling: Calendars, availability
        - Finance: Budgets, expenses, approvals
        - Legal: Contracts, compliance

        Respond with a comma-separated list or a single value: HR,Scheduling or Finance


```

--------------------------------

### SowonFlow Tool Security: File Path and Extension Validation

Source: https://sowonai.github.io/sowonflow-docs/tools

This code snippet illustrates input validation for a file path within a SowonFlow tool's function. It checks for potentially insecure path traversals (e.g., '../', '/') and validates file extensions against an allowed list.

```javascript
func: async ({ file_path }) => {
  // Path validation  
  if (file_path.includes('../') || file_path.startsWith('/')) {
    return "File path not allowed for security reasons.";
  }
    
  // File extension validation  
  const allowedExtensions = ['.txt', '.pdf', '.docx'];
  const ext = path.extname(file_path).toLowerCase();
  if (!allowedExtensions.includes(ext)) {
    return "Unsupported file format.";
  }
    
  // Normal processing  
  return await processFile(file_path);
}


```

--------------------------------

### YAML Workflow Definition for Parallel Custom Nodes

Source: https://sowonai.github.io/sowonflow-docs/custom-nodes

Illustrates a SowonFlow workflow designed for parallel processing using multiple custom nodes. It includes setup for state variables and defines the flow through parallel execution, joining, and final processing.

```yaml
version: "agentflow/v1"
kind: "WorkflowSpec"
metadata:
  name: "Parallel Custom Workflow"

state:
  variables:
    - name: "userId"
      initial_value: null
    - name: "results"
      initial_value: {}

nodes:
  start:
    type: "custom"
    handler: "initializeData"
    next: "parallelProcessing"

  parallelProcessing:
    type: "parallel"
    branches: ["dataValidation", "userLookup", "permissionCheck"]

  dataValidation:
    type: "custom"
    handler: "validateInput"
    next: "joinResults"

  userLookup:
    type: "custom"
    handler: "fetchUserInfo"
    next: "joinResults"

  permissionCheck:
    type: "custom"
    handler: "checkPermissions"
    next: "joinResults"

  joinResults:
    type: "join"
    next: "finalProcessing"

  finalProcessing:
    type: "custom"
    handler: "processResults"
    next: "end"

  end:
    type: "end"
```
Tokens:
Raw