scoutos/scout-workflow

Scout Workflow Skill

Execute and manage Scout workflows programmatically. Workflows are automated processes that connect tools, respond to triggers, and execute predefined sequences of actions.

Authentication

All Scout API endpoints require Bearer token authentication. Use your Scout API key.

Authorization: Bearer YOUR_API_KEY

Environment Variable (Recommended)

export SCOUT_API_KEY="your-api-key-here"

---

Base URL

https://api.scoutos.com

---

Workflow Execute

Execute a workflow by ID with optional inputs.

Endpoint

POST /v2/workflows/{workflow_id}/execute

Parameters

| Parameter | Type | Location | Required | Description | |-----------|------|----------|----------|-------------| | workflow_id | string | path | Yes | Unique workflow identifier | | environment | string | query | No | Execution environment: production (default), staging, development, console | | revision_id | string | query | No | Specific revision to execute | | session_id | string | query | No | Session ID for conversation continuity | | inputs | object | body | No | Key-value pairs passed to workflow | | streaming | boolean | body | No | Enable streaming response (default: false) |

Example: Basic Execution

curl -X POST "https://api.scoutos.com/v2/workflows/wf_abc123/execute" \
  -H "Authorization: Bearer $SCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "user_message": "Analyze this data and provide insights",
      "data_url": "https://example.com/data.csv"
    },
    "streaming": false
  }'

Example: With Environment

curl -X POST "https://api.scoutos.com/v2/workflows/wf_abc123/execute?environment=staging" \
  -H "Authorization: Bearer $SCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "query": "Find all customers with unpaid invoices"
    },
    "streaming": false
  }'

Example: Streaming Response

curl -X POST "https://api.scoutos.com/v2/workflows/wf_abc123/execute" \
  -H "Authorization: Bearer $SCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "user_message": "Generate a report"
    },
    "streaming": true
  }'

Response

{
  "run": {
    "stop_reason": "workflow_run_completed",
    "session_id": "sess_xyz789",
    "workflow_run_id": "run_def456",
    "state": {
      "output": {
        "result": "Analysis complete...",
        "summary": "3 insights found"
      }
    },
    "errors": []
  },
  "workflow_id": "wf_abc123",
  "output_block_id": "output_block_1"
}

Stop Reasons

| Value | Description | |-------|-------------| | workflow_run_completed | Workflow finished successfully | | workflow_run_failed | Workflow encountered an error |

---

Python SDK

Install

pip install scoutos

Basic Usage

from scoutos import Scout

client = Scout(api_key="YOUR_API_KEY")

# Execute workflow
response = client.workflows.run(
    workflow_id="wf_abc123",
    inputs={
        "user_message": "Hello there! I have a question...",
    }
)

# Print result
print(response)

Streaming

from scoutos import Scout

client = Scout(api_key="YOUR_API_KEY")

# Stream workflow execution
response = client.workflows.run_stream(
    workflow_id="wf_abc123",
    inputs={
        "user_message": "Hello there! I have a question..."
    }
)

for chunk in response.data:
    print(chunk)

Create Revision

from scoutos import Scout

client = Scout(api_key="YOUR_API_KEY")

# Deploy a new workflow revision
response = client.workflows.create_revision(
    workflow_id="wf_abc123",
    workflow_key="my-workflow"
)

Async Client

import asyncio
from scoutos import AsyncScout

client = AsyncScout(api_key="YOUR_API_KEY")

async def main():
    response = await client.workflows.run(
        workflow_id="wf_abc123",
        inputs={"query": "Search for documents"}
    )
    print(response)

asyncio.run(main())

---

TypeScript SDK

Install

npm install scoutos
# or
pnpm add scoutos

Basic Usage

import { ScoutClient } from "scoutos";

const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });

// Execute workflow
const response = await client.workflows.run("workflow_id", {
  inputs: {
    user_message: "Hello there! I have a question...",
  }
});

console.log(response);

Streaming

import { ScoutClient } from "scoutos";

const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });

const response = await client.workflows.run_stream("workflow_id", {
  inputs: {
    user_message: "Hello there! I have a question..."
  }
});

console.log(response);

---

Scout CLI

The Scout CLI enables managing workflows as code, with version control and CI/CD integration.

Install

brew tap scoutos/scoutos-cli
brew install scoutos-cli

Initialize Project

scout init

Link Account

scout link

Run Workflow Locally

scout workflows run <workflow_folder>

Deploy Workflow

scout workflows deploy <workflow_folder>

Check Version

scout --version

---

Workflow Project Structure

project/
├── workflows/
│   └── my-workflow/
│       ├── workflow.yml       # Workflow definition
│       └── inputs/
│           └── default.json  # Default input parameters
└── scout.config.ts            # Project configuration

workflow.yml Example

name: My Workflow
description: An automated workflow
trigger:
  type: webhook
