scout-workflow

name	scout-workflow
description	Execute and manage Scout workflows programmatically. Use when you need to run workflows, create revisions, or manage workflow lifecycle via API. Supports execution, streaming, and CLI-based deployment.

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