blocks:
  - id: input_1
    type: input
    config:
      fields:
        - name: user_message
          type: string
  - id: llm_1
    type: llm
    config:
      model: gpt-4
      prompt: "{{ inputs.user_message }}"
  - id: output_1
    type: output
    config:
      result: "{{ llm_1.response }}"

---

Workflow Block Types

Input/Output Blocks

| Block | Description | |-------|-------------| | Input | Defines workflow input fields | | Output | Defines workflow output | | Text | Dynamic text with Jinja templating | | JSON | JSON data processing | | HTTP Request | Make HTTP API calls | | Extract Links | Extract links from markdown |

AI Processing Blocks

| Block | Description | |-------|-------------| | LLM | Generate text with language models (OpenAI, Anthropic) | | LLM Reasoning | Text generation with reasoning | | Execute JavaScript | Run custom JavaScript code | | Web Search | Search the web and extract results | | Web Page Scrape | Scrape web page content | | Exa Search | Advanced search with Exa API | | Exa Webpage Contents | Scrape webpage content with Exa |

Control Flow Blocks

| Block | Description | |-------|-------------| | Conditional | Branch based on conditions | | Continue If | Continue if condition is true | | Delay | Pause workflow execution | | Stop If | Stop if condition is true | | Reduce | Iterate with accumulator pattern |

Communication Blocks

| Block | Description | |-------|-------------| | Slack Message | Format markdown for Slack | | Slack Message Post | Post messages to Slack | | Slack Reaction | Add emoji reactions | | Slack Thread Get | Retrieve thread messages | | Trigger Slack | Trigger from Slack events | | Discord Message | Send messages to Discord | | Twilio Message | Send SMS via Twilio | | Copilot Message | LLM-powered responses | | Copilot Links | Display links with metadata |

Third-Party Integration Blocks

| Block | Description | |-------|-------------| | HubSpot Contact Create | Create contacts in HubSpot | | HubSpot Contact Get | Retrieve contact info | | HubSpot Contact Search | Search contacts | | Linear Ticket Create | Create issues in Linear |

Data Storage Blocks

| Block | Description | |-------|-------------| | Query Collection Table | Search Scout collections | | Save Document to Table | Save documents to tables | | Key-Value Read | Read from key-value store | | Key-Value Write | Write to key-value store | | Key-Value Delete | Delete from key-value store |

Debug Blocks

| Block | Description | |-------|-------------| | Inspect Graph | Debug workflow state |

---

Workflow Environments

| Environment | Description | |-------------|-------------| | production | Live environment (default) | | staging | Pre-production testing | | development | Development testing | | console | Latest changes in Scout UI |

---

Jinja Templating

Use Jinja syntax in workflow blocks for dynamic content:

{{ inputs.user_message }}
{{ llm_block.response }}
{% if condition %}value{% endif %}

Common Patterns

# Access previous block output
{{ llm_1.generated_text }}

# Conditional logic
{% if input_block.priority == "high" %}
Urgent: {{ input_block.message }}
{% else %}
{{ input_block.message }}
{% endif %}

# Loop over arrays
{% for item in input_block.items %}
- {{ item.name }}: {{ item.value }}
{% endfor %}

# Date formatting
{{ "now" | datetime_format("%Y-%m-%d") }}

---

Error Handling

When a workflow fails, check the errors array in the response:

{
  "run": {
    "stop_reason": "workflow_run_failed",
    "errors": [
      "LLM block failed: API rate limit exceeded"
    ]
  }
}

SDK Error Handling

from scoutos import Scout
from scoutos.core.api_error import ApiError

client = Scout(api_key="YOUR_API_KEY")

try:
    response = client.workflows.run(
        workflow_id="wf_abc123",
        inputs={"query": "test"}
    )
except ApiError as e:
    print(f"Status: {e.status_code}")
    print(f"Error: {e.body}")

---

Best Practices

1. Use environments wisely — Test in development or staging before production
2. Handle errors gracefully — Check stop_reason and errors array
3. Use streaming for long workflows — Better UX for slow operations
4. Session continuity — Pass session_id for conversational workflows
5. Version control workflows — Use Scout CLI and Git for collaboration

---

Related Skills

• scout — Collections, tables, documents, syncs, agents
• aoconnect — AO processes for decentralized workflows
• agent-browser — Browser automation blocks in workflows

---

Additional Resources

• Scout Docs: https://docs.scoutos.com — Official documentation for all Scout features
• Workflow Docs: https://docs.scoutos.com/docs/workflows
• Blocks Reference: https://docs.scoutos.com/docs/workflows/blocks
• API Reference: https://docs.scoutos.com/api-sdk/endpoints/workflows/run
• CLI Repo: https://github.com/scoutos/cli
• Python SDK: https://github.com/scoutos/scoutos-python-sdk