# Agent Blocks: Run Agents as Workflow Steps
Source: https://docs.scoutos.com/agents/agent-blocks
Embed Scout agents as steps inside a workflow. Process unstructured data, route intelligently, generate content, and pass results to downstream blocks.
Agent Blocks are the bridge between [Agents](/agents/overview) and [Workflows](/workflows/overview). A workflow gives you reliable, repeatable structure — triggers, branching, and integrations that run the same way every time. An agent gives you judgment — the ability to read messy input, reason about it, and decide what to do. An Agent Block lets you drop that judgment into any step of a workflow, so the structured parts stay deterministic while the hard parts get handled by an AI agent.
Agent Blocks run an agent you've already built in Scout. If you don't have one yet, start with [Getting Started with Agents](/agents/getting-started) and come back once you have an agent to embed.
## When to Use an Agent Block
Reach for an Agent Block whenever a step needs to interpret something rather than follow a fixed rule.
**Processing unstructured data.** Pull intent, urgency, and key details out of an incoming email, support ticket, or document — text that has no fixed schema and can't be parsed with a condition.
**Intelligent routing.** Categorize tickets, score and qualify leads, or tag feedback so downstream blocks can branch on the result.
**Content generation.** Draft a follow-up email, summarize a meeting, or produce a report from the data the workflow has gathered so far.
**Research and enrichment.** Research a company, surface recent news, or assemble context about a contact before the workflow records or acts on it.
If a step is purely deterministic — "route to engineering when `priority == 1`" — use a [Condition Block](/workflows/blocks) instead. Agent Blocks are for the steps that genuinely need language understanding or judgment.
## How Agent Blocks Work
### Adding a block
Open the workflow where you want to add AI judgment, and click the **+** to add a new block.
Choose **Agent Block** from the block picker, then select which of your agents should run at this step.
Give the agent its instructions for this step and map in the inputs it needs (see below).
Choose how the agent should return its result — plain text, JSON, or structured data — based on what downstream blocks expect.
### Configuring inputs
An Agent Block can draw its inputs from three sources:
* **The workflow trigger** — data from the event that started the run, e.g. `{{ trigger.ticket_body }}`
* **Previous blocks** — output from any block earlier in the workflow
* **Static values** — fixed text or configuration you type directly
You reference dynamic inputs with Jinja template syntax. For example, to pass the body of an incoming ticket into the agent:
```text theme={null}
{{ trigger.ticket_body }}
```
Keep inputs small and explicit. Pass only the fields the agent needs to make its decision — not the entire workflow state. Focused inputs produce more reliable results and make the workflow easier to debug.
### Handling output
The agent's response is available to downstream blocks as `agent_result`, referenced through the block's name. If an Agent Block named `analyze_ticket` returns a structured result, later blocks can read individual fields:
```text theme={null}
{{ blocks.analyze_ticket.agent_result.category }}
{{ blocks.analyze_ticket.agent_result.urgency }}
{{ blocks.analyze_ticket.agent_result.suggested_action }}
```
When an agent returns JSON, parse it with a JSON block before referencing individual fields downstream. That guarantees later blocks receive clean, structured data instead of a raw string.
## Example: Meeting Follow-up Workflow
This workflow turns a raw meeting transcript into tracked tasks and a drafted follow-up email — without anyone reviewing the transcript by hand.
A webhook receives the meeting transcript when the call ends.
An agent reads the transcript and extracts action items, decisions, and follow-ups, assigning an owner and deadline to each.
An Action Block creates a task in your project tool for each action item the agent returned.
A second agent drafts a follow-up email summarizing the decisions and next steps.
An Action Block sends the draft through Gmail to the meeting attendees.
The workflow runs the same way every time, while the agents absorb the nuance of each individual meeting — different attendees, different decisions, different follow-ups.
## Example: Lead Intelligence Workflow
This workflow enriches a new lead, records it, and routes it based on its value — combining research, a CRM write, content generation, and branching in a single run.
A webhook fires when a new lead submits a form.
An agent researches the lead's company and assembles context: size, industry, recent news, and a lead score.
An Action Block creates a CRM record populated with the enriched data.
An agent generates a personalized outreach email tailored to the company and its context.
A Condition Block checks the lead score: high-value leads notify a sales rep immediately, while the rest enter a nurture sequence.
## Best Practices
**Keep agents focused.** One task per block. Chain several focused Agent Blocks rather than asking a single agent to do everything — focused agents are more accurate and far easier to debug when something goes wrong.
**Define clear outputs.** Tell the agent exactly what format to return, ideally JSON with named fields like `category`, `urgency`, `summary`, and `suggested_action`. Predictable output is what makes downstream blocks reliable.
**Handle edge cases.** Add a Condition Block after the agent to catch invalid or low-confidence output and route it to a human review queue instead of letting the workflow act on a bad result.
**Use instructions as configuration.** Be specific in the prompt about the inputs, the required output format, and any constraints. The prompt is how you tune an Agent Block's behavior for its place in the workflow.
## Limitations
* **Agent Blocks run synchronously by default.** The workflow waits for the agent to finish before moving to the next block.
* **Split long tasks.** Complex work that takes more than a few seconds should be broken across multiple blocks, or handled with [async interactions](/agents/getting-started) so the workflow isn't blocked.
* **Use Condition Blocks for deterministic logic.** If a decision doesn't require judgment, a Condition Block is faster and more predictable than an agent.
***
## Next Steps
See how triggers, blocks, and branching fit together.
Explore every block type you can combine with Agent Blocks.
Build and configure the agents you embed in workflows.
Coordinate multiple agents on a single complex task.
# Agent Versioning: Git for Agents, Without the Commands
Source: https://docs.scoutos.com/agents/agent-versioning
Scout versions every change to your agents. Test changes in isolation, promote the best version to production in one click, and roll back instantly.
Agent Versioning is version control built into Scout. Every time you change an agent, Scout captures a new version automatically — so you can experiment freely, test changes without touching production, and roll back the moment something goes wrong. It's the safety net that lets you iterate on live agents with confidence.
* **Automatic versioning** — every edit creates a new version, no manual saves of "v2-final-final" required
* **Version isolation** — test changes without affecting the version your users see
* **One-click promotion** — make any version the production version instantly
* **Instant rollback** — revert to a previous version in seconds
Each version is its own agent ID, and the **active** version is the one designated for production.
## The Problem It Solves
Agent configurations are complex. A single agent ties together prompts, model parameters, database connections, workflows, skills and integrations, permissions, and scheduling. Change one prompt to fix an edge case and you might quietly break three others.
Without version control, teams resort to workarounds: duplicating agents, copy-pasting configs into documents, or simply hoping the last change was an improvement. Agent Versioning replaces all of that with systematic change tracking and one-click rollback — no workarounds needed.
## Demo
## How It Works
Saving an agent captures everything that changed — prompts, model parameters, database connections, workflows, skills and integrations, and scheduling. Each version gets its own unique agent ID.
Older versions stay accessible. You can open them, test them, compare them side by side, and debug — all without affecting the version running in production.
When a version is promoted, it becomes the active version for scheduled runs, Copilot deployments, and manual executions. Everything that points at "the agent" now points at the new version.
Rolling back switches the active version pointer to a previous agent ID. There's no redeployment and no rebuild — the change takes effect immediately.
## Saving Versions
When you save an agent, a split button gives you two choices:
* **Save and Activate** — creates a new version *and* immediately promotes it to production. Use this when you're confident the change is ready for users.
* **Save as Inactive** — creates a new version without promoting it. The version is staged for testing only and production keeps running the current active version.
The split between these two options is what makes safe iteration possible: you can keep saving and testing inactive versions until one is ready, then activate it in a single click.
## Viewing Version History
The version history panel lists every version of an agent. For each one, you can see:
* **Agent ID** — the unique identifier for that version
* **Status** — whether the version is Active or Inactive
* **Created date** — when the version was saved
* **Author** — who made the change
* **Diff** — what changed compared to the previous version
When you open a version that isn't the active one, a banner appears to make clear you're viewing a non-production version.
## Testing Specific Versions
Open the version you want to test and use the **Interact** panel. It tests the exact version you're viewing, so you can validate an inactive version before promoting it.
Target a specific version by using its agent ID directly:
```bash theme={null}
curl -X POST https://api.scoutos.com/agents/{agentId}/interact \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "message": "Hello" }'
```
Because each version has its own agent ID, you can run automated tests against an inactive version without affecting production traffic.
### Copilot Deployment Versioning
Each Copilot deployment references a specific agent ID, which means you can validate a new version end to end before any user sees it:
Make your changes and choose **Save as Inactive** to create a new version.
Point a test Copilot deployment at the new version's agent ID.
Exercise the test deployment until you're confident the new version behaves correctly.
Activate the new version and update your production deployments to the new agent ID.
## Use Cases
Save each prompt iteration as an inactive version, test it against your validation data, and promote the one that performs best.
Add a new database connection in a fresh version and compare it against the current version before going live.
Run versions in parallel to compare token costs and output quality before switching models.
Revert to a known-good version instantly while you debug the newer one.
## Technical Details
* **Agent IDs** — every version has a unique agent ID (for example, `agent_abc123`). The active version is tracked as metadata on the agent.
* **Version storage** — each version is an immutable snapshot containing the full configuration (as JSON), references to the resources it uses, and metadata such as creator, timestamp, and parent version.
* **Access control** — version history is visible to anyone with access to the agent. Promoting and rolling back require edit permissions.
## Limitations
Version history is retained for **30 days** on standard plans.
* Historical versions can't be edited directly. To change an old version, restore it as a new version and edit that.
## Getting Started
Navigate to the agent you want to change in Scout Studio.
Make your changes — to the prompt, model, integrations, or anything else.
Choose **Save as Inactive** so production keeps running the current version.
Use the Interact panel to test the new version, and compare it against previous versions in the history panel.
Activate the new version once you're confident. If anything looks wrong later, use **Roll back** to return to a previous version.
***
## Next Steps
Manage where your agents are live across Slack channels.
Embed a specific agent version on your website or app.
Trace agent runs and debug behavior across versions.
# Asynchronous Agent Interactions: Run Long Tasks Without Blocking
Source: https://docs.scoutos.com/agents/async-interactions
Run long-running Scout agent tasks without holding an HTTP connection open. Supply a callback URL and receive the results via a signed webhook.
Some agent tasks run too long to hold an HTTP connection open. Instead of waiting, you supply Scout with a callback URL — Scout starts the task, returns immediately, and POSTs the result to your endpoint when the agent finishes.
## When to Use Async
* **Long-running tasks** — anything that runs longer than 30 seconds, such as order processing, report generation, or bulk data workflows
* **Unreliable connections** — environments where connections time out or drop before a synchronous response can return
* **Queued workflows** — cases where you enqueue tasks and handle their results separately
## How It Works
Provide a `callback_url` when starting the interaction.
Scout responds right away with `202 Accepted` and a `session_id`.
Scout runs the agent task without holding your connection open.
On completion, Scout POSTs the result to your callback URL.
## API Reference
### Start Async Interaction
Start an interaction that runs in the background and reports its result to a callback URL.
```text theme={null}
POST https://api.scoutos.com/world/{agent_id}/_interact_async
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```
#### Parameters
The messages to send to the agent. Each message has a `content` field: a list of text strings and drive file references.
An HTTPS URL where Scout POSTs the result when the agent finishes. Must be publicly reachable — see [Requirements](#requirements).
#### Request
```json theme={null}
{
"messages": [
{
"content": [
"Process all pending orders and send confirmation emails"
]
}
],
"callback_url": "https://your-app.com/webhooks/scout-callback"
}
```
#### Response
Scout returns `202 Accepted` immediately, before the agent runs.
The identifier for this agent session. Use it to correlate the callback with the request that started it.
The URL to fetch the full event stream for this session once it completes.
```json theme={null}
{
"session_id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
"events_url": "https://api.scoutos.com/world/agent_abc123/events/a1b2c3d4-e5f6-7890-ab12-cd34ef567890"
}
```
### Callback Payload
When the agent finishes, Scout POSTs a JSON payload to your `callback_url`.
A unique identifier for this callback delivery. Use it to deduplicate retries — see [Retry Behavior](#retry-behavior).
The session this callback reports on, matching the `session_id` from the original response.
Either `succeeded` or `failed`.
ISO 8601 timestamp of when the agent finished.
The URL to fetch the full event stream for the session.
Present only when `status` is `failed`. Contains a `code` and a human-readable `message`.
```json Success theme={null}
{
"callback_event_id": "2b2f5b7d-7a5d-4f9b-9f6d-8ed0d2c7a1d2",
"session_id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
"status": "succeeded",
"completed_at": "2026-03-05T14:30:00Z",
"events_url": "https://api.scoutos.com/world/agent_abc123/events/a1b2c3d4-e5f6-7890-ab12-cd34ef567890"
}
```
```json Failure theme={null}
{
"callback_event_id": "2b2f5b7d-7a5d-4f9b-9f6d-8ed0d2c7a1d2",
"session_id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
"status": "failed",
"completed_at": "2026-03-05T14:30:00Z",
"events_url": "https://api.scoutos.com/world/agent_abc123/events/a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
"error": {
"code": "EXECUTION_ERROR",
"message": "Agent exceeded maximum step count"
}
}
```
### Fetching Results
The callback payload confirms completion but doesn't include the agent's full output. Use the `events_url` to retrieve the complete event stream:
```text theme={null}
GET https://api.scoutos.com/world/agent_abc123/events/a1b2c3d4-e5f6-7890-ab12-cd34ef567890
Authorization: Bearer YOUR_API_KEY
```
## Callback Authentication
Every callback includes signature headers so you can confirm the request genuinely came from Scout:
```text theme={null}
X-Scout-Signature-Alg: HMAC-SHA256
X-Scout-Signature: t=1709651400,sig=base64-encoded-signature
```
### Verifying the Signature
Extract `t` (timestamp) and `sig` (signature) from the `X-Scout-Signature` header.
Concatenate the timestamp and the raw request body as `{timestamp}.{raw_request_body}`.
Compute HMAC-SHA256 over the base string using your org secret key.
Compare your computed value against `sig` using a constant-time comparison.
```python Python theme={null}
import hmac
import hashlib
import base64
def verify_scout_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
# Parse the header: t=1709651400,sig=base64...
parts = dict(item.split("=", 1) for item in signature_header.split(","))
timestamp = parts.get("t", "")
provided_sig = parts.get("sig", "")
# Build the signed string
signed_string = f"{timestamp}.{raw_body.decode('utf-8')}"
# Compute HMAC-SHA256
expected = hmac.new(
secret.encode("utf-8"),
signed_string.encode("utf-8"),
hashlib.sha256
).digest()
expected_b64 = base64.b64encode(expected).decode("utf-8")
# Constant-time comparison prevents timing attacks
return hmac.compare_digest(expected_b64, provided_sig)
```
```javascript Node.js theme={null}
const crypto = require("crypto");
function verifyScoutSignature(rawBody, signatureHeader, secret) {
// Parse the header: t=1709651400,sig=base64...
const parts = Object.fromEntries(
signatureHeader.split(",").map((p) => p.split("=", 2))
);
const timestamp = parts.t ?? "";
const providedSig = parts.sig ?? "";
// Build the signed string
const signedString = `${timestamp}.${rawBody}`;
// Compute HMAC-SHA256
const expected = crypto
.createHmac("sha256", secret)
.update(signedString)
.digest("base64");
// Constant-time comparison prevents timing attacks
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(providedSig)
);
}
```
### Example Webhook Handler (Express)
```javascript theme={null}
const express = require("express");
const crypto = require("crypto");
const app = express();
// Use raw body for signature verification
app.post("/webhooks/scout-callback", express.raw({ type: "application/json" }), async (req, res) => {
const sigHeader = req.headers["x-scout-signature"];
if (!verifyScoutSignature(req.body, sigHeader, process.env.SCOUT_SECRET)) {
return res.status(401).send("Invalid signature");
}
const payload = JSON.parse(req.body);
// Deduplicate using callback_event_id
if (await alreadyProcessed(payload.callback_event_id)) {
return res.status(200).send("Already handled");
}
if (payload.status === "succeeded") {
// Fetch the full event stream if you need step-by-step details
await handleSuccess(payload.session_id, payload.events_url);
} else {
await handleFailure(payload.session_id, payload.error);
}
// Respond within 10 seconds or Scout will retry
res.status(200).send("OK");
});
```
Always read the **raw** request body before calling `JSON.parse`. If the JSON is parsed and re-serialized first, the body bytes change and the signature won't match.
## Retry Behavior
Scout uses **at-least-once** delivery, so the same callback may arrive more than once.
* **Deduplication** — check `callback_event_id` before processing to avoid duplicate work
* **Retry schedule** — exponential backoff over roughly 24 hours
* **Retry triggers** — network errors or `5xx` responses from your endpoint
## Requirements
* `callback_url` must use HTTPS
* Private and internal URLs aren't supported (SSRF protection)
* Your endpoint must respond within 10 seconds
# Agent Code Execution: Run JavaScript in a Secure Sandbox
Source: https://docs.scoutos.com/agents/code-execution
Enable Scout agents to write and run JavaScript or TypeScript in a secure sandbox for structured API calls, data transforms, and precise calculations.
Language models are excellent at reasoning, summarizing, and making decisions — but they're unreliable for precise math, complex JSON manipulation, or structured HTTP calls to external APIs. Code Execution closes that gap. When you enable it on an agent, the agent can write JavaScript or TypeScript to solve a problem and run it in a secure sandbox, then use the real output to continue its work. If you've ever seen an LLM confidently produce a wrong calculation, this is the fix.
## What Code Execution Enables
Code Execution is the right tool when determinism, precision, or structured API handling matters:
* **Calling third-party APIs** with structured request and response handling — authentication headers, error checking, retry logic
* **Transforming and validating JSON payloads** — reshaping, filtering, and normalizing complex data structures
* **Running deterministic calculations** — scoring models, weighted rankings, currency conversions, statistical computations
* **Building lightweight data pipelines** — fetch, transform, filter, and return in a single execution
Code Execution is not designed for long-running batch jobs, heavy background processing, or operations with large side effects that haven't been explicitly requested by the user.
***
## How It Works
When Code Execution is enabled on an agent, the agent decides on its own whether writing code is the right approach for a given task. Here's the full flow:
1. The agent receives a task and determines that code is the most reliable path
2. The agent writes JavaScript or TypeScript to accomplish it
3. The sandboxed runtime executes the code under strict resource limits
4. The sandbox returns stdout, the return value, and any errors — the same feedback a developer would get in a terminal
5. The agent uses that output to respond to the user, pass results to another tool, or take the next step
The agent sees real output from real execution. There's no hallucination risk on the computed values.
***
## Enable Code Execution on an Agent
Navigate to your agent in Scout Studio.
Click the **Tools** tab in the agent editor.
Toggle on **Code Execution** from the native tools list.
Save your agent and send a prompt that requires a calculation, data transform, or API call. Review the **Logs** tab to see the code the agent generated and the output it received.
***
## A Real Example
Say your agent receives this prompt: *"Fetch the top five accounts from our CRM API and score them by revenue."*
The agent generates and executes something like this:
```javascript JavaScript theme={null}
const response = await fetch("https://api.example.com/accounts", {
headers: { Authorization: `Bearer ${env.CRM_API_KEY}` }
});
if (!response.ok) {
throw new Error(`CRM API error: ${response.status} ${response.statusText}`);
}
const accounts = await response.json();
const scored = accounts
.map(a => ({
name: a.name,
score: (a.annual_revenue * 0.6) + (a.employee_count * 0.4),
revenue: a.annual_revenue,
employees: a.employee_count
}))
.sort((a, b) => b.score - a.score)
.slice(0, 5);
return { ok: true, top_accounts: scored };
```
The agent gets the structured result back and can summarize it, pass it to another tool, or return it directly to the user. The scoring logic runs exactly as written — no approximation, no hallucination.
***
## Prompt Examples
These prompts naturally lead an agent to use Code Execution:
```text theme={null}
"Call this REST API endpoint, normalize the response, and return a table of active accounts."
```
```text theme={null}
"Compute weighted lead scores from this JSON payload and return the top 10 with reasons."
```
```text theme={null}
"Write JavaScript to parse these webhook events and group failures by error code."
```
```text theme={null}
"Fetch pricing data from this API, convert all currencies to USD, and summarize deltas by plan."
```
```text theme={null}
"Validate this JSON schema against our expected format and return a list of violations."
```
***
## Instruction Snippet
Add this block to your agent's instructions to guide when and how it uses Code Execution:
```text theme={null}
When a task requires deterministic compute, structured API integration,
or complex data transforms:
1. Prefer Code Execution over in-context reasoning for calculations,
parsing, and strict data transforms.
2. Keep generated code minimal and focused on the specific task.
3. Validate required input fields before executing.
4. Return structured outputs with clear, consistent field names.
5. Handle API errors explicitly — check response status codes and
throw descriptive errors on failure.
6. Explain failures in the final response with enough detail that
the user can take corrective action.
```
***
## Consistent Output Shapes
Give your agent a standard structure for both success and failure responses. Consistent shapes make downstream tool chaining predictable and make it easier for both the agent and humans to understand what happened.
**Success:**
```json theme={null}
{
"ok": true,
"data": { "top_accounts": [] },
"summary": "Fetched and scored 5 accounts from CRM API"
}
```
**Failure:**
```json theme={null}
{
"ok": false,
"error_code": "UPSTREAM_TIMEOUT",
"message": "CRM API timed out after 10 seconds",
"next_action": "Retry with a smaller batch size or contact CRM support"
}
```
Using `ok: true/false` as a top-level field lets the agent branch on results without parsing error strings — and makes log review much faster.
***
## Security Model
Code Execution runs in a sandboxed runtime with strict resource limits. Your agent's code cannot:
* Access the filesystem outside the sandbox
* Make outbound network calls to arbitrary destinations (unless explicitly allowed by your configuration)
* Spawn persistent processes or background workers
* Access other agents' data or Scout's internal systems
The sandbox is isolated per execution. Each run starts clean with no shared state from previous runs. Environment variables like API keys are injected by Scout — they are not exposed in plain text in the generated code or logs.
Before enabling Code Execution on a public-facing Copilot deployment, review your agent's instructions carefully. Ensure the agent is instructed to confirm before taking high-impact actions and to avoid executing code that wasn't explicitly requested by the user.
***
## Code Execution vs. Workflow JavaScript Block
Scout offers two places to run JavaScript. Here's when to use each:
| | **Agent Code Execution** | **Workflow JavaScript Block** |
| ----------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **When to use** | The agent decides at runtime what code to write based on the task | The logic is predefined and should always run the same way |
| **Who writes the code** | The agent generates it dynamically | You write it once in the workflow builder |
| **Best for** | Dynamic API calls, variable transformations, context-dependent logic | Fixed pipelines, repeatable computations, versioned business logic |
| **Versioning** | Not versioned — generated fresh each run | Versioned with the workflow |
Use **Agent Code Execution** when the agent needs to adapt its approach based on what it discovers. Use the **Workflow JavaScript Block** when the same logic runs identically every time and you want it reviewed, versioned, and locked.
***
## Best Practices
**Validate inputs before running.** Instruct the agent to check that required fields exist and have expected types before executing code that depends on them.
**Keep outputs small and structured.** Return only what's needed for the next step — not the entire raw API response. This keeps context clean and downstream processing fast.
**Handle errors explicitly.** Check HTTP status codes, catch exceptions, and return structured error objects rather than letting the code throw unhandled errors.
**Avoid side effects unless requested.** Don't write code that modifies external systems (CRM records, databases, emails) unless the user explicitly asked for that action.
**Log key decisions.** Include a `summary` field in your return value explaining what the code did. This makes log review significantly faster when debugging.
# Scout Copilot: Embed an AI Agent in Your Website or App
Source: https://docs.scoutos.com/agents/copilot
Deploy a Scout agent as an embeddable chat widget on your website or app. Configure instructions, tools, and widget behavior for your end users.
Copilot is how you put a Scout agent directly in front of your users — as a chat widget embedded on your website, inside your product, or anywhere a simple script tag can run. Every Copilot is powered by a Scout agent you configure, so the same agent you've been building and testing in Studio becomes the experience your customers, prospects, or internal teams interact with. You control the instructions, the tools it can use, and how it presents itself — without writing any backend code.
## What Copilot Is
A Copilot deployment is a lightweight embeddable widget backed by a Scout agent. When a user opens the widget and sends a message, they're talking to your agent — with access to exactly the tools you've enabled, following exactly the instructions you've written. The widget handles the conversation UI; your agent handles the intelligence.
Common Copilot use cases:
* **Customer support** — answer product questions, surface documentation, and escalate when needed
* **User onboarding** — walk new users through setup and answer questions at each step
* **In-app assistant** — help users get more from your product without leaving the page
* **Internal knowledge base** — give your team a conversational interface to internal docs and processes
* **Sales and marketing** — answer prospect questions on your website and qualify interest
***
## Creating a Copilot Deployment
Navigate to the agent you want to deploy in Scout Studio. If you haven't built the agent yet, see [Getting Started](/agents/getting-started) to set one up first.
In the agent editor, click **Settings** and open the **Deployments** section.
Click **New Deployment** and select **Copilot**. Give it a name that identifies where it will be used — for example, "Support Portal" or "Marketing Site."
Adjust the widget settings for this deployment. Each deployment can have its own welcome message, tags for session tracking, and optional features like text-to-speech.
Scout generates a deployment-specific embed snippet. Copy it and paste it into your website or application where you want the widget to appear.
***
## Embedding the Widget
The basic embed is a single script tag and a custom element. Paste this into your HTML where you want the widget to appear:
```html HTML theme={null}
```
Replace `your-copilot-id` with the deployment ID shown in Scout Studio. That's everything required for a basic deployment. The widget loads, positions itself, and connects to your agent automatically.
### Configuration attributes
You can extend the embed element with optional attributes to customize behavior:
| Attribute | Required | Description | Default |
| ------------- | -------- | ------------------------------------------------------------------- | ------- |
| `copilot-id` | Yes | The deployment ID from Scout Studio | — |
| `tags` | No | Array of tags attached to agent sessions for tracking and filtering | `[]` |
| `tts-enabled` | No | Enable text-to-speech playback for assistant messages | `false` |
### Add session tags
Pass metadata tags to every session your Copilot creates. Tags appear in the **History** view in Studio and can be used to filter and categorize sessions by source, page, or user segment:
```html HTML theme={null}
```
Use tags to distinguish traffic from different placements — your homepage widget, your app's help sidebar, your support portal — so you can analyze them separately in Studio.
### Enable text-to-speech
Add `tts-enabled="true"` to make the widget read assistant messages aloud:
```html HTML theme={null}
```
When TTS is enabled, a speaker icon appears next to each assistant message. Users can click it to hear the message read aloud. Starting a new message automatically stops any currently playing one. TTS runs entirely in the browser — message content is not sent to any third party for speech synthesis.
**Browser support for TTS:** Chrome 33+, Safari 7+, Edge 14+, Firefox 49+. If the browser doesn't support TTS, the control appears disabled with an accessible message.
***
## How Agent Revisions Work
Copilot deployments always use the agent's active revision. When you update your agent's instructions, tools, or model settings and promote the new version, the Copilot automatically starts using it — you don't need to update or replace the embed snippet.
Test your Copilot after making significant changes to the agent. A change that improves behavior in Studio may affect the public-facing widget in unexpected ways, especially if the instructions weren't written with a public audience in mind.
***
## Multiple Deployments for One Agent
A single agent can power multiple Copilot deployments simultaneously. This is useful when you want the same underlying intelligence with different surface-level configurations — different welcome messages, different tags, different placement on your site.
Each deployment is a separate channel into the same agent:
* Public homepage Copilot — welcoming, general-purpose
* Authenticated in-app assistant — more direct, assumes product context
* Customer support portal — focused on known issues and escalation paths
* Internal team tool — accesses internal knowledge sources not exposed publicly
Create each as a separate deployment so you can tailor the experience and track sessions independently.
***
## Public Deployment Checklist
Before you embed a Copilot on a public-facing site, review what your agent can do from a user's perspective. A tool that's harmless in internal testing may create risk when exposed to anonymous users.
### Review your tools
Check each tool enabled on the agent and ask: should an anonymous user be able to trigger this?
Look out for:
* **CRM or ticketing tools** that can read or modify customer data
* **Email or messaging tools** that can send outbound communications
* **Internal knowledge sources** that contain information not meant for external audiences
* **Code execution** or web access that could be misused by adversarial prompts
* **Tools with side effects** — anything that creates, updates, or deletes records in downstream systems
Disable any tool that a public user shouldn't have access to, or create a separate agent for the public Copilot with a more restricted tool set.
### Tighten your instructions
Public Copilots need stricter guardrails than internal agents. Update the instructions to:
* Define what kinds of requests the agent should refuse
* Limit when it calls tools versus answering directly from its knowledge
* Require explicit confirmation before taking any high-impact action
* Instruct it not to reveal sensitive internal information even if asked
* Set clear boundaries on tone, scope, and response length for a public audience
Test your public Copilot with adversarial prompts before launch — ask it to ignore its instructions, reveal system prompts, or perform actions outside its intended scope. This surfaces instruction gaps before your users find them.
### Plan your deployment surfaces
Different placements usually benefit from different deployments with different configurations. Think through each surface where you want the Copilot to appear and whether a single configuration covers all of them, or whether separate deployments with tailored instructions make more sense.
***
## Common Questions
**Can I change the appearance of the widget?**
The widget adapts to your site's theme automatically. For deeper appearance customization, create the deployment in Studio and use the available configuration options. Advanced styling may require reaching out to Scout support.
**Do I need to re-embed after updating my agent?**
No. The embed snippet points to the deployment, and the deployment always uses the agent's active revision. Update the agent, promote the revision, and the Copilot updates automatically.
**Can I restrict the Copilot to authenticated users only?**
Yes. Deploy the embed snippet only on pages behind your authentication wall. The Copilot widget itself doesn't enforce authentication — your application does.
**How do I track which sessions came from the Copilot?**
Use the `tags` attribute on the embed element: `tags='["source:copilot", "surface:homepage"]'`. Sessions with these tags appear in your agent's History tab in Studio where you can filter and analyze them.
**Can I have the same Copilot on multiple pages?**
Yes. Paste the same embed snippet on as many pages as you need. If you want to track sessions per page, use tags to identify the source page.
# Agent Delegation: Multi-Agent Collaboration in Scout
Source: https://docs.scoutos.com/agents/delegation
Coordinate multiple Scout agents using delegation and multi-agent chats. Route tasks to specialized sub-agents and assemble results automatically.
When a task is complex enough that a single agent struggles to handle it well, multi-agent collaboration gives you a better architecture. Instead of one agent doing everything adequately, you build a team of focused specialists — each excellent at one thing — and coordinate them to deliver results that a single agent couldn't match. Scout supports two patterns for this: **multi-agent chats**, where you bring multiple agents into a single conversation yourself, and **agent delegation**, where a coordinator agent routes sub-tasks to specialists automatically.
## Multi-Agent Chats
The simplest form of multi-agent collaboration requires no setup beyond having multiple agents in your workspace. In Scout Studio's chat interface, you can mention multiple agents in the same conversation by typing `@` followed by an agent name. Each agent receives the message and responds from its own perspective, with its own tools and instructions.
Use multi-agent chats when:
* You want to compare outputs from agents with different specializations
* You need a quick review or second opinion from another agent
* You're exploring a problem from multiple angles before committing to an approach
This pattern works well for ad-hoc collaboration. For systematic, repeatable workflows — where a coordinator always routes specific task types to specific specialists — agent delegation is the better fit.
***
## Agent Delegation
Agent delegation lets one agent hand off sub-tasks to other agents programmatically. A **coordinator agent** receives the user's high-level goal, identifies the sub-tasks involved, routes each to the right specialist, and assembles the results into a final response. The user interacts only with the coordinator — the specialist agents work behind the scenes.
### Why delegation produces better results
A general-purpose agent making decisions across many domains tends to be mediocre at all of them. Specialized agents, each focused on a narrow task, outperform a generalist on every dimension — accuracy, speed, and reliability.
```text Without delegation theme={null}
One agent handles everything:
"Analyze this sales call, update the CRM, draft a follow-up email,
research competitor alternatives, and write a deal strategy."
→ Average quality across all five tasks
```
```text With delegation theme={null}
Coordinator identifies sub-tasks and routes them:
├─ Call Analysis Agent → reviews transcript and extracts key insights
├─ CRM Agent → updates records with structured data
├─ Writing Agent → drafts the follow-up email
├─ Research Agent → surfaces competitive alternatives
└─ Strategy Agent → assembles a deal strategy from all inputs
→ Expert-quality output on each task
```
### How delegation works
When a coordinator agent delegates to a specialist:
1. The coordinator identifies a sub-task that a specialist handles better
2. It passes the relevant context — not the entire conversation, just what the specialist needs
3. The specialist executes its task using its own tools and instructions
4. The specialist returns structured results to the coordinator
5. The coordinator incorporates those results and continues toward the final goal
***
## Collaboration Patterns
### Coordinator and specialists
One agent acts as the orchestrator, routing task types to the right specialist. This is the most common delegation pattern.
```text theme={null}
Coordinator Agent
├─ Delegates to Salesforce Agent for CRM tasks
├─ Delegates to Gmail Agent for email drafts
├─ Delegates to Research Agent for web research
└─ Delivers final assembled response to the user
```
**Use when:** You have a primary workflow that occasionally needs specialized sub-tasks handled by a dedicated expert.
### Sequential pipeline
Each agent handles one phase of a task and passes its output to the next agent downstream.
```text theme={null}
Research Agent → gathers raw information
↓
Analyst Agent → synthesizes and identifies patterns
↓
Writer Agent → produces the final deliverable
```
**Use when:** Tasks have distinct phases that each benefit from specialized handling, and each phase depends on the output of the previous one.
### Panel of judges
Multiple agents review the same output from different angles, and the coordinator assembles a final decision based on their feedback.
```text theme={null}
Draft Agent → produces an initial output
↓
┌─────────────────────────────────────┐
│ Fact-Check Agent → verifies claims │
│ Brand Voice Agent → checks tone │
│ Compliance Agent → flags risks │
└─────────────────────────────────────┘
↓
Coordinator → synthesizes feedback → Final output
```
**Use when:** Quality is critical, errors are costly, and review from multiple perspectives genuinely improves the result. Common in content production, legal review, and high-stakes decision workflows.
### Parallel processing
Multiple agents work simultaneously on independent sub-tasks, and a coordinator combines their outputs into a unified result.
```text theme={null}
┌→ Pricing Agent → pricing analysis
User input ─────┼→ Technical Agent → technical assessment
└→ Support Agent → support requirements
↓
Coordinator → unified recommendation
```
**Use when:** Multiple independent analyses can run at the same time, and combining their outputs produces a more complete answer than any single agent could deliver.
***
## Setting Up Delegation
### Part 1: Enable your coordinator to delegate
1. Open your coordinator agent in Scout Studio
2. Click **Add Tool**
3. Find and select the **Delegate to Agent** tool
4. Update the agent's instructions to describe when and how it should delegate
Be explicit in the instructions about which agents to call and under what conditions:
```text theme={null}
You are a Sales Coordinator. When the user asks you to prepare for a
sales call, delegate as follows:
- Use the "Research Agent" to gather company background, recent news,
and key contacts. Pass the company name and any context from the
conversation.
- Use the "CRM Agent" to retrieve interaction history and deal stage.
Pass the company name and account ID if available.
- Use the "Writing Agent" to draft the final call brief. Pass the
research and CRM outputs as context.
Wait for each delegation to complete before passing results to the next
agent. Return a single consolidated brief to the user when all three
are done.
```
The more specific your instructions, the more reliably your coordinator routes to the right specialists.
### Part 2: Make your specialist agents delegatable
For a specialist agent to receive delegated tasks, it needs to be discoverable within your workspace.
1. **Set visibility to Team** — the coordinator can only delegate to agents it can see
2. **Give it a clear name and description** — the coordinator uses this information to decide when to delegate to it
3. **Write focused, narrow instructions** — a well-scoped specialist is easier to delegate to reliably
A good specialist agent instruction makes the role unambiguous:
```text theme={null}
You are a Financial Analyst Agent. Your only job is to analyze financial
data and extract key metrics: revenue, gross margin, EBITDA, year-over-year
growth, and notable line items.
Return results as structured JSON. Do not write prose summaries or make
strategic recommendations — that is handled by other agents downstream.
```
***
## Best Practices
**Keep specializations narrow.** Each agent should do one thing well. "I analyze financial statements and extract key metrics" is a better scope than "I help with finance stuff."
**Establish a standard output format.** Decide how specialist agents should return results — structured JSON, a specific template, or a defined set of fields — so the coordinator can reliably parse and combine their outputs.
**Avoid delegation loops.** Delegation should flow in one direction. An agent that delegates to another agent should never be in that agent's delegation chain.
```text theme={null}
✅ Agent A → Agent B → Agent C
❌ Agent A → Agent B → Agent A (loop — will cause problems)
```
**Plan for failures.** Include instructions for what to do if a specialist times out or returns an error: "If the CRM Agent fails, continue with the research output and note the missing CRM data in the final brief."
**Monitor with observability.** When something goes wrong in a multi-agent chain, use the **Logs** tab to trace which delegation failed and what input caused it. See [Observability](/agents/observability) for how to read delegation traces.
***
## Limitations and Trade-offs
**Latency adds up.** Each delegation adds a round-trip wait. A chain of three agents can take roughly three times as long as a single agent. Design your architecture so the quality improvement justifies the added time.
**Debugging is more complex.** Tracing a failure back to the right agent in a chain requires more effort than debugging a single agent. Scout's execution logs show each delegation step, which makes this manageable — but it's worth considering when deciding whether delegation is right for your use case.
**Not always worth it.** Short, self-contained tasks are faster handled directly. If delegation adds overhead without meaningfully improving quality, skip it and keep the logic in one agent.
***
## Common Questions
**How does the coordinator know which specialist to call?**
It uses the instructions you write. Be explicit: name the specialists, describe what each one is for, and tell the coordinator when to use each one. The clearer the instructions, the more reliably the routing works.
**Can a specialist agent also delegate to other agents?**
Yes, but be careful about building deep delegation chains. Each level adds latency and complexity. Keep chains to two or three levels at most.
**What happens if a specialist agent fails or times out?**
The coordinator handles it according to its instructions. Write explicit fallback behavior: "If the specialist returns an error, note it in the final output and continue without that input."
**Do specialists need special configuration to receive delegated tasks?**
Just two things: set visibility to Team so the coordinator can see them, and give them a clear name and description so the coordinator knows when to delegate to them.
# Deployments: Manage Agents Across Your Slack Channels
Source: https://docs.scoutos.com/agents/deployments
Use the Deployments view in Scout Studio to deploy agents to Slack channels, track live deployments, and browse available channels across connected workspaces.
The Deployments view is your central place to see and manage which Slack channels your agents are active in. From here you can deploy agents to new channels, track which ones are live, and browse all available channels across your connected workspaces.
![The Channels view showing Channel, Workspace, and Agents columns with active deployments]()
## Getting There
In Scout Studio, choose **Deployments** from the left sidebar. You'll see all Slack channels from your connected workspaces, grouped into **Active** and **Inactive**.
## Active and Inactive Channels
**Active** channels have at least one agent running. Each shows its workspace and a set of gradient orbs representing the deployed agents. Multiple agents can be active in a single channel.
**Inactive** channels exist in your workspace but have no agents deployed. Public channels appear with a `#` icon and private channels with a lock icon.
## Deploying an Agent to a Channel
Locate your target channel using the search bar, or narrow the list with the **All workspaces** dropdown.
Click the **+** button on the right side of the channel row.
Choose the agent you want to deploy from the picker.
Once deployed, the channel moves from **Inactive** to **Active** and the agent's orb appears in its row.
## Adding a New Channel
If the channel you want isn't listed, click **Add agent** in the top right corner. This lets you configure a new Slack channel connection and assign an agent to it.
***
## Next Steps
Connect your Slack workspace to Scout.
Embed agents on your website or in your app.
Run agents automatically on a schedule.
# Create Your First Scout Agent: A Step-by-Step Guide
Source: https://docs.scoutos.com/agents/getting-started
Create a Scout agent from a template or from scratch, connect tools, configure instructions, and run your first task — no prior experience needed.
Getting your first Scout agent running takes less than five minutes if you start from a template, or about fifteen if you prefer to build from scratch with full control over every setting. Either way, by the end of this guide you'll have an agent that can take a goal, reason through it, call tools, and deliver a result — without you writing a single line of logic.
## Option 1: Start from a Template
The Agent Marketplace is the fastest path to a working agent. Templates ship with pre-written instructions, the right tools pre-selected, and a guided flow for connecting your accounts.
Navigate to [studio.scoutos.com/agents/marketplace](https://studio.scoutos.com/agents/marketplace). Browse the available templates — Meeting Prep, Competitor Intel, Deal Monitor, Seller Guidance, CRM Hygiene, Personal Agent — and click any card to preview what it does and which integrations it requires.
When you find one that fits, click **Use Template**. Scout creates the agent with all its pre-configured instructions, selects the right tools, and prompts you to authorize any integrations the template needs (Salesforce, HubSpot, Google Workspace, and so on).
Follow the guided setup to connect your tools. You can skip optional integrations and add them later from the **Tools** tab on your agent.
Click **Chat** on your new agent and try one of the suggested prompts. Your agent is ready to work.
Templates are fully customizable after install. You can edit the instructions, add or remove tools, and adjust every setting — the template is just a starting point.
***
## Option 2: Build from Scratch
If your use case is specific to your team or you want full control from the start, build a custom agent at [studio.scoutos.com/agents/new](https://studio.scoutos.com/agents/new).
Choose a clear, descriptive name that tells your team exactly what this agent does.
* ✅ "Meeting Research Assistant"
* ✅ "Pipeline Risk Monitor"
* ❌ "Agent 1" or "Test"
Add a short description of its purpose — this also helps other agents know when to delegate to it.
Instructions are the system prompt that defines your agent's role, communication style, and guardrails. Be specific about what it should and shouldn't do.
```text theme={null}
You are a sales research assistant for our team. Your role is to:
- Search the web for accurate, up-to-date information about prospects
- Check our internal knowledge base first for any company-specific context
- Provide clear, concise summaries with sources cited
- Ask a clarifying question when the request is ambiguous
- Maintain a professional but direct tone in all responses
Always indicate whether information came from a web search or our
knowledge base. Keep summaries to three to five bullet points unless
the user asks for more detail.
```
Strong instructions are the single biggest factor in agent quality. Treat them like a job description for a new hire: the more clearly you define expectations, the better the results.
Go to the **Tools** tab to give your agent capabilities. Native tools are available immediately — toggle them on to activate:
* **Web Search** — search the internet for current information
* **Scout Knowledge Base Search** — search documents in your workspace
* **Code Execution** — write and run JavaScript or TypeScript for deterministic compute
To connect additional integrations (Google Workspace, Slack, Salesforce, HubSpot, GitHub, and more), visit [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations), authorize your accounts, then return to the **Tools** tab to toggle them on for this agent.
Start with two or three tools. You can always add more once you see how the agent behaves in practice.
Click the **Settings** tab to tune how your agent behaves.
**Model selection** — The default **Auto** setting lets Scout route each request to the best model for the task complexity, powered by [Not Diamond](https://notdiamond.ai). This is the right choice for most agents. Pin a specific model (Claude Sonnet, GPT-4o, etc.) only when you need predictable costs or have a specific reason to lock behavior.
**Response style** — Choose from Precise (focused, reliable answers — best for data tasks), Balanced (recommended for everyday use), Creative (expressive responses for writing and ideation), or Experimental (open-ended, freeform).
**Max steps** — Each tool call counts as one step. Set this based on task complexity:
* 5–10 steps for simple lookups and quick responses
* 15–20 steps for research tasks with multiple searches
* 25+ steps for complex workflows involving multiple tools
**Conversation starters** — Add two or three example prompts to help your team understand what this agent can do.
**Visibility** — Set to **Team** so your whole workspace can access the agent, or keep it **Private** while you're still testing.
Click **Save**, then click **New Chat** to test your agent. Try these prompts to verify the right tools are being used:
```text theme={null}
"What is [your company]?" — should use the knowledge base
"What's the latest news about AI agents?" — should use web search
"Summarize our docs on onboarding and find related web resources" — should use both
```
Refine your instructions or tool selection based on what you see.
***
## Schedule Your Agent
Once your agent is working well manually, you can set it to run automatically — no workflow required.
1. Open your agent and go to the **Triggers** tab
2. Click **Add Schedule**
3. Choose a frequency: daily, weekly, or a custom cron expression
4. Define the task the agent should run and any inputs it needs
5. Save and enable the schedule
For example, your pipeline monitor can check for at-risk deals every morning at 8 a.m. and post a summary to Slack — all without any manual trigger.
See [Agent Scheduling](/agents/scheduling) for cron syntax, examples, and how to monitor scheduled runs.
***
## Access Your Agent via SDK
In addition to Scout Studio and chat, you can call any agent programmatically using the Python or TypeScript SDK. Authenticate with an API key from [Settings → API Keys](https://studio.scoutos.com/settings/api-keys).
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
response = client.agents.interact(
agent_id="agent_abc123",
messages=[
{
"role": "user",
"content": "Research Acme Corp and summarize recent news."
}
]
)
print(response.content)
```
```typescript TypeScript theme={null}
import Scout from "scoutos";
const client = new Scout({ apiKey: "YOUR_API_KEY" });
const response = await client.agents.interact({
agentId: "agent_abc123",
messages: [
{
role: "user",
content: "Research Acme Corp and summarize recent news.",
},
],
});
console.log(response.content);
```
Replace `agent_abc123` with the agent ID shown in Scout Studio under your agent's settings. See the [API Reference](https://ref.scoutos.com) for the full list of parameters, including streaming responses and async interactions.
***
## Embed Your Agent as a Copilot
You can also deploy your agent as a chat widget on any website or web app with a single script tag:
```html HTML theme={null}
```
Go to your agent's **Settings → Deployments** to create a Copilot deployment and get your `copilot-id`. See [Copilot](/agents/copilot) for configuration options, appearance settings, and the public deployment checklist.
***
## Common Questions
**My agent isn't using the right tool.**
Make the instruction more explicit: "Always check the knowledge base before searching the web" or "Use the CRM tool whenever the user mentions a specific company or deal."
**Responses are too long or too short.**
Add a length preference to your instructions: "Provide a three-to-five bullet summary unless the user asks for more detail."
**Which model should I choose?**
Start with Auto. It routes each request to the right model based on complexity. Pin a specific model only if you need cost predictability or have found that a particular model works best for your use case.
**How do I share my agent with my team?**
Set **Visibility** to "Team" in the Settings tab. Anyone in your workspace can then find and chat with it.
**How do I see what my agent is doing?**
Open the **Logs** tab on your agent. It shows every tool call, decision, and execution trace for every session. See [Observability](/agents/observability) for a full walkthrough.
**What's the difference between a template and a custom agent?**
Templates are pre-configured for specific use cases — install and start working immediately. Custom agents give you full control but require more setup. Both are fully editable after creation.
# Monitor Agent Activity: Logs, Traces, and Tool Usage
Source: https://docs.scoutos.com/agents/observability
Track every Scout agent action with execution logs, tool usage traces, and session history. See what agents did, when, and why — full auditability.
When an agent produces an unexpected result, you need more than just the final answer — you need to see every decision that led to it. Scout gives you a complete picture of every agent session through two views in Studio: **History**, which shows every conversation your agent has had, and **Logs**, which breaks each session down into a step-by-step execution trace. Together they let you trace any interaction from the user's first message to the final response, understand exactly which tools were called and why, and catch issues before they become patterns.
## Where to Look
In Scout Studio, open any agent and use these two views:
* **History** — review prior sessions and conversations, with timestamps, tags, and summaries
* **Logs** — inspect every tool call, model decision, and execution event in a session
Start with **History** to find the session you want to investigate, then open **Logs** to see exactly what happened step by step.
***
## Activity Logs: History
The **History** tab shows every session your agent has handled. Each row includes:
* **Session ID** — a unique identifier for the interaction
* **Timestamp** — when the session started and how long it ran
* **Tags** — any metadata tags attached when the session was created
* **Summary** — a brief description of the conversation
Click any session row to open the full conversation thread. You'll see the complete message exchange between the user and the agent, which tools were called and what they returned, and the final response the agent delivered. This is the fastest way to review what a user actually experienced.
***
## Execution Traces: Logs
The **Logs** tab gives you a step-by-step trace of every event in a session. Each entry captures one thing the agent did — a model call, a tool invocation, an error — in the order it happened.
| Event type | What it shows |
| --------------- | ------------------------------------------------------------- |
| `llm_call` | The prompt sent to the model and the response returned |
| `tool_call` | The tool name, input arguments, and output received |
| `tool_error` | A tool call that failed, with the error message |
| `session_start` | Timestamp and metadata when the session began |
| `session_end` | Timestamp, duration, and final status when the session closed |
Use the Logs view when History shows a bad output but you can't tell why. The `llm_call` entries show you exactly what context the model received at each step — so you can spot truncated history, missing tool results, or a prompt that drifted off course. The `tool_call` entries show you the exact input the agent passed to each tool and the exact output it got back, so you can verify tools are being used correctly.
### Debugging a failed tool call
Open the **History** tab and click the session where the bad output occurred.
In the session detail view, open the **Logs** tab and scroll to find the relevant sequence of events.
Look for a `tool_error` entry. It shows the input the agent passed to the tool and the error message the tool returned.
Look at the `llm_call` that follows the error. This shows how the model interpreted the failure and what decision it made — whether it retried, tried a different tool, or gave up.
This workflow catches most issues without needing to reproduce them locally.
***
## Tool Usage
The Logs view surfaces every tool call your agent made in a session — reads, writes, API calls, code executions, and any other tool the agent invoked. For each call you can see:
* **Which tool was called** and when
* **What input the agent passed** — the exact arguments, queries, or payloads
* **What the tool returned** — the full response, including any errors
* **How long the call took**
Reviewing tool usage helps you understand whether your agent is using tools efficiently, whether it's calling the right tools in the right order, and whether any external service is causing slowdowns or failures. It also gives you a clear audit trail for any actions the agent took — writes to a CRM, emails sent, records updated — so you can verify the agent behaved as intended.
When a tool input uses [Variables](/agents/variables), the Logs view shows the resolved values that were passed to the tool. Sensitive header values are sanitized rather than logged raw.
***
## Interaction Tags
You can attach metadata tags to any agent session by including them in the API request. Scout stores these tags on the session record so you can filter History by them later.
Common tagging patterns:
* `source:eval` — test and evaluation traffic
* `source:end_user` — live user sessions
* `campaign:q1` — sessions tied to a specific campaign
* `team:support` — sessions from a particular team
Tags are observability metadata only. They are not added to the agent's prompt, not passed to tools, and do not affect how the agent behaves. Sessions without tags work exactly the same way.
### Tag rules
* Up to **20 tags** per request
* Up to **32 characters** per tag
* Allowed characters: lowercase letters, numbers, `:`, `_`, and `-`
* Scout automatically trims whitespace, lowercases values, removes empty tags, and deduplicates
* Requests with invalid tags return `400 Bad Request`
### Sending tags in a request
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
client.agents.interact(
agent_id="agent_abc123",
messages=[
{
"role": "user",
"content": "Run this evaluation prompt against the latest support workflow"
}
],
tags=["source:eval", "campaign:q1"]
)
```
```typescript TypeScript theme={null}
import Scout from "scoutos";
const client = new Scout({ apiKey: "YOUR_API_KEY" });
await client.agents.interact({
agentId: "agent_abc123",
messages: [
{
role: "user",
content: "Run this evaluation prompt against the latest support workflow",
},
],
tags: ["source:eval", "campaign:q1"],
});
```
```json JSON (raw request body) theme={null}
{
"messages": [
{
"role": "user",
"content": "Run this evaluation prompt against the latest support workflow"
}
],
"tags": ["source:eval", "campaign:q1"]
}
```
### Filtering History by tags
In the **History** tab, use the tag filter to find sessions by tag value:
* Press `Enter` or `,` to turn a typed value into a filter chip
* Use **ANY** to return sessions that contain at least one of your selected tags
* Use **ALL** to return sessions that contain every selected tag
* Tag filters work alongside date range, duration, and pagination controls
This makes it straightforward to compare evaluation runs against live user traffic, measure how different campaigns are using your agent, or isolate sessions from a specific team — without touching your agent configuration.
***
## Using Observability to Build Trust
Observability isn't just for debugging — it's how you and your team build confidence that agents are doing what you intended.
**Verify behavior after instruction changes.** After updating your agent's instructions, run a few test sessions and review the Logs to confirm the agent is following the new guidance. Don't assume — check.
**Audit high-stakes actions.** For agents that write to a CRM, send emails, or modify records, use tool call logs to confirm every action was appropriate. The logs give you a timestamped record of exactly what the agent did and with what input.
**Identify patterns in failures.** Filter History by failed sessions and look for common causes across Logs entries. A recurring `tool_error` on the same tool often points to a misconfigured integration, a rate limit, or an instruction that produces bad tool inputs.
**Compare test traffic to real traffic.** Use `source:eval` and `source:end_user` tags to keep evaluation sessions separate from live sessions, then compare them side by side in History to catch regressions before they affect users.
***
## Best Practices
* Use a consistent prefix scheme for tags — `source:`, `campaign:`, `team:` — so filters stay predictable
* Keep tag values short and exact; avoid spaces and special characters
* Use `source:eval` consistently for all test and evaluation traffic so it's easy to filter out of production metrics
* Don't put sensitive or user-identifying information in tags — they appear in the Studio UI and can be seen by workspace members
* Review logs for the first few runs after any significant change to agent instructions, tools, or model settings
# Agents
Source: https://docs.scoutos.com/agents/overview
Scout agents execute complex tasks using connected tools and AI judgment. Build agents without code or deploy them with full SDK control.
Scout agents are intelligent workers that understand a goal, figure out the steps to reach it, and carry those steps out using the tools you connect — all without you wiring up logic for every scenario. Whether you're automating meeting research, cleaning CRM data, or monitoring a competitor landscape, an agent handles the complexity while you focus on the outcome.
## What Agents Are
An agent in Scout combines three things: **instructions** that define its role and behavior, **tools** that give it the ability to act (search the web, query your CRM, send a Slack message, run code), and an **LLM** that supplies judgment — deciding which tool to use, interpreting results, and choosing what to do next.
Unlike a static automation that breaks whenever something unexpected happens, an agent adapts. It tries alternative approaches, handles edge cases, and asks for clarification when it genuinely needs it. You describe the outcome you want. The agent figures out the path.
## How the Agent Loop Works
Every Scout agent runs the same core loop from the moment you send a message or a scheduled trigger fires:
You give the agent a task in plain English — via chat, a scheduled trigger, or an API call. The agent reads its instructions and decides how to approach the work.
The agent selects the right tools from the ones you've connected: web search, a database query, a CRM lookup, custom code, and more.
The agent calls each tool, reads back what it returns, and incorporates that information into its understanding of the task.
The LLM evaluates the results and chooses the next action — call another tool, ask a clarifying question, or deliver a final response.
The loop continues until the goal is complete or the agent needs input from you. Every step is logged for full auditability.
## Agents vs. Workflows
Both agents and workflows automate work, but they're designed for different situations.
| | **Agents** | **Workflows** |
| ---------------------- | -------------------------------------- | ----------------------------------------- |
| **Best for** | Goals where the path isn't fully known | Predictable, repeatable, fixed-step tasks |
| **Input** | Plain-English goal or question | Structured trigger with defined inputs |
| **Handles surprises?** | Yes — adapts and retries | No — unexpected data breaks steps |
| **Configuration** | Instructions + tools | Visual node-based pipeline |
| **Output** | Conversational response or action | Deterministic output from final node |
Use an **agent** when you need flexible, goal-driven behavior — like "research this company and write a briefing." Use a **workflow** when every step is known in advance and consistency matters most — like sending a structured welcome email when a contact is created.
Agents and workflows work together. Workflows can be exposed as tools that an agent calls, giving you the best of both: flexible judgment at the agent layer and reliable, versioned logic at the workflow layer.
## Agent Marketplace
The fastest way to get started is the **Agent Marketplace** — a library of pre-built templates designed for common business tasks. Every template ships with pre-written instructions, the right tools already selected, and a guided setup to connect your accounts.
Browse templates at [studio.scoutos.com/agents/marketplace](https://studio.scoutos.com/agents/marketplace) and install one in under two minutes.
| Template | What it does |
| -------------------- | -------------------------------------------------------------------- |
| **Meeting Prep** | Researches companies, pulls recent news, and prepares call briefings |
| **Competitor Intel** | Monitors competitors and delivers intelligence reports |
| **Deal Monitor** | Watches your pipeline for at-risk deals and recommends next actions |
| **Seller Guidance** | Provides real-time coaching and deal strategy recommendations |
| **CRM Hygiene** | Validates and cleans contact records automatically |
| **Personal Agent** | A general-purpose assistant you configure for your own workflow |
See [Agent Templates](/agents/templates) for full descriptions and setup instructions.
## Key Capabilities
### Scheduling
Run agents automatically on a schedule without building a workflow. Set a daily, weekly, or custom cron schedule from the agent's **Triggers** tab and your agent handles the rest — morning briefings, weekly reports, nightly cleanups. See [Scheduling](/agents/scheduling).
### Code Execution
Enable agents to write and run JavaScript or TypeScript in a secure sandbox when plain reasoning isn't enough. Use it for structured API calls, complex data transforms, and deterministic calculations. See [Code Execution](/agents/code-execution).
### Multi-Agent Collaboration
Agents can work together in two ways:
* **Multi-agent chats** — Mention multiple agents in a single conversation and they collaborate on the task together.
* **Agent delegation** — A coordinator agent identifies sub-tasks and routes them to specialized agents, then assembles the results.
See [Delegation](/agents/delegation) for setup patterns, including the panel-of-judges pattern for quality-critical decisions.
### Variables
Let agents reference interaction-scoped values like tenant IDs and request context in tool inputs using `{{name}}` syntax. Configure organization secrets on trusted, locked surfaces instead of agent-authored runtime inputs. See [Variables](/agents/variables).
### Copilot Deployments
Embed any agent on your website or inside your app as a chat widget with a single script tag. Each deployment has its own configuration, so you can tailor behavior for different audiences. See [Copilot](/agents/copilot).
## Common Questions
**What's the difference between an agent and a workflow?**
Workflows are deterministic pipelines: input in, steps run in order, output out. They're great when every step is predictable. Agents are goal-driven: you describe what you want and the agent decides the steps, handles surprises, and asks for help when stuck. Use workflows when you know the path in advance. Use agents when the path depends on what you discover along the way.
**How reliable are agents?**
Very. Scout agents include built-in error handling and recover gracefully from tool failures. You can review every session in [Observability](/agents/observability) to see exactly what the agent did and why — every tool call, every decision, every result.
**Can I build a custom agent for something specific?**
Yes. The visual workflow builder lets you create custom tools without code. Attach them to any agent just like a native integration. If you can describe the logic, you can build it.
**Can agents work together?**
Yes. Use multi-agent chats or agent delegation to have specialized agents collaborate on a single task. One agent can act as a coordinator that routes sub-tasks to specialists and assembles the final output.
**Should I start with a template or build from scratch?**
Start with a template if one fits your use case — they're fully customizable after install. Build from scratch when you need something your team-specific that no template covers.
## Explore Further
Create your first agent from a template or from scratch, connect tools, and run your first task.
Browse pre-built agents for meeting prep, CRM hygiene, competitor intel, and more.
Set up recurring runs with daily, weekly, or custom cron schedules from the Triggers tab.
Coordinate multiple specialized agents using delegation and multi-agent chats.
Review activity logs, execution traces, and tool usage for every agent session.
Let agents write and run JavaScript in a secure sandbox for deterministic compute.
Reference runtime values in tool inputs and resolve them safely at execution time.
Embed an agent on your website or in your app as a chat widget.
Connect Salesforce, HubSpot, Slack, Notion, Google Workspace, and more.
# Agent Planning Tools: Reliable Execution on Complex Tasks
Source: https://docs.scoutos.com/agents/planning
Give Scout agents a structured way to plan, track, and adapt multi-step work with the CreatePlan, GetNextStep, and UpdatePlan tools.
Language models are strong at reasoning one step at a time, but complex tasks expose a weakness: an agent juggling many tool calls can lose track of progress, forget the original goal, or fall into loops of repeated actions. Planning tools fix this. They give the agent a structured way to map out an approach before executing, track which steps are done, and adapt the plan as it learns new information. The result is dramatically more reliable execution on multi-step work.
## Why Planning Matters
Without planning, an agent improvises step by step. On a simple lookup that's fine — but on a task with five or ten interdependent steps, improvising leads to predictable failure modes:
* **Getting lost** — the agent forgets what it has already done and repeats work
* **Losing the goal** — after several tool calls, it drifts away from the original request
* **Looping** — it makes the same call again and again without making progress
* **Stopping early** — it declares the task complete when steps remain
With planning, the agent builds a roadmap first, works through it in a logical sequence, tracks completed and remaining work, and adjusts deliberately when something changes. In the **Logs** tab, the difference is stark: reactive backtracking versus a consistent, traceable sequence of steps with intentional adjustments.
***
## The Three Planning Tools
Planning is provided by three tools that work as a set. Each handles one part of the plan-execute-adapt loop.
### CreatePlan
`CreatePlan` builds a structured plan at the start of a complex task. The agent analyzes the request and its available tools, breaks the work into discrete steps, identifies dependencies between them, and estimates complexity. Agents use it when a task has more than a couple of steps or spans multiple tools.
```json theme={null}
{
"plan_id": "plan_abc123",
"task": "Research competitor pricing and create comparison report",
"steps": [
{
"id": 1,
"description": "Search web for current pricing of top five competitors",
"tools": ["web_search"],
"status": "pending"
},
{
"id": 2,
"description": "Scrape pricing pages for detailed feature comparison",
"tools": ["web_scrape"],
"status": "pending"
},
{
"id": 3,
"description": "Format data into comparison table",
"tools": [],
"status": "pending"
},
{
"id": 4,
"description": "Generate summary report with insights",
"tools": [],
"status": "pending"
}
]
}
```
### GetNextStep
`GetNextStep` returns the current step to work on, along with relevant context from prior steps, and marks it in progress. The agent calls it after finishing a step or whenever it's unsure what to do next. Because it carries context forward, the agent stays oriented across a long task.
```json theme={null}
{
"step_id": 2,
"description": "Scrape pricing pages for detailed feature comparison",
"tools": ["web_scrape"],
"status": "ready",
"context": {
"previous_step": "Found pricing pages for four of five competitors",
"urls_to_scrape": [
"https://competitor-a.com/pricing",
"https://competitor-b.com/pricing"
]
}
}
```
### UpdatePlan
`UpdatePlan` keeps the plan in sync with reality. The agent uses it to add or reorder steps, change descriptions, mark steps complete, or skip steps that turn out to be impossible. This is what makes a plan a living guide rather than a rigid script.
Add a step when the agent discovers new work:
```json theme={null}
{
"action": "add_step",
"after_step": 2,
"step": {
"description": "Research pricing for newly discovered competitor X",
"tools": ["web_search", "web_scrape"]
}
}
```
Complete a step and record the result:
```json theme={null}
{
"action": "complete_step",
"step_id": 2,
"result": "Successfully scraped pricing from all five competitors"
}
```
Skip a step that can't be done, with a reason:
```json theme={null}
{
"action": "skip_step",
"step_id": 2,
"reason": "Competitor B's pricing page requires login, cannot access"
}
```
***
## Enable Planning Tools on an Agent
Navigate to your agent in Scout Studio.
Click the **Tools** tab in the agent editor, then click **Add tool**.
Find the **Planning** section and add **CreatePlan**, **GetNextStep**, and **UpdatePlan**. They work as a set — adding only `CreatePlan` leaves the agent unable to track progress or adapt.
Save your agent, then update its instructions so it knows when to plan (see below).
Add all three tools, not just one. The planning loop breaks if any are missing: without `GetNextStep` the agent can't track progress, and without `UpdatePlan` it can't adapt when something changes.
***
## Writing Instructions for Planning
Enabling the tools isn't enough — the agent needs guidance on *when* to plan. Add a block like this to your agent's instructions:
```text theme={null}
For any task with more than two or three steps, start by calling
CreatePlan to break the work into a sequence of steps.
- After completing each step, call GetNextStep to retrieve the next
step and the context you need for it.
- When you discover new work, hit a blocker, or learn something that
changes your approach, call UpdatePlan to add, reorder, complete,
or skip steps.
- For simple, single-step requests (a quick lookup, a single
calculation), skip planning and answer directly.
Treat the plan as a guide, not a rigid script — adjust it as you learn.
```
***
## When to Use Planning Tools
Planning adds the most value when a task is genuinely multi-step. Match the tool to the work.
**Good use cases:**
* **Multi-step research** — gathering and synthesizing information across several sources
* **Cross-system data work** — pulling from Salesforce, HubSpot, and other tools, then combining the results
* **Open-ended problem solving** — for example, investigating why a conversion rate dropped
* **Tasks with dependencies** — customer onboarding or anything where later steps depend on earlier ones
**Skip planning for:**
* **Simple single-step tasks** — looking up today's weather
* **Fixed, well-defined workflows** — where the steps never change (use a [Workflow](/workflows/overview) instead)
* **Quick lookups** — finding a contact's email address
***
## Worked Example
**Request:** *"Identify our top 10 cold leads and write personalized re-engagement emails for each."*
**Without planning**, the agent might search the CRM, start drafting an email for the first lead it finds, get sidetracked gathering more context, lose track of how many emails it has written, and finish with an incomplete, inconsistent result — or not finish at all.
**With planning**, the agent calls `CreatePlan` and produces a structured approach:
```json theme={null}
{
"plan_id": "plan_leads_42",
"task": "Identify top 10 cold leads and write re-engagement emails",
"steps": [
{
"id": 1,
"description": "Query CRM for leads with no activity in 90+ days",
"tools": ["crm_search"],
"status": "pending"
},
{
"id": 2,
"description": "Rank inactive leads by deal value and select top 10",
"tools": [],
"status": "pending"
},
{
"id": 3,
"description": "Gather context for each lead (industry, last interaction, deal stage)",
"tools": ["crm_search"],
"status": "pending"
},
{
"id": 4,
"description": "Draft a personalized re-engagement email per lead",
"tools": [],
"status": "pending"
},
{
"id": 5,
"description": "Save email drafts back to the CRM",
"tools": ["crm_update"],
"status": "pending"
},
{
"id": 6,
"description": "Summarize the outreach strategy for the user",
"tools": [],
"status": "pending"
}
]
}
```
The agent then works through the plan with `GetNextStep`, looping over each lead in steps 3 and 4. When it discovers a surprise — say three of the top 10 leads were already contacted last week — it calls `UpdatePlan` to skip those and pull in three replacements, keeping the count at 10. The result: all 10 emails drafted, personalized, and saved, plus a clear strategy summary.
***
## Best Practices
**Let the agent decide when to plan.** Don't force planning on every task. Instruct the agent to plan for complex work and answer simple requests directly.
**Be clear about goals.** Guide the agent to consider what information it needs, the best order to gather it, and what might change its approach. A clear goal produces a better plan.
**Allow plan flexibility.** Plans are guides, not scripts. Make sure your instructions encourage the agent to use `UpdatePlan` when reality differs from the plan.
**Checkpoint progress.** Instruct the agent to report what it has accomplished at natural checkpoints, so you can follow along and catch a wrong turn early.
***
## Frequently Asked Questions
No. Planning tools are best for complex, multi-step tasks. For agents that handle simple lookups or run a fixed sequence, they add overhead without benefit.
Yes — they work together. `CreatePlan` builds the plan, `GetNextStep` walks through it, and `UpdatePlan` keeps it current. Skipping one breaks the planning loop: without `GetNextStep` the agent can't track progress, and without `UpdatePlan` it can't adapt.
There's a small upfront cost to build the plan, and planning uses a few more tokens. On complex tasks the agent is usually faster overall, because it wastes less effort backtracking and repeating work. On simple tasks, skip planning.
Yes. The **Logs** tab shows every `CreatePlan` and `UpdatePlan` call, so you can see the plan the agent built and how it adjusted along the way.
A plan is a starting point. The agent uses `UpdatePlan` to correct course as it works. If you consistently see poor plans, refine the agent's instructions to clarify the goal and constraints.
# Schedule Agent Runs: Cron, Triggers, and Automation
Source: https://docs.scoutos.com/agents/scheduling
Set up recurring Scout agent runs using built-in scheduling. Configure daily, weekly, or cron schedules from the Triggers tab — no workflow required.
Scheduling lets your agents work on autopilot — running at defined intervals, completing their tasks, and delivering results without anyone having to trigger them manually. You configure a schedule directly on the agent from the **Triggers** tab, no workflow required. Once it's set, your agent runs exactly when you need it, every time.
Common uses include morning briefings delivered before the workday starts, weekly competitive intelligence reports, nightly CRM cleanup jobs, and hourly system health checks. If a task is worth doing on a recurring cadence, scheduling makes it automatic.
## Setting Up a Schedule
You configure the schedule from the trigger panel on the right side of the agent editor. The screenshot below shows a custom schedule being set up — choose a frequency, set the time, and pick the days the agent should run.
![The Scout agent editor with the Schedule Custom trigger panel open on the right, showing Mode, Name, Frequency, Time, and Day fields]()
Open your agent in Scout Studio and click the **Add Trigger** button. In the trigger panel, select **Schedule** as the trigger type.
Select from Daily, Weekly, or Custom (cron expression). See the options below for details on each type and example cron patterns.
Set the time, timezone, and any input values the agent needs to run. Inputs are passed to the agent on every scheduled execution — if your agent doesn't need dynamic inputs, leave this section empty.
```json theme={null}
{
"report_type": "weekly_summary",
"date_range": "last_7_days",
"recipient": "team@yourcompany.com"
}
```
Save your settings and enable the schedule. Your agent will begin running automatically at the times you specified. Check the **Logs** tab after the first run to confirm everything is working.
***
## Schedule Types
### Daily
Run your agent once per day at a specific time. Select your timezone so the schedule reflects your team's working hours rather than UTC.
Best for: daily summaries, morning prep briefings, overnight data processing.
### Weekly
Run your agent on specific days of the week at a set time. You can select one or multiple days — for example, Monday and Thursday, or just Friday for an end-of-week wrap-up.
Best for: weekly reports, periodic reviews, recurring team briefings.
### Custom Cron
Use cron syntax for anything more advanced — every four hours, twice a day, the first Monday of the month, and so on.
| Cron expression | Meaning |
| ---------------- | ----------------------------- |
| `0 9 * * *` | Every day at 9 a.m. |
| `0 9 * * 1` | Every Monday at 9 a.m. |
| `0 9 * * 1-5` | Weekdays at 9 a.m. |
| `0 */4 * * *` | Every four hours |
| `0 */2 * * *` | Every two hours |
| `0 0 * * 1` | Every Monday at midnight |
| `0 0 1 * *` | First day of every month |
| `0 8,17 * * 1-5` | Weekdays at 8 a.m. and 5 p.m. |
Use [crontab.guru](https://crontab.guru) to validate cron expressions before saving them. It shows a plain-English description of what your expression will do.
***
## Example Scheduled Agents
### Morning Sales Briefing
**Schedule:** `0 8 * * 1-5` — weekdays at 8 a.m.
**Instructions:**
```text theme={null}
Prepare a concise morning briefing for the sales team that includes:
- Today's calendar events from Google Calendar
- New leads added in the last 24 hours from Salesforce
- Any mentions of our company in the news overnight
- A summary of open support tickets flagged as urgent
Format as a scannable list. Keep the whole brief under 300 words.
```
**Tools:** Google Calendar, Salesforce, Web Search, Help Desk
**Output:** Post to #sales-team Slack channel
***
### Weekly Competitor Monitor
**Schedule:** `0 7 * * 1` — every Monday at 7 a.m.
**Instructions:**
```text theme={null}
Research our top five competitors and identify:
- Any pricing changes announced in the last seven days
- New product announcements or feature releases
- Press coverage, news mentions, or blog posts
- Job postings that might indicate a strategic shift
Write a summary report with links to sources. Flag anything that
requires an immediate response from our team.
```
**Tools:** Web Search, Exa
**Output:** Save to Drive as `/reports/competitors/YYYY-MM-DD.md` and email to leadership
***
### Nightly CRM Hygiene
**Schedule:** `0 2 * * *` — every night at 2 a.m.
**Instructions:**
```text theme={null}
Review contact and account records in Salesforce and:
- Flag duplicates for manual review
- Mark contacts with no activity in the last 90 days as stale
- Update any company data that appears outdated
- Generate a summary of records reviewed and changes made
If Salesforce is unavailable, retry once after 15 minutes. Log the
outcome either way.
```
**Tools:** Salesforce
**Output:** Log results to the "CRM Hygiene" table in Scout
***
### Hourly System Check
**Schedule:** `0 * * * *` — every hour
**Instructions:**
```text theme={null}
Check the status of our key systems and report:
- API response times for our three main endpoints
- Database connection health
- Error rates logged in the past hour
Post to #ops-alerts only if a metric exceeds its threshold.
Do not post if everything is healthy.
```
**Tools:** Custom monitoring tools, Slack
**Output:** Post to #ops-alerts only when issues are detected
***
## Managing Schedules
### Edit a schedule
Open your agent, go to the **Triggers** tab, and update any field — timing, frequency, inputs, or timezone. Changes take effect immediately after you save.
### Pause a schedule
Toggle the schedule off in the **Triggers** tab to stop it temporarily. Your configuration is preserved so you can re-enable it any time.
### Delete a schedule
Remove the schedule entirely from the **Triggers** tab. The agent continues to work normally and can still be triggered manually or via other trigger types.
***
## Monitoring Scheduled Runs
Open the **Logs** tab on your agent to see a full history of scheduled executions. Each log entry includes:
* When the run started and finished
* The inputs passed to the agent
* Every tool call, in order
* The output or response delivered
* Success or failure status with error details if applicable
After setting up a new schedule, check the Logs tab for the first two or three runs to confirm the agent is producing the expected output. Small instruction adjustments early on save a lot of time later.
***
## Agent Scheduling vs. Workflow Scheduling
Both agents and workflows support scheduling, but they're designed for different scenarios.
**Use agent scheduling when:**
* The task requires judgment, adaptation, or handling of unexpected data
* You want to configure the schedule directly on the agent without building a workflow
* The agent should decide its own approach based on what it finds
**Use workflow scheduling when:**
* The task is deterministic — every step is known in advance
* You need precise control over the order of operations
* The same pipeline runs identically every time with no branching logic
For most recurring business tasks — reports, briefings, monitoring, cleanup — agent scheduling is the right choice. It's faster to set up and handles the variability that breaks rigid pipelines.
***
## Best Practices
**Test before you schedule.** Run your agent manually with the same inputs you plan to use in the scheduled trigger. Confirm the output looks right before automating.
**Start simple.** Begin with daily or weekly schedules. Increase frequency only when you've confirmed the agent handles repeated runs reliably.
**Set your timezone explicitly.** Always choose your team's timezone rather than relying on a UTC default. A schedule set to "9 a.m." should run at 9 a.m. where your team is.
**Write failure handling into your instructions.** Tell the agent what to do when a tool is unavailable: "If Salesforce returns an error, log the issue and continue with the remaining data sources."
**Account for rate limits.** If your agent calls APIs with rate limits, avoid scheduling it too frequently. Hourly is usually safe; every five minutes may trigger throttling on some services.
**Monitor early runs.** Check the Logs tab after each of the first few scheduled runs. Catching a misconfiguration on run two is much easier than diagnosing it after thirty runs.
***
## Common Questions
**Do I need a workflow to schedule an agent?**
No. Scheduling is built directly into the agent's Triggers tab. You don't need to create a workflow.
**Can I have multiple schedules for one agent?**
Yes. Add multiple triggers with different frequencies, times, and inputs — for example, a daily summary and a separate weekly deep-dive report.
**What happens if a scheduled run is still in progress when the next one starts?**
Scout queues the next run. If the previous run is still active, the new run waits or is skipped depending on your agent's configuration.
**Can I still trigger the agent manually if it's on a schedule?**
Yes. Schedules add automatic triggers — they don't prevent you from triggering the agent manually at any time.
**How do I know if a scheduled run failed?**
Open the **Logs** tab. Failed runs are marked with an error status and include details about what went wrong so you can diagnose and fix the issue.
# Scout Agent Templates: Pre-Built Automation Blueprints
Source: https://docs.scoutos.com/agents/templates
Explore Scout's pre-built agent templates for meeting prep, CRM hygiene, competitor intel, deal monitoring, and more. Install and customize in minutes.
Agent templates are the fastest way to get value from Scout. Instead of writing instructions, selecting tools, and configuring settings from scratch, you install a template and start working — the agent arrives pre-configured, tested, and ready for your use case. Every template is fully customizable after installation, so you can tune it to fit your team's exact workflow.
## Why Use a Template?
Instructions, tools, and settings are pre-configured. Connect your integrations and you're done.
Templates show you how well-crafted instructions and tool selections work together — a great reference for building your own agents.
Built on workflows that real sales, ops, and research teams rely on daily.
Modify instructions, add or remove tools, and adjust settings after install — the template is a starting point, not a constraint.
### Template or custom agent?
**Use a template when:**
* Your use case matches one of the templates below
* You want something working in under five minutes
* You're new to Scout and want a proven starting point
**Build from scratch when:**
* Your workflow is highly specific to your team's internal processes
* You need integrations not covered by any template
* You want complete control over every setting from the start
***
## Available Templates
### Meeting Prep
Prepare for any call with comprehensive company research and a ready-to-use briefing document — delivered before you walk in.
**What it does:**
* Researches the company's background, funding history, and key products
* Pulls recent news, press releases, and announcements
* Identifies key decision-makers and their professional backgrounds
* Surfaces relevant CRM activity and previous interactions with your team
* Generates a structured briefing with talking points and recommended questions
**Best for:** Sales reps, account managers, and executives preparing for client or prospect calls
**Integrations:** Salesforce, HubSpot, Web Search, LinkedIn (optional)
**Sample prompt:**
> "I have a call with Acme Corp tomorrow at 2 p.m. Their VP of Sales is joining. Prep me."
***
### Competitor Intel
Monitor your competitive landscape automatically and receive regular intelligence reports without spending hours on manual research.
**What it does:**
* Tracks competitor websites for content changes and product updates
* Monitors news mentions, press releases, and earned media
* Analyzes pricing and positioning shifts over time
* Summarizes competitive threats and emerging opportunities
* Delivers regular briefings on a schedule you define
**Best for:** Sales teams, marketing, competitive intelligence, and strategy functions
**Integrations:** Web Search, Exa.ai (optional), Slack (for alerts)
**Sample prompt:**
> "What's changed with \[Competitor] in the last two weeks?"
***
### Deal Monitor
Keep a pulse on your pipeline and get proactive recommendations before deals go cold.
**What it does:**
* Analyzes your pipeline data to identify at-risk opportunities
* Monitors deal velocity, engagement patterns, and stage progression
* Flags deals that need immediate attention
* Recommends next actions based on deal stage and activity history
* Sends daily or weekly pipeline summaries to keep your team aligned
**Best for:** Sales managers, account executives, and revenue operations teams
**Integrations:** Salesforce, HubSpot, Pipedrive, Slack (for alerts)
**Sample prompt:**
> "Which of my deals are at risk this week?"
***
### Seller Guidance
Get real-time coaching and deal strategy recommendations exactly when you need them — in the middle of a deal, not after it's lost.
**What it does:**
* Analyzes deal context, history, and current stage
* Provides negotiation tactics and customized talking points
* Suggests next steps based on where the deal stands
* Identifies blockers and how to work through them
* Shares competitive positioning insights for the specific account
**Best for:** Sales reps and account executives actively working deals
**Integrations:** Salesforce, HubSpot, Pipedrive
**Sample prompt:**
> "I'm stuck on the Acme deal. The champion just changed. What should I do?"
***
### CRM Hygiene
Keep your CRM accurate and up-to-date automatically, so your team can trust the data they rely on.
**What it does:**
* Identifies incomplete or outdated contact and account records
* Validates contact information and flags likely errors
* Enriches accounts with current firmographic data
* Detects duplicate entries and surfaces them for review
* Suggests corrections and, where configured, applies fixes automatically
**Best for:** Sales operations, revenue operations, and CRM administrators
**Integrations:** Salesforce, HubSpot, Pipedrive
**Sample prompt:**
> "Check my accounts for missing data and show me what needs updating."
***
### Personal Agent
A general-purpose assistant you configure for your own workflow — research, writing, task management, or anything else you need help with daily.
**What it does:**
* Adapts to whatever tasks you define in the instructions
* Connects to the tools you choose — web search, knowledge base, email, calendar, and more
* Runs on a schedule or responds on demand
* Builds context over time through conversation history
**Best for:** Anyone who wants a flexible AI assistant tailored to their personal workflow
**Integrations:** Your choice — connect any combination of available tools
**Sample prompt:**
> "Summarize my unread Slack messages and tell me what needs my attention today."
***
## Installing a Template
Navigate to [studio.scoutos.com/agents/marketplace](https://studio.scoutos.com/agents/marketplace). Click any template card to see a full description, the required integrations, and sample prompts before you commit.
When you've found the right template, click **Use Template**. Scout creates the agent with pre-configured instructions, tools, and settings automatically.
The guided setup prompts you to authorize any integrations the template requires. If an integration isn't connected yet, Scout walks you through the OAuth flow. You can skip optional integrations and add them from the **Tools** tab later.
Click **Chat** and try one of the suggested prompts. Your agent is ready. You can also set up a schedule, adjust instructions, or add tools at any point — nothing is locked after install.
You can install the same template more than once with different configurations. For example: one Meeting Prep agent for enterprise accounts with deeper research, and another for SMB accounts with a faster, lighter setup.
***
## Customizing a Template
Templates are starting points, not ceilings. After installation you have full control over every part of the agent.
### Modify the instructions
Open the **Instructions** tab and edit the system prompt to match your specific needs. You can narrow the focus, add company-specific context, or change the output format entirely.
```text Before theme={null}
Research companies before meetings and summarize key information.
```
```text After theme={null}
Research B2B SaaS companies before meetings. Focus on recent funding rounds,
product announcements in the last 90 days, and headcount changes. Format the
output as a three-section brief: Company Overview, Recent Activity, and
Suggested Questions.
```
### Add or remove tools
Go to the **Tools** tab to connect additional integrations or remove access to tools this particular agent doesn't need. Keeping the tool list focused helps the agent make better decisions about when to use each capability.
### Create variations
Install the same template multiple times with different configurations to serve different segments, teams, or use cases — each becomes its own independent agent.
### Share with your team
Set **Visibility** to **Team** in the Settings tab so everyone in your workspace can use the agent.
***
## Common Questions
**Can I install multiple templates?** Yes. Install as many as you need — each becomes a separate, independently configurable agent.
**What if a template doesn't match my exact use case?** Install it anyway and modify the instructions and tools after installation. Templates are fully editable.
**Do I need to set up integrations before installing a template?** No. The guided setup walks you through connecting accounts during installation. You can also skip some and connect them later from the **Tools** tab.
**Can I see the agent's instructions before installing?** Yes. Click any template in the marketplace to preview its full configuration — instructions, tools, and sample prompts — before you commit to installing it.
**Are templates free?** Templates are free to install. You pay for agent usage (model calls and tool executions) based on your Scout plan.
# Variables in agent tool inputs
Source: https://docs.scoutos.com/agents/variables
Use interaction variables to pass request-scoped context into agent-authored tool inputs.
Variables let an agent reference interaction-scoped values in tool inputs. For example, an agent can send `{{city}}`, and Scout substitutes the value when the tool runs.
Use variables for request-specific context such as a tenant, workspace, locale, or routing value.
## What variables are
An interaction variable is a placeholder written in double curly braces that an agent can put in a tool input:
```json theme={null}
{
"query": "latest weather in {{city}}"
}
```
When the agent calls the tool, Scout replaces `{{city}}` with the actual value before the tool receives it. The tool sees the resolved value, and the model never has to hold it.
Interaction variables are values you supply when you start an interaction. Agents can reference them in runtime tool inputs during that interaction.
## Why use variables
Interaction variables let your application provide request context without copying it into an agent's prompt.
Variables separate the two responsibilities:
* Your application provides interaction values when it starts an interaction.
* The tool input keeps a symbolic reference until execution.
* Scout resolves the real value only when the tool executes.
An agent can use interaction variables to route a call to the correct tenant or workspace.
## When values are resolved
Variables are resolved at tool execution time, the moment before a tool runs, not when the prompt is rendered. A placeholder stays symbolic throughout the agent's reasoning and is substituted only as the tool is invoked.
Variables apply to **tool inputs only**. They are not interpolated into prompts, messages, or model context.
## Syntax
Scout supports these interaction variable forms:
| Syntax | Resolves from |
| ------------------------- | --------------------------------------------- |
| `{{NAME}}` | A top-level interaction variable |
| `{{local.path.to.value}}` | An interaction variable at the specified path |
| `{{customer.email}}` | An interaction variable at the specified path |
## Resolution rules
For agent-authored runtime tool input:
* **`{{NAME}}`** resolves from a top-level interaction variable.
* **`{{local.*}}`** resolves only from interaction variables.
* **`{{customer.email}}`**, a bare dotted path, resolves through interaction variables only.
* **Missing values** resolve to an empty string.
Use interaction variables in agent-authored input for request-specific context such as tenant, workspace, locale, or routing metadata.
## Type behavior
How a resolved value is typed depends on where the placeholder sits:
* **Whole-field placeholder:** when a placeholder is the entire field value, the resolved value keeps its native type (object, array, number, boolean).
* **Embedded placeholder:** when a placeholder sits inside a larger string, the resolved value is converted to a string.
For example, `{{customer}}` on its own can resolve to a full object, while `"Bearer {{token}}"` always resolves to a string.
## Security model
Interpolation prevents Scout from placing a variable's value directly in the model context before a tool call:
* Values are resolved at tool execution time, not baked into the prompt.
* The tool receives the resolved value only when it executes.
Interpolation is not a guarantee that a secret stays hidden. A tool can return, transform, or otherwise reveal its resolved input in model-visible output. Only interpolate secrets into tools and configuration surfaces whose input and output behavior you trust.
## Examples
### Interaction-scoped variable
Supply a variable when you start the interaction, then reference it by name in the message. The agent uses `{{city}}` in the search tool's input, and Scout resolves it at execution time. Here `$AGENT` is your agent ID and `$SECRET` is a Scout [API key](/settings/api-keys).
```sh theme={null}
curl --request POST \
--url "https://api.scoutos.com/world/$AGENT/_interact" \
--header "Authorization: Bearer $SECRET" \
--header 'content-type: application/json' \
--data '{
"variables": {
"city": "Charleston, SC"
},
"messages": [
{
"content": [
"Search the web for latest weather in {{city}}. Only search once. Compact the results"
]
}
]
}'
```
### Nested interaction variables
Variables can be objects, and you can reference nested values with a dotted path.
```sh theme={null}
curl --request POST \
--url "https://api.scoutos.com/world/$AGENT/_interact" \
--header "Authorization: Bearer $SECRET" \
--header 'content-type: application/json' \
--data '{
"variables": {
"location": {
"city": "Charleston",
"state": "SC"
}
},
"messages": [
{
"content": [
"Search the web for latest weather in {{location.city}}, {{location.state}}. Only search once. Compact the results"
]
}
]
}'
```
### What the agent emits versus what the tool receives
The agent emits tool input with placeholders still in place. Scout resolves them just before the tool runs, and the tool receives only the final values.
```json Agent emits theme={null}
{
"query": "latest weather in {{city}}",
"headers": {
"X-Tenant": "{{tenant.id}}"
}
}
```
```json Tool receives theme={null}
{
"query": "latest weather in Charleston, SC",
"headers": {
"X-Tenant": "tenant_42"
}
}
```
### Native-type preservation
Because `{{customer}}` is the whole field, it resolves to the full object. Because `{{customer.email}}` is also a whole field, it resolves to the string at that path.
```json Agent emits theme={null}
{
"customer": "{{customer}}",
"customer_email": "{{customer.email}}"
}
```
```json Tool receives theme={null}
{
"customer": {
"email": "a@example.com",
"name": "Scout Customer"
},
"customer_email": "a@example.com"
}
```
## MCP per-call headers
MCP-backed tools accept a reserved `headers` input that lets an agent supply request headers for a single tool call. These headers are merged over the MCP connection's base auth headers and are not forwarded as normal tool arguments. They only shape the outbound request.
Configure credentials in the MCP connection or integration settings. This trusted configuration keeps standing authorization separate from agent-authored input.
Use interaction variables in per-call headers only for non-sensitive, request-specific metadata such as tenant, workspace, locale, or routing values:
```json theme={null}
{
"headers": {
"X-Tenant": "{{tenant.id}}",
"X-Workspace": "{{workspace_id}}"
}
}
```
Here both values come from interaction variables and resolve when the tool executes. The MCP connection's base headers provide authentication.
Do not use agent-authored per-call headers to carry credentials or secret references. An MCP tool can expose resolved header values through its output. Configure authentication on the trusted [MCP connection](/mcp-server/index) instead.
## Next steps
See how agents pick tools and run the core agent loop.
Connect MCP-compatible tools and configure base transport headers.
Inspect tool inputs and outputs, with resolved values, in the Logs view.
Start interactions programmatically and pass variables in the request.
# Creating Scout Databases, Tables, and Column Schemas
Source: https://docs.scoutos.com/databases/creating-databases
Set up Scout Databases and Tables for your agents. Define column schemas, configure metadata fields, and prepare your knowledge base for semantic search.
Databases are the data layer for your Scout agents. Before an agent can search your knowledge base or retrieve structured records, you need a Database with at least one Table and a defined schema. This page walks you through creating a Database in Scout Studio, configuring its Tables with typed columns, and getting data into them — both manually and via the API.
## Creating a Database
### From Scout Studio
Navigate to Databases in the left-hand sidebar of the Scout dashboard.
Click **+ New** at the top of the page. A creation dialog appears.
Provide the following:
* **Name** *(required)* — A clear, descriptive name, for example `Product Knowledge Base` or `Support FAQs`.
* **Description** *(optional)* — A short note about what this Database contains.
* **Icon** *(optional)* — A visual identifier to help distinguish it in the sidebar.
Scout provisions and indexes your Database. This typically takes about 30 seconds. The UI shows the current provisioning status — wait for it to finish before adding data.
### Via the API
```bash cURL theme={null}
curl -X POST https://api.scoutos.com/v2/collections \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Knowledge Base",
"description": "Product documentation and support articles"
}'
```
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
database = client.databases.create(
name="Knowledge Base",
description="Product documentation and support articles"
)
print(database)
# {'id': 'col_abc123', 'name': 'Knowledge Base', ...}
```
```typescript TypeScript theme={null}
import { ScoutClient } from "scoutos";
const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });
const database = await client.databases.create({
name: "Knowledge Base",
description: "Product documentation and support articles"
});
```
## Configuring Tables
Every new Database comes with one `Untitled` table. You can rename it and add columns to match your data model. Tables act as distinct namespaces within a Database — for example, a `Help Center` Database might have an `FAQs` table and a `Troubleshooting Guides` table.
### Adding Columns
Click the table name in the Database view to open it.
Click the **+** button in the table header row.
Enter a column name (use `snake_case`, for example `updated_at` or `category`) and select a column type from the list below.
Click **Save** or press Enter. The column appears immediately in the table schema.
### Column Types
| Type | Description | Best For |
| -------------------- | ------------------------- | ------------------------------- |
| **Single Line Text** | Short plain-text entries | Titles, category tags, IDs |
| **Multi Line Text** | Long-form text content | Descriptions, articles, notes |
| **Number** | Integer or decimal values | Prices, counts, Unix timestamps |
| **Checkbox** | Boolean true/false flag | Status flags, completion state |
| **URL** | A valid web address | Source links, reference URLs |
### Example Schema: Documentation Table
For a product documentation knowledge base, use this column layout:
| Column | Type | Purpose |
| ------------ | ---------------- | ----------------------------------------------- |
| `title` | Single Line Text | Article title displayed in search results |
| `content` | Multi Line Text | Full article text — indexed for semantic search |
| `url` | URL | Original source URL for attribution |
| `category` | Single Line Text | Topic classification for filtering |
| `updated_at` | Number | Unix timestamp of the last update |
### The `content` Column
The `content` column receives special treatment during indexing:
* **Automatic chunking** — Long content is split into chunks of roughly 2,500 characters so that each chunk fits within the embedding model's context window.
* **Vector embeddings** — Each chunk gets its own embedding, enabling fine-grained semantic matches within long documents.
* **Linked results** — Query results link back to the parent document so you always know which record matched.
Store all primary searchable text in a column named `content` for the best semantic search results. Scout uses this column for automatic embedding when vector indexing is enabled.
## Naming and Organizing Databases
Keep your Databases easy to navigate with a few consistent conventions:
* Use descriptive, noun-based Database names (`Customer Support`, `Product Catalog`, `Engineering Docs`).
* Use snake\_case for column names (`created_at`, `user_id`, `source_url`).
* Group related tables inside a single Database rather than creating many small Databases— it keeps context together and makes agent queries simpler.
* Add a description to every Database so teammates (and agents) understand its purpose at a glance.
## Adding Data
Choose the method that fits your workflow:
Best for small datasets or one-off additions. Click **+ Add Document** in the table view and fill in the fields directly.
Best for live data that changes regularly. Connect Notion, Google Sheets, or a website and let Scout sync automatically on a schedule.
Best for bulk imports and programmatic ingestion from your own applications.
Best for saving data produced by an agent or workflow step directly into a table.
### Manual Entry
1. Open your table in Scout Studio.
2. Click **+ Add Document** or click in any empty row.
3. Fill in the fields.
4. Click **Save**.
### Via the API or SDK
```bash cURL theme={null}
curl -X POST https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id}/documents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"documents": [
{
"id": "doc_001",
"title": "Getting Started Guide",
"content": "This comprehensive guide walks you through...",
"url": "https://docs.example.com/getting-started",
"category": "tutorial",
"updated_at": 1704067200
}
]
}'
```
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
# Add a single document
client.documents.create(
collection_id="col_abc123",
table_id="tab_xyz789",
documents=[{
"id": "doc_001",
"title": "Getting Started Guide",
"content": "This comprehensive guide walks you through...",
"url": "https://docs.example.com/getting-started",
"category": "tutorial",
"updated_at": 1704067200
}]
)
# Add multiple documents in a single request
client.documents.create(
collection_id="col_abc123",
table_id="tab_xyz789",
documents=[
{"id": "doc_001", "title": "Doc 1", "content": "...", "category": "tutorial"},
{"id": "doc_002", "title": "Doc 2", "content": "...", "category": "reference"},
{"id": "doc_003", "title": "Doc 3", "content": "...", "category": "tutorial"}
]
)
```
```typescript TypeScript theme={null}
import { ScoutClient } from "scoutos";
const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });
// Add a single document
await client.documents.create({
collectionId: "col_abc123",
tableId: "tab_xyz789",
documents: [{
id: "doc_001",
title: "Getting Started Guide",
content: "This comprehensive guide walks you through...",
url: "https://docs.example.com/getting-started",
category: "tutorial",
updatedAt: 1704067200
}]
});
// Add multiple documents
await client.documents.create({
collectionId: "col_abc123",
tableId: "tab_xyz789",
documents: [
{ id: "doc_001", title: "Doc 1", content: "...", category: "tutorial" },
{ id: "doc_002", title: "Doc 2", content: "...", category: "reference" },
{ id: "doc_003", title: "Doc 3", content: "...", category: "tutorial" }
]
});
```
### Via Workflow Blocks
Use the **Save Document to Table** block inside any Scout workflow:
1. Add the block to your workflow canvas.
2. Select the target Database and Table from the dropdowns.
3. Map workflow output values to the appropriate table columns.
4. Run the workflow — documents are upserted automatically.
## Document Structure
Every document follows this general shape:
```json theme={null}
{
"id": "unique_document_id",
"content": "Main searchable text that gets embedded...",
"title": "Document Title",
"category": "tutorial",
"url": "https://docs.example.com/my-article",
"updated_at": 1704067200
}
```
A unique identifier for the document. Used for upserts — if a document with this ID already exists, it is updated in place rather than duplicated.
The primary text body. This field is automatically chunked and embedded for semantic search. Write comprehensive, descriptive content here for the best retrieval quality.
A short label for the document. Returned in search results and displayed in the Scout UI.
Any custom metadata field. Metadata columns are used for filtering, sorting, and display — they are not embedded.
## Managing Tables
### View a Table's Schema
```bash theme={null}
curl https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id}/schema \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Rename a Table
```bash theme={null}
curl -X PATCH https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id} \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Updated Table Name"}'
```
### Delete a Table
Deleting a table permanently removes all documents and vector embeddings stored in it. This action cannot be undone.
```bash theme={null}
curl -X DELETE https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id} \
-H "Authorization: Bearer YOUR_API_KEY"
```
## Using Databases with Agents
Once your Database has data, agents can read from and write to it.
### 1. Enable Databases Tools
In your agent's **Tools** tab, enable the Databases tools to grant the agent permission to create and query documents.
### 2. Add an Instruction Snippet
Add the following to your agent's system prompt:
```markdown theme={null}
When creating or updating table records:
1. Validate the target database and table before writing.
2. Confirm required fields are present: id, content, and key metadata.
3. Use consistent values for taxonomy fields like category and status.
4. If data is incomplete, ask for missing fields before saving.
5. After writing, return the record IDs that were created or updated.
```
### 3. Prompt Examples
* "Create a `release_notes` record for version 2.8.0 with category `platform`."
* "Upsert these three customer call summaries into `customer_feedback`."
* "Check whether this document already exists by URL before creating a new row."
## Best Practices
* **Schema stability** — Avoid renaming columns after syncing data. Source mappings and workflow blocks reference columns by name; renames break those connections.
* **Use `id` for upserts** — Always supply a stable, unique `id` for each document so re-running ingestion doesn't create duplicates.
* **Content length** — Write comprehensive, descriptive text in the `content` field. Short or generic content produces weaker embeddings and lower-quality search results.
* **Timestamps** — Include `created_at` and `updated_at` as Number columns (Unix timestamps) so you can filter by date range in queries.
## Next Steps
Automate data ingestion from Notion, Google Sheets, and the web.
Search databases with semantic, keyword, and hybrid modes.
Understand the full Databases data model and when to use it.
# Sync Google Sheets into Scout Databases
Source: https://docs.scoutos.com/databases/google-sheets
Sync spreadsheet rows from Google Sheets into a Scout Database table. Map columns to fields, schedule syncs, and keep data current for agent retrieval.
The Google Sheets source syncs spreadsheet rows directly into a Scout table without rebuilding your data elsewhere. It's a good fit for structured lists that non-technical teams already maintain in a spreadsheet — CRM exports, content inventories, product catalogs, and similar data. Each row becomes a document, and your column headers map to table fields.
## Before You Start
* Create a Database and a destination table in Scout. See [Creating Databases](/databases/creating-databases).
* Make sure your sheet has a clear header row in **row 1** — Scout uses these headers as field names.
* Add table columns for the fields you want to search or filter on.
* Choose a stable identifier column (for example `ID`, `Slug`, or `URL`) before your first sync. Scout uses it to match and update existing rows; without one, every sync creates duplicates.
## Connect the Google Sheets Integration
Navigate to **Integrations** in Scout.
Find **Google Sheets** in the list and start the connection.
Sign in with your Google account and grant access to your spreadsheets.
Availability may vary by workspace during rollout.
## How Sync Works
Scout reads the sheet top to bottom, treating each row as a document:
* **New rows** become new documents.
* **Updated rows** are matched by your stable identifier and overwritten — an upsert. Without an identifier, updates create duplicates instead.
* **Deleted rows** aren't removed automatically. Re-run with full replacement if you need to clear them out.
Decide on a stable identifier column before your first sync. `ID`, `Slug`, and `URL` are common choices — anything that uniquely and consistently identifies a row.
## Create a Google Sheets Source
Navigate to the table you want to populate.
Click **Sources** → **Add Source**, then select **Google Sheets**.
Choose the spreadsheet and the specific worksheet or tab to sync.
Match each sheet column to a column in your table. See [Field Mapping](#field-mapping) below.
Optionally choose a schedule, or leave the source as manual-only.
Click **Create** to save the configuration.
## Field Mapping
Map your sheet headers to table column names. A typical content-inventory mapping looks like this:
| Sheet header | Table column | Notes |
| -------------- | ------------ | ---------------------------- |
| `Title` | `title` | Used in search results |
| `Page URL` | `url` | Links back to the source |
| `Summary` | `content` | Main text for retrieval |
| `Last Updated` | `updated_at` | Helps with freshness ranking |
| `Owner Team` | `team` | Useful for filtering |
Map your main text to the `content` column. Scout embeds this field for semantic search, so retrieval quality depends on it being mapped correctly.
Start with a small subset of columns and expand once you've validated data quality.
## Run and Validate
Trigger a manual run from the Sources panel.
Confirm the expected documents appear in your table.
Check a few rows for correct types and formatting.
Run a query to confirm retrieval quality. See [Querying Data](/databases/querying-data).
## Common Issues
Confirm the header row exists in row 1, recheck your field mapping, and make sure column types match the shape of the data.
Add a stable identifier column before re-syncing. Without one, each sync creates new documents instead of updating existing ones.
Review your sync strategy — full replacement versus incremental — and re-run after any major schema changes.
Reconnect with the correct Google account and verify you have at least view access to the spreadsheet.
## Best Practices
* **Keep header names consistent.** Renaming a header breaks the mapping until you update the source config.
* **Use an explicit table schema** rather than syncing every column in the sheet.
* **Schedule syncs only for sheets that change often.** Run manually for one-time imports.
* **Add metadata columns** like `team`, `status`, or `region` to support downstream filtering.
Renaming a mapped sheet header or table column breaks the field mapping for that field. The column stays empty on subsequent syncs until you update the mapping.
## Next Steps
Compare all source types and their sync options.
Search synced data with semantic and hybrid search.
Design schemas for reliable ingestion.
# Sync Notion to Scout Databases for Agent Search
Source: https://docs.scoutos.com/databases/notion
Connect Notion and sync workspace pages and databases into a Scout Database. Keep runbooks, handbooks, and internal docs searchable by your agents.
Notion is where many teams keep their living knowledge — runbooks, product specs, onboarding guides, meeting notes, and employee handbooks. The Notion source imports that content into a Scout Database so your agents can search it by meaning and surface the right answer mid-conversation. Set it up once and Scout keeps the table current as pages change.
**Common use cases:**
* An **HR bot** that answers employee questions straight from the handbook
* A **support agent** that surfaces internal docs while helping a customer
* A **knowledge base** that stays current automatically as the team edits Notion
## Before You Start
Set up the destination before connecting Notion:
1. Create a **Database** and a destination **Table**. See [Creating Databases](/databases/creating-databases).
2. Add these columns to the table:
| Column | Type |
| --------- | ---------------- |
| `title` | Single Line Text |
| `url` | URL |
| `content` | Multi Line Text |
3. Identify the Notion pages or databases you want to sync.
Store the main body text in a column named `content`. Scout automatically chunks and embeds this field for semantic search — if body text lands anywhere else, retrieval won't work as expected.
## Connect the Notion Integration
Go to **Integrations** in the Scout dashboard and find Notion in the list.
Click **Connect** next to Notion to start the OAuth flow.
In the Notion authorization screen, select the workspace and grant access to the specific pages and databases you want Scout to read.
Keep permissions scoped narrowly at first — grant only the pages you intend to sync, then expand access later as your needs grow.
## Create a Notion Source
Navigate to **Databases**, open your Database, and select the destination table.
Click the **Sources** tab, then **Add Source**, and select **Notion**.
Select the Notion integration you connected above.
Match the Notion fields to your table columns. See [Recommended Field Mapping](#recommended-field-mapping) below.
Optionally choose a schedule, or leave the source as manual-only.
Click **Create** to save the source. You can run the first sync immediately.
## Recommended Field Mapping
| Notion Field | Table Column | Type |
| ---------------- | ------------ | ---------------- |
| Page title | `title` | Single Line Text |
| Page URL | `url` | URL |
| Body / content | `content` | Multi Line Text |
| Last edited time | `updated_at` | Datetime |
Keep these mappings consistent across every table that uses a Notion source. Consistent schemas make queries and metadata filters predictable across your Databases.
## What Gets Synced
**Syncs well:**
* Rich text blocks — paragraphs, headings, bullet lists, toggles, and callouts
* Inline tables
* Database rows and their properties
**Doesn't sync:**
* Embedded files and attachments (PDFs, images, videos)
* Inline databases (extracted as text, not as structured data)
* Linked page previews (not followed)
**Nested pages.** Scout syncs only the pages you've granted access to and does not auto-crawl into nested child pages unless those are also explicitly granted. For deeply nested structures, grant access at a high enough level to cover everything you want synced.
## Run and Validate
Trigger the initial sync from the Sources panel and watch it complete.
Open a few synced rows and confirm the `content` column holds actual body text — not just the page title.
Run a semantic query against the table to confirm retrieval quality. See [Querying Data](/databases/querying-data).
An empty `content` field almost always means a mapping issue. Confirm the Notion body text is mapped to the `content` column and re-run the sync.
## Common Issues
| Symptom | What to Check |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Missing pages** | Recheck the granted pages in Notion. Permission changes can take a few minutes to propagate — wait and re-run the sync. |
| **Empty or thin content** | Confirm the page has real text rather than only embeds or attachments, and that body content maps to `content`. |
| **Data looks outdated** | Enable a sync schedule for automatic re-syncs, or re-run manually after major edits. |
| **Visible in Notion but missing from Scout** | Nested child pages need explicit access grants. Databases need their own integration grant, separate from the parent page. |
## Best Practices
* **Start small.** Sync one Notion section, validate content quality and retrieval, then expand.
* **Keep mappings consistent.** Use the same column mappings across every table backed by a Notion source.
* **Schedule only what changes.** Use a scheduled sync for frequently edited docs; skip it for static archives.
* **Scope with metadata.** Pair Notion content with metadata filters in your queries to narrow results to a specific section or topic.
## Next Steps
Compare all source types and sync options.
Search synced content with semantic, keyword, and hybrid search.
Design your table schema before configuring a source.
# Databases
Source: https://docs.scoutos.com/databases/overview
Scout Databases store structured records with automatic embeddings for semantic search. Use them for RAG apps, knowledge bases, and agent data retrieval.
Scout Databases are the primary way to store, search, and retrieve information for your AI agents. Every piece of text you add to a Database is automatically embedded and indexed, so agents can find the most relevant content by meaning — not just by matching exact words. Whether you're building a customer support chatbot, a documentation assistant, or an internal knowledge base, Databases give your agents the data retrieval layer they need.
## What Are Databases?
A **Database** is a container made up of one or more **Tables**. Each Table holds **Documents** — structured records that combine metadata fields (like title, category, or a timestamp) with a text body that gets automatically embedded for semantic search.
```text theme={null}
Database
├── Table 1
│ ├── Document 1 (metadata + text)
│ ├── Document 2 (metadata + text)
│ └── ...
├── Table 2
│ └── ...
└── Sources (sync integrations)
```
For example, a customer support team might have a **Help Center** database with two tables: `FAQs` and `Troubleshooting Guides`. Each document in `FAQs` could have a `category` column, a `last_updated` timestamp, and a text body containing the answer. Agents can search across both tables at once or scope their query to a single table.
## Search Modes
Databases support three distinct search modes. You choose the right one based on the kind of query you expect.
| Mode | How It Works | Best For |
| --------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Semantic (Vector)** | Converts your query to an embedding and finds documents with similar vectors | Natural language questions, finding related concepts |
| **Keyword (BM25)** | Matches exact keywords using traditional full-text search | Product codes, SKUs, technical identifiers |
| **Hybrid** | Fuses semantic and keyword results using Reciprocal Rank Fusion (RRF) | General-purpose production search |
### Semantic Search
Semantic search finds relevant content even when the user's words don't appear verbatim in the document. A query for `"how do I reset my password"` can surface documents about `"account recovery"` or `"login troubleshooting"` because the embeddings capture meaning, not just terms.
### Keyword Search
Keyword search uses BM25 to find documents containing exact keyword matches. Use it when precision matters — for example, when users search for a specific error code like `ERR_CERT_AUTHORITY_INVALID`.
### Hybrid Search
Hybrid search combines both approaches using Reciprocal Rank Fusion. Results from the semantic pass and the keyword pass are merged and re-ranked, so you get the precision of keyword matching alongside the conceptual coverage of vector search. **For most production applications, hybrid search is the recommended default.**
## Databases vs. Drive
Scout offers two storage systems. Use this table to pick the right one for your use case.
| Feature | Databases & Tables | Drive |
| ------------- | ----------------------------------- | -------------------------------------- |
| **Purpose** | Structured data with vector search | Raw file storage (PDFs, images, docs) |
| **Search** | Semantic, keyword, or hybrid | By path or filename |
| **Use Case** | RAG, knowledge bases, CRM data | Assets, attachments, generated outputs |
| **AI Access** | Agents search by meaning | Agents read and write files directly |
| **Sync** | Notion, Google Sheets, web scraping | Manual upload or agent writes |
### When to Use Databases
Choose Databases when your agents need to find information by meaning:
* Building a chatbot that answers questions from your internal docs (RAG)
* Creating a searchable knowledge repository for support or onboarding
* Storing and querying customer or CRM records
* Surfacing content by concept rather than exact path
### When to Use Drive
Choose Drive when your agents need raw file access:
* Storing PDFs, images, and other binary assets
* Saving generated reports and workflow outputs
* Passing files between workflow steps
* Reading files by exact path without semantic querying
## Quick Start
Get up and running with Databases in four steps.
1. Navigate to **Databases** in the Scout dashboard.
2. Click **+ New** at the top of the page.
3. Enter a name and optional description.
4. Click **Create**.
Scout provisions and indexes your Database automatically. This takes about 30 seconds and the UI shows the current status while it's setting up.
Every new Database comes with an `Untitled` table. Rename it and add columns to match your data:
1. Click the **+** button in the table header row.
2. Enter a column name and select a type: `Single Line Text`, `Multi Line Text`, `Number`, `Checkbox`, or `URL`.
3. Repeat for each field your documents need.
Store your main searchable text in a column named `content` — Scout automatically chunks and embeds this field for semantic search.
Add documents via the REST API or Python SDK.
```bash cURL theme={null}
curl -X POST https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id}/documents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"documents": [{
"id": "doc_1",
"text": "Your searchable content here...",
"title": "Document Title",
"category": "documentation"
}]
}'
```
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
client.documents.create(
collection_id="col_abc123",
table_id="tab_xyz789",
documents=[{
"id": "doc_1",
"text": "Your searchable content here...",
"title": "Document Title",
"category": "documentation"
}]
)
```
Search your database from a workflow or directly via the API.
**In a Workflow**, add a **Query Database Table** block and configure it:
```yaml theme={null}
Search Term: "{{inputs.user_question}}"
Minimum Similarity: 0.5
Hybrid Search: true
Limit: 10
```
**Via the API:**
```bash theme={null}
curl -X POST https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id}/query \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"search_term": "customer support",
"min_similarity": 0.5,
"limit": 10
}'
```
## Using Databases with Agents
Give your agents the ability to read from and write to Databases by following these two steps.
### 1. Enable Databases Tools
Open your agent in Scout, go to the **Tools** tab, and enable the Databases tools. This grants the agent permission to query tables and create or update documents.
### 2. Add an Instruction Snippet
Add the following to your agent's system prompt to guide its retrieval behavior:
```markdown theme={null}
When a task depends on organizational knowledge or structured records:
1. Query Databases first.
2. Prefer hybrid search for broad user questions.
3. Use metadata filters when the user specifies a category, date, or status.
4. If information is missing and the user provided new facts, write the new record
to the correct table.
5. In your reply, clearly distinguish between retrieved data and newly added data.
```
### Prompt Examples
* "Search our support knowledge base for account recovery steps and summarize the answer."
* "Find onboarding docs updated in the last 30 days and return only security-related items."
* "Add this meeting note to the `customer_feedback` table with category `enterprise`."
### Expected Agent Behavior
When configured correctly, your agent will:
* Query the correct table before formulating an answer
* Apply metadata filters when the user's request includes constraints like category or date
* Write records only when explicitly asked or when your instructions allow it
* Cite which data came from Databases in its final response
## Next Steps
Create databases, configure table schemas, and populate data via the UI or API.
Sync data automatically from Notion, Google Sheets, websites, and more.
Master semantic search, hybrid search, and advanced metadata filtering.
# Querying Scout Databases: Semantic and Hybrid Search
Source: https://docs.scoutos.com/databases/querying-data
Search Scout Databases using semantic or hybrid mode. Filter by metadata and tune similarity thresholds for precise agent data retrieval.
Querying is where Databases pay off. You've stored your documents, your embeddings are built, and now your agents and workflows need to retrieve the right information at the right time. Scout gives you three search modes — semantic, keyword, and hybrid — along with metadata filters and tunable thresholds so you can dial in exactly the results you need.
## Query Modes
| Mode | How It Works | Best For |
| --------------------- | ---------------------------------------------------------------------------- | -------------------------------------------- |
| **Semantic (Vector)** | Converts your query to an embedding and finds documents with similar vectors | Natural language questions, related concepts |
| **Keyword (BM25)** | Matches exact keywords using traditional full-text search | Product codes, SKUs, technical identifiers |
| **Hybrid** | Fuses both result sets using Reciprocal Rank Fusion (RRF) | General-purpose production search |
### Semantic Search
Semantic search converts your query into a vector embedding and returns documents whose embeddings are closest in vector space. It finds relevant content even when the user's words don't appear verbatim in the document.
```yaml theme={null}
Query: "how do I reset my password"
Finds: Documents about "password recovery", "account access", "login issues"
```
Use semantic search for conversational interfaces, synonym-rich content, and queries where users express intent in their own words.
### Keyword Search (BM25)
Keyword search uses the BM25 algorithm to find documents containing exact keyword matches. It's the same mechanism behind traditional full-text search.
```yaml theme={null}
Query: "API_KEY_12345"
Finds: Only documents containing "API_KEY_12345" exactly
```
Use keyword search when users search for specific identifiers, error codes, product names, or other terms where exact matching matters more than semantic similarity.
### Hybrid Search
Hybrid search runs both a semantic pass and a keyword pass, then merges and re-ranks the results using Reciprocal Rank Fusion (RRF). You get the precision of keyword matching alongside the conceptual coverage of vector search in a single ranked result set.
```yaml theme={null}
Query: "React hooks tutorial"
Finds:
- Documents with "React", "hooks", "tutorial" (keyword match)
- Documents about "state management in React" (semantic match)
```
**Hybrid search is the recommended default for most production applications.** It handles mixed query styles — proper nouns blended with natural language — better than either mode alone.
## Query Parameters
The query string. In workflow blocks this supports Jinja templating, for example `{{inputs.user_question}}`.
Minimum relevance threshold. Results below this score are excluded. Range is `0.0` to `1.0`. See [Tuning min\_similarity](#tuning-min_similarity) for guidance.
Maximum number of results to return.
When `true`, enables hybrid mode — results from semantic and keyword passes are fused using RRF.
Controls the balance between semantic and keyword search in hybrid mode. `0.0` = pure keyword, `1.0` = pure semantic. Ignored when `hybrid_search` is `false`.
Filter results by metadata column values. See [Filtering by Metadata](#filtering-by-metadata) for the full syntax.
## Querying via Workflow Blocks
Add a **Query Database Table** block to any workflow to search your data at runtime.
### Configuration
| Parameter | Description | Default |
| ---------------------- | --------------------------------------- | -------- |
| **Database** | The Database to query | Required |
| **Table** | The Table within the Database | Required |
| **Search Term** | Query string; supports Jinja templating | Required |
| **Minimum Similarity** | Relevance threshold (0–1) | `0.35` |
| **Hybrid Search** | Enable RRF fusion | `false` |
| **Alpha** | Semantic vs. keyword balance (0–1) | `0.5` |
| **Filters** | Metadata filter expression | Optional |
| **Limit** | Max results to return | `10` |
### Example Block Configuration
```yaml theme={null}
Database: Knowledge Base
Table: Documentation
Search Term: "{{inputs.user_question}}"
Minimum Similarity: 0.5
Hybrid Search: true
Alpha: 0.5
Limit: 10
```
### Working with Query Results
The block returns an array of result objects. Each result contains a `details` object with relevance scores and a `record` object with the document's fields:
```json theme={null}
[
{
"details": {
"vector_distance": 0.15,
"hybrid_score": 0.87
},
"record": {
"id": "doc_abc123",
"attributes": {
"title": "Getting Started Guide",
"content": "This guide walks you through...",
"category": "tutorial",
"url": "https://docs.example.com/getting-started"
}
}
}
]
```
Distance from the query in vector space. Lower values indicate higher similarity. `0.0` is identical; `1.0` is completely unrelated. Present on all results.
Fused relevance score when `hybrid_search: true`. Higher is better. `null` for pure semantic queries.
The unique document identifier.
All metadata fields stored on the document, keyed by column name.
Access results in downstream blocks with Jinja:
```jinja2 theme={null}
{{ query_results.output[0].record.attributes.title }}
```
Handle empty results gracefully:
```jinja2 theme={null}
{% if query_results.output | length > 0 %}
{{ query_results.output[0].record.attributes.content }}
{% else %}
I couldn't find anything relevant. Try rephrasing your question.
{% endif %}
```
## Querying via API
### Basic Semantic Query
```bash theme={null}
curl -X POST https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id}/query \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"search_term": "customer support",
"min_similarity": 0.5,
"limit": 10
}'
```
### Hybrid Search Query
```bash theme={null}
curl -X POST https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id}/query \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"search_term": "React hooks tutorial",
"min_similarity": 0.5,
"hybrid_search": true,
"alpha": 0.5,
"limit": 10
}'
```
### Using the Python SDK
```python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
results = client.tables.query(
collection_id="col_abc123",
table_id="tab_xyz789",
search_term="customer support",
min_similarity=0.5,
hybrid_search=True,
limit=10
)
for result in results:
print(f"Title: {result['record']['attributes']['title']}")
print(f"Distance: {result['details']['vector_distance']}")
```
### Using the TypeScript SDK
```typescript theme={null}
import { ScoutClient } from "scoutos";
const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });
const results = await client.tables.query({
collectionId: "col_abc123",
tableId: "tab_xyz789",
searchTerm: "customer support",
minSimilarity: 0.5,
hybridSearch: true,
limit: 10
});
results.forEach(result => {
console.log(`Title: ${result.record.attributes.title}`);
console.log(`Score: ${result.details.hybrid_score}`);
});
```
## Filtering by Metadata
Metadata filters let you narrow results using column values before or after the similarity ranking step. Filters use a JSON array with the format `["column_id", "operator", "value"]`.
### Available Operators
| Operator | Description | Example |
| -------- | -------------------------------- | ---------------------------------------------- |
| `Eq` | Equal to | `["status", "Eq", "active"]` |
| `NotEq` | Not equal to | `["status", "NotEq", "archived"]` |
| `In` | Value is in a list | `["category", "In", ["tutorial", "guide"]]` |
| `NotIn` | Value is not in a list | `["category", "NotIn", ["draft", "archived"]]` |
| `Gt` | Greater than | `["price", "Gt", 50]` |
| `Gte` | Greater than or equal | `["views", "Gte", 1000]` |
| `Lt` | Less than | `["created_at", "Lt", 1704067200]` |
| `Lte` | Less than or equal | `["stock", "Lte", 10]` |
| `Glob` | Pattern match (case-sensitive) | `["url", "Glob", "*/docs/*"]` |
| `IGlob` | Pattern match (case-insensitive) | `["title", "IGlob", "*quick start*"]` |
| `And` | All sub-filters must match | `["And", [[...], [...]]]` |
| `Or` | Any sub-filter must match | `["Or", [[...], [...]]]` |
### Filter Examples
**Single column filter:**
```json theme={null}
["category", "Eq", "tutorial"]
```
**Date range:**
```json theme={null}
["And", [
["created_at", "Gte", 1672531200],
["created_at", "Lte", 1704067200]
]]
```
**Multiple categories:**
```json theme={null}
["category", "In", ["tutorial", "guide", "reference"]]
```
**Case-insensitive title match:**
```json theme={null}
["title", "IGlob", "*getting started*"]
```
**Combined conditions:**
```json theme={null}
["And", [
["category", "Eq", "tutorial"],
["difficulty", "In", ["beginner", "intermediate"]],
["created_at", "Gte", 1704067200]
]]
```
### Using Filters in Workflow Blocks
Apply filters dynamically with Jinja templating:
```yaml theme={null}
Filters: ["category", "Eq", "{{inputs.category}}"]
```
For conditional filter logic:
```jinja2 theme={null}
{% if inputs.show_archived %}
["category", "Eq", "{{inputs.category}}"]
{% else %}
["And", [["category", "Eq", "{{inputs.category}}"], ["status", "NotEq", "archived"]]]
{% endif %}
```
## Tuning min\_similarity
The `min_similarity` threshold cuts off results below a relevance score. Start with `0.5` and adjust based on what you observe.
| Value Range | Behavior |
| ----------- | ----------------------------------------------------- |
| `0.0 – 0.4` | Broad — includes marginal and loosely related matches |
| `0.5 – 0.7` | Balanced — good default for most knowledge bases |
| `0.8 – 1.0` | Strict — only highly relevant, near-exact matches |
**Practical guidance:**
* Use `0.3–0.4` for exploratory search or content discovery.
* Use `0.5–0.6` as a general-purpose default for production.
* Use `0.7–0.8` for technical documentation where precision matters.
* Use `0.8+` when you need near-exact semantic matches.
## Tuning Alpha (Hybrid Mode)
The `alpha` parameter shifts the balance between semantic and keyword scoring in hybrid mode.
| Alpha | Behavior |
| ----- | -------------------------------------- |
| `0.0` | Pure keyword (BM25 only) |
| `0.3` | Mostly keyword with a semantic boost |
| `0.5` | Balanced — the recommended default |
| `0.7` | Mostly semantic with keyword precision |
| `1.0` | Pure semantic |
**When to adjust:**
* Lower alpha (`0.2–0.4`) for technical docs with specific identifiers and exact terms.
* Medium alpha (`0.5`) for general knowledge bases — start here.
* Higher alpha (`0.7–0.9`) for natural language conversations and content discovery.
## Using Databases with Agents
### 1. Enable Databases Tools
In your agent's **Tools** tab, enable the Databases query capability.
### 2. Add an Instruction Snippet
```markdown theme={null}
For questions that require internal knowledge:
1. Query Databases before answering.
2. Start with hybrid search using min_similarity: 0.5 and alpha: 0.5.
3. If results are noisy, increase min_similarity.
4. If the user gives constraints like category, date, or status, apply metadata filters.
5. Return a concise answer, then include the key supporting records.
```
### 3. Prompt Examples
* "Find troubleshooting steps for SSO login failures from the IT docs table."
* "Search only `category = policy` and summarize PTO policy changes since Jan. 1."
* "Query the sales enablement table for pricing objection handling and give me three approved responses."
## Common Query Patterns
### Find Similar Documents
```json theme={null}
{
"search_term": "{{document.content}}",
"min_similarity": 0.7,
"limit": 5
}
```
### Recent Tutorials Only
```json theme={null}
{
"search_term": "{{user_query}}",
"filters": ["And", [
["category", "Eq", "tutorial"],
["created_at", "Gte", 1704067200]
]],
"limit": 10
}
```
### Exclude Drafts
```json theme={null}
{
"search_term": "{{user_query}}",
"filters": ["status", "NotEq", "draft"],
"limit": 10
}
```
### Multi-Category Hybrid Search
```json theme={null}
{
"search_term": "{{user_query}}",
"hybrid_search": true,
"filters": ["category", "In", ["tutorial", "guide", "reference"]],
"limit": 15
}
```
## Troubleshooting
**Getting no results**
* Lower `min_similarity` — try `0.3` to cast a wider net.
* Confirm your table has indexed documents by checking the row count in Scout Studio.
* Try a simple, general search term to confirm the data is reachable.
* Temporarily remove filters to check whether a filter condition is too restrictive.
**Too many irrelevant results**
* Raise `min_similarity` to `0.6` or higher.
* Add metadata filters to scope results to the right category or status.
* Lower `alpha` toward `0.3` if your query uses specific terms that should match exactly.
**Missing an obvious match**
* Confirm the document is in the correct table.
* Check for typos in filter values — `Eq` and `In` operators are case-sensitive. Use `IGlob` for case-insensitive text matching.
* Try hybrid search if you've been using semantic-only.
* Re-sync your data source if the record was added recently and may not be indexed yet.
**Low scores on relevant results**
`vector_distance` values above `0.5` generally indicate weak semantic alignment. This often means:
* Your query phrasing doesn't match how the content is written.
* The content is too short or generic to embed well.
* Consider enriching your documents with more descriptive text and re-syncing.
## Best Practices
1. **Start with defaults** — `min_similarity: 0.5`, `hybrid_search: true`, `alpha: 0.5`. Adjust from there based on observed results.
2. **Prefer hybrid search** — it outperforms pure semantic or pure keyword for the vast majority of real-world queries.
3. **Use metadata filters** — scoping to category, date, or status dramatically improves precision without sacrificing recall within the relevant subset.
4. **Write rich content** — comprehensive, descriptive text in the `content` field produces better embeddings and more accurate retrieval.
5. **Test with real queries** — use actual user questions (not synthetic ones) to tune thresholds and filter configurations.
## Next Steps
Understand the Databases data model and when to use it.
Set up schemas optimized for search quality.
Keep database data fresh with automated syncs.
# Database Sources: Sync Data from Notion, Sheets, and More
Source: https://docs.scoutos.com/databases/sources
Automatically sync Scout Databases from websites, Notion, Google Sheets, Google Drive, and Microsoft 365. Set up once and keep your agent data current.
Sources eliminate the manual work of keeping your Databases current. Instead of re-uploading content every time your documentation updates or your spreadsheet changes, you configure a Source once and Scout handles ingestion automatically — on a schedule or whenever you trigger a manual run. This is the recommended approach for any Database that powers a live agent.
## What Sources Do
Each Source runs a sync job that:
1. Pulls content from an external system using your configured credentials and settings.
2. Maps the incoming fields to the columns in your destination table.
3. Creates new documents or updates existing ones — an **upsert** based on each item's unique source identifier.
Sources are non-destructive by default: items removed from the source are **not** automatically deleted from your table. If you want your table to mirror the source exactly, clear the table contents and trigger a fresh sync.
Scout deduplicates by matching the source item's unique identifier — the URL for web pages, the row ID for spreadsheet rows, the page ID for Notion. Running the same sync twice does not create duplicate records.
## Supported Sources
Scout supports a broad set of integrations so you can pull data from wherever your content already lives.
Crawl a website starting from a single URL. Scout follows internal links up to a configurable depth and extracts page content automatically.
Provide an XML sitemap URL and Scout fetches every listed page. Ideal for documentation portals with an existing sitemap.
Sync Notion pages and databases. Connect via OAuth or an integration token and select the pages or database records to include.
Sync rows from a Google Sheets spreadsheet. Each row becomes a document; column headers map to table fields.
Pull documents and files directly from a Google Drive folder. Supports Docs, Sheets, and PDF files.
Connect a Microsoft 365 tenant and sync content from SharePoint sites, document libraries, or Teams wikis.
Sync files from a personal or business OneDrive account. Supports Word documents, PDFs, and text files.
Pull documents from a Laserfiche repository into a Scout Database for AI-powered search and retrieval.
## How Syncs Work
When a sync runs, Scout compares the incoming data against what is already in your table:
* **New items** become new documents, embedded and indexed immediately.
* **Existing items** are updated in place — the document is overwritten using its source ID as the match key.
* **Items removed from the source** are left in the table unchanged. Delete them manually if your use case requires exact mirroring.
Running the same sync twice is safe. Scout deduplicates on the source item's unique identifier (URL, row ID, page ID), so repeated runs do not create duplicate documents.
## Configuring a Source
Navigate to Databases in Scout, open the Database you want to populate, and click the target Table.
Click the **Sources** tab at the top of the table view.
Click **Add Source** and choose the source type from the list of integrations.
Complete the OAuth flow or paste your credentials for the chosen integration. Then configure source-specific settings such as:
* **Web Scraping** — starting URL, crawl depth, URL filters
* **Sitemap** — sitemap URL
* **Notion** — database or page selector
* **Google Sheets** — spreadsheet ID and sheet name
* **SharePoint / OneDrive** — tenant, site, and library
Review the field mapping screen. Match the incoming fields from the source to your table's columns. See [Source Mapping](#source-mapping) below for guidance.
Choose a schedule or leave it as manual-only. See [Sync Frequency](#sync-frequency) for recommendations.
Click **Run Now** to trigger the initial ingestion. Scout fetches the data, maps it, and populates the table. Watch the progress in the Sources panel.
## Source Mapping
Each source produces different fields. During setup you map those fields to columns in your table. Common mappings:
| Source Field | Maps To | Notes |
| -------------------- | --------------------------- | --------------------------------------------------------- |
| `title` | `title` (Single Line Text) | Article or page title |
| `body` / `content` | `content` (Multi Line Text) | Main searchable text — must be mapped here for embeddings |
| `url` / `source_url` | `url` (URL) | Original URL for attribution |
| `last_modified` | `updated_at` (Number) | Unix timestamp of the last change |
Always map the main body text to your `content` column. This is the field Scout embeds for semantic search. If you map it to a different column, vector search won't work as expected.
If the source doesn't include a field your table expects, that column remains empty for synced documents. You can fill the gap manually afterward or combine a second Source that covers the missing data.
## Sync Frequency
| Schedule | When to Use |
| --------------- | --------------------------------------------------------------------------- |
| **Manual only** | Static content that rarely changes — a one-time import of archived articles |
| **Hourly** | Live support docs or spreadsheets that update throughout the day |
| **Daily** | Documentation portals or Notion wikis updated a few times a week |
| **Weekly** | Reference content that changes infrequently |
Use scheduled syncs only for content where freshness actually matters. Unnecessary syncs consume ingestion quota and slow down other operations.
## Triggering a Manual Sync
You can re-run any Source at any time without waiting for the scheduled window:
1. Open the **Sources** panel for your table.
2. Find the Source you want to run.
3. Click **Run Now**.
Scout queues the job immediately. Progress and any errors appear in the sync history log.
## Monitoring Sync Status
The **Sources** panel shows the current and historical state of every sync job:
| Status | Meaning |
| ------------- | ------------------------------------------------------------------------- |
| **Running** | The sync is actively fetching and ingesting data. |
| **Completed** | The sync finished successfully. The timestamp and record count are shown. |
| **Failed** | The sync encountered an error. Open the error log to see details. |
| **Scheduled** | The sync is queued for the next scheduled window. |
From the Sources panel you can:
* View run history and record counts
* Inspect error messages and stack traces for failed runs
* Edit source credentials or mapping configuration
* Re-run failed or completed jobs
### Common Failure Causes
* **Permission changes** — The OAuth token or integration key was revoked. Re-authenticate the source.
* **Changed URLs** — The starting URL or sitemap location moved. Update the source configuration.
* **Rate limits** — The external system throttled Scout's requests. Re-run the sync after a short wait.
* **Mapping drift** — A column was renamed after the source was configured. Update the field mapping to match the new column name.
Renaming a table column after configuring a Source breaks the field mapping for that column. The column stays empty on subsequent syncs until you update the mapping to reference the new column name.
## Best Practices
* **Start small.** Test a Source on a subset of content before running a full ingestion. Create a temporary table, sync a sample, and verify field mapping and content quality before pointing the source at your production table.
* **Keep column names stable.** Schema changes after a sync are disruptive. Design your columns up front and avoid renames.
* **Schedule only what needs freshness.** For static content, a one-time manual sync is sufficient and uses fewer resources.
* **Review failures quickly.** Mapping drift and revoked credentials are the most common failure modes. Check the Sources panel regularly and fix issues before they go unnoticed for multiple sync cycles.
* **Use the `content` column.** Always map the primary text body to a column named `content` so Scout's automatic embedding pipeline picks it up correctly.
## Next Steps
Design your table schema before configuring a Source.
Search synced content with semantic, keyword, and hybrid modes.
Understand the full Databases model and when to use it.
# Web Scraping: Sync Public Web Content into Scout Databases
Source: https://docs.scoutos.com/databases/web-scraping
Pull public website content into a Scout Database for semantic search and RAG. Scrape a single page, crawl a site, or ingest a sitemap on a schedule.
Web scraping lets you ingest public web content directly into a Scout Database so your agents can search and reason over it. Use it to keep agents current with content that lives on the web — competitor sites, news, product pages, and external documentation. Each scraped page becomes a document that is embedded and indexed alongside the rest of your Database data.
Create a [Database](/databases/creating-databases) with at least one Table before setting up a web scraping Source. Scraped pages are written as documents into the Table you select.
## Types of Web Scrapes
Scout offers three ways to scrape content, each suited to a different scope.
Scrape one page by its URL. Best for one-off pages, specific articles, and individual documentation pages — for example importing a single blog post or product page.
Start from a URL and automatically follow internal links across the site, respecting `robots.txt`. Best for complete sites, documentation portals, and knowledge bases.
Parse a sitemap URL and scrape the pages it lists. Best for large sites with an organized sitemap where you want precise control over which pages are ingested.
## Setting Up a Web Scrape
Set up a [Database](/databases/creating-databases) and a Table to hold the scraped content. Make sure the Table has a `content` column so extracted text is embedded for semantic search.
Open your Database, select the target Table, and go to the **Sources** tab. Click **Add Source** and choose **Web Scrape**.
Enter the **URL** and choose your scrape type and options. A few common configurations:
**Single page**
```
URL: https://docs.scoutos.com/docs/overview
Scraper: Http
Text Extractor: Readability
```
**Full site crawl**
```
URL: https://docs.scoutos.com
Scraper: Http
Max Depth: 3
Max Page Count: 500
Exclude Patterns: /api/, /changelog/
```
**Sitemap**
```
URL: https://docs.scoutos.com/sitemap.xml
Scraper: Http
Text Extractor: Readability
```
Click **Run Now** to start ingestion. The dashboard reports pages discovered, pages scraped, errors encountered, and an estimated time to completion.
## Configuration Options
### Basic Settings
| Setting | Default | Description |
| -------------------- | ------------- | ------------------------------------------------------- |
| **URL** *(required)* | — | The full URL to scrape, crawl, or the sitemap to parse. |
| **Scraper** | `Http` | How pages are fetched — `Http` or `Playwright`. |
| **Text Extractor** | `Readability` | How the main content is extracted from each page. |
### Scraper Options
| Scraper | Best For | Trade-offs |
| -------------- | --------------------------------------------- | --------------------------------------------------------------------------------- |
| **Http** | Static pages and server-rendered HTML | Fast, but struggles with single-page apps (SPAs) and JavaScript-rendered content. |
| **Playwright** | SPAs and dynamic, JavaScript-rendered content | Renders the page in a browser before extracting, so it is slower. |
Start with the **Http** scraper. The most common cause of empty results is a JavaScript-rendered site being scraped with Http — if pages come back empty, switch to **Playwright**.
### Text Extractor Options
| Extractor | Description | Best For |
| --------------- | ------------------------------------------------------------------------- | ------------------------------------- |
| **Readability** | Scout's smart extraction that removes navigation, ads, and other clutter. | Documentation and most general pages. |
| **Trafilatura** | A Python-based extractor focused on the main body content. | News articles and blog posts. |
### Advanced Settings
| Setting | Default | Description |
| -------------------- | ------------- | -------------------------------------------------------------------- |
| **Allow** | (none) | Comma-separated URL patterns to include. |
| **Deny** | (none) | Comma-separated URL patterns to exclude. |
| **Exclude Patterns** | (none) | Regex patterns to exclude matching URLs. |
| **Strip** | (none) | Comma-separated HTML tags to remove before extraction. |
| **Strip URLs** | `true` | Remove URLs from the extracted text. |
| **Allowed Domains** | Source domain | Domains the crawler is permitted to follow links into. |
| **Max Depth** | `5` | How many link levels deep a crawl will follow from the starting URL. |
| **Max Page Count** | `3000` | The maximum number of pages a single scrape will ingest. |
## Monitoring a Scrape
Track running and completed scrapes from the **Sources** tab. For each scrape you can see:
| Field | Meaning |
| ------------ | ------------------------------------------------------- |
| **Status** | Whether the scrape is running, completed, or failed. |
| **Progress** | Pages discovered versus pages scraped. |
| **Errors** | Pages that could not be fetched or extracted. |
| **Duration** | How long the scrape has been running or took to finish. |
Open a scrape to view detailed logs and per-page results, including which URLs succeeded and which returned errors.
## Results
Each scraped page becomes a separate document in your Table. The extracted text is embedded and indexed for semantic search, and page metadata such as the URL and title is preserved for filtering and attribution.
```json theme={null}
{
"id": "doc_abc123",
"text": "Extracted content from the web page...",
"metadata": {
"url": "https://example.com/page",
"title": "Page Title",
"scraped_at": "2025-02-26T10:00:00Z"
}
}
```
Scout deduplicates scraped pages by URL. Re-running a scrape updates existing documents in place rather than creating duplicates, so you can refresh content on a schedule without bloating your Table.
## Best Practices
* **Optimize scope.** Start with a low **Max Depth**, exclude paths you don't need with **Deny** and **Exclude Patterns**, and set a **Max Page Count** so a crawl can't run away.
* **Choose the right scraper.** Use **Http** for static sites and **Playwright** only when content is JavaScript-rendered — Http is significantly faster.
* **Match the extractor to the content.** **Readability** works best for documentation; **Trafilatura** is better for news and blogs. Use **Strip** to remove unwanted elements.
* **Batch large sites.** For big sites, scrape from a sitemap rather than a deep crawl for more predictable coverage, and exclude media-heavy paths. Scout handles rate limiting automatically.
## Troubleshooting
The site is likely JavaScript-rendered. Switch the **Scraper** from Http to **Playwright**. Also confirm the page is publicly accessible and doesn't require authentication.
Narrow the scope with **Deny** and **Exclude Patterns**, lower **Max Depth**, or switch to a **Sitemap** scrape for precise control over which pages are included.
Use the **Http** scraper instead of Playwright where possible, reduce **Max Depth**, and check the target site's response times — slow origins slow the whole crawl.
## Next Steps
Design your Table schema before configuring a web scrape.
See all the ways to sync data into Databases, including Notion and Google Sheets.
Search scraped content with semantic, keyword, and hybrid modes.
# Drive API Reference: Upload, Download, and Manage Files
Source: https://docs.scoutos.com/drive/api-reference
Full API reference for Scout Drive. Upload files, download by path, list folder contents, create folders, and delete files using REST endpoints or the SDK.
Scout Drive exposes a REST API for all file and folder operations. Every endpoint requires authentication and returns consistent JSON responses. This reference covers each endpoint in full — parameters, response shapes, curl examples, and SDK equivalents — so you can integrate Drive into any application or automate file management in your agents and workflows.
## Authentication
All Drive API endpoints require a Bearer token in the `Authorization` header:
```text theme={null}
Authorization: Bearer YOUR_API_KEY
```
You can generate and manage API keys under **Settings → API Keys** in the Scout dashboard.
## Base URL
```text theme={null}
https://api.scoutos.com
```
## Rate Limits
| Endpoint | Limit |
| ----------------------- | ----------------------- |
| `POST /drive/upload` | 100 requests per minute |
| `GET /drive/download` | 500 requests per minute |
| `GET /drive/list` | 300 requests per minute |
| `POST /drive/folders` | 100 requests per minute |
| `DELETE /drive/folders` | 50 requests per minute |
When you exceed a rate limit, the API returns `429 Too Many Requests`. Check the `Retry-After` response header for the number of seconds to wait before retrying.
## Endpoint Summary
| Action | Method | Endpoint |
| -------------------- | -------- | ----------------- |
| Upload files | `POST` | `/drive/upload` |
| Download a file | `GET` | `/drive/download` |
| List folder contents | `GET` | `/drive/list` |
| Create a folder | `POST` | `/drive/folders` |
| Delete a folder | `DELETE` | `/drive/folders` |
***
## POST /drive/upload
Upload one or more files to Drive. Each file can be placed at a specific path using the `metadata` array.
### Request
```text theme={null}
POST https://api.scoutos.com/drive/upload
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_KEY
```
### Parameters
One or more files sent as multipart form data fields. Each file corresponds by index to an entry in the `metadata` array.
A JSON array of metadata objects, one per file, controlling where each file is stored. If omitted, files are stored at the root using their original filenames.
### Metadata Object Fields
Fully qualified destination path, for example `/reports/2024/q1.pdf`. Takes the highest priority when resolving the file location.
Destination folder path, for example `/reports/2024`. Combined with `name` if both are provided.
Destination filename, for example `q1-report.pdf`. Combined with `folder` if provided, otherwise stored at the root.
### Path Resolution Priority
For each file at index `i`, the destination path is resolved in this order:
| Priority | Condition | Result |
| -------- | -------------------------- | ------------------------------------------ |
| 1 | `path` is set | Use `path` as the fully qualified location |
| 2 | `folder` + `name` both set | `{folder}/{name}` |
| 3 | `folder` only | `{folder}/{original_filename}` |
| 4 | `name` only | `/{name}` (root) |
| 5 | Neither set | `/{original_filename}` (root) |
### Response
`200 OK`
```json theme={null}
{
"data": [
{
"id": "file_abc123",
"name": "q1-report.pdf",
"path": "/reports/2024/q1-report.pdf",
"url": "https://cdn.scoutos.com/files/file_abc123",
"size": 204800,
"created_at": "2024-01-15T10:30:00Z"
}
]
}
```
Unique identifier for the uploaded file.
Stored filename.
Full path where the file was stored in Drive.
Direct URL to access the file content.
File size in bytes.
ISO 8601 timestamp of when the file was created.
### Examples
```bash cURL theme={null}
# Simple upload — stored at root with original filename
curl -X POST https://api.scoutos.com/drive/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "files=@report.pdf"
# Upload to a specific folder
curl -X POST https://api.scoutos.com/drive/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "files=@report.pdf" \
-F 'metadata=[{"folder": "/reports/2024"}]'
# Upload to a specific path
curl -X POST https://api.scoutos.com/drive/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "files=@report.pdf" \
-F 'metadata=[{"path": "/reports/2024/q1-summary.pdf"}]'
# Upload multiple files to different locations
curl -X POST https://api.scoutos.com/drive/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "files=@report.pdf" \
-F "files=@data.csv" \
-F 'metadata=[{"path": "/reports/2024/q1-report.pdf"}, {"folder": "/data/exports", "name": "sales-data.csv"}]'
```
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
# Simple upload — stored at root with original filename
result = client.drive.upload(files=["report.pdf"])
# Upload to a specific folder
result = client.drive.upload(
files=["report.pdf"],
metadata=[{"folder": "/reports/2024"}]
)
# Upload to a specific path
result = client.drive.upload(
files=["report.pdf"],
metadata=[{"path": "/reports/2024/q1-summary.pdf"}]
)
# Upload multiple files to different locations
result = client.drive.upload(
files=["report.pdf", "data.csv", "notes.txt"],
metadata=[
{"path": "/reports/2024/q1-report.pdf"},
{"folder": "/data/exports", "name": "sales-data.csv"},
{"folder": "/notes"}
]
)
print(result["data"][0]["path"]) # /reports/2024/q1-report.pdf
```
```typescript TypeScript theme={null}
import { ScoutClient } from "scoutos";
import * as fs from "fs";
const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });
// Simple upload — stored at root with original filename
const result = await client.drive.upload({
files: [fs.createReadStream("report.pdf")]
});
// Upload to a specific folder
const folderResult = await client.drive.upload({
files: [fs.createReadStream("report.pdf")],
metadata: [{ folder: "/reports/2024" }]
});
// Upload to a specific path
const pathResult = await client.drive.upload({
files: [fs.createReadStream("report.pdf")],
metadata: [{ path: "/reports/2024/q1-summary.pdf" }]
});
console.log(pathResult.data[0].path); // /reports/2024/q1-summary.pdf
```
***
## GET /drive/download
Download a single file from Drive. Returns the raw file content as a binary stream.
### Request
```text theme={null}
GET https://api.scoutos.com/drive/download
Authorization: Bearer YOUR_API_KEY
```
### Query Parameters
Fully qualified file path, for example `/reports/report.pdf`. Use this **or** `name` + `folder` — not both.
Filename to retrieve, for example `report.pdf`. Must be used together with `folder`.
Folder to search within, for example `/reports`. Must be used together with `name`.
Provide either `path` alone, or both `name` and `folder` together. The request returns `400 Bad Request` if neither combination is supplied.
### Response
`200 OK` — Returns the file content as a binary stream. Response headers include:
```text theme={null}
Content-Type: application/pdf
Content-Disposition: attachment; filename="report.pdf"
```
### Examples
```bash cURL theme={null}
# Download by full path
curl -X GET "https://api.scoutos.com/drive/download?path=/reports/2024/q1-report.pdf" \
-H "Authorization: Bearer YOUR_API_KEY" \
--output q1-report.pdf
# Download by folder + name
curl -X GET "https://api.scoutos.com/drive/download?name=q1-report.pdf&folder=/reports/2024" \
-H "Authorization: Bearer YOUR_API_KEY" \
--output q1-report.pdf
```
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
# Download by full path
content = client.drive.download(path="/reports/2024/q1-report.pdf")
with open("q1-report.pdf", "wb") as f:
f.write(content)
# Download by folder + name
content = client.drive.download(
name="q1-report.pdf",
folder="/reports/2024"
)
with open("q1-report.pdf", "wb") as f:
f.write(content)
```
```typescript TypeScript theme={null}
import { ScoutClient } from "scoutos";
import * as fs from "fs";
const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });
// Download by full path
const content = await client.drive.download({
path: "/reports/2024/q1-report.pdf"
});
fs.writeFileSync("q1-report.pdf", Buffer.from(content));
// Download by folder + name
const contentByName = await client.drive.download({
name: "q1-report.pdf",
folder: "/reports/2024"
});
fs.writeFileSync("q1-report.pdf", Buffer.from(contentByName));
```
***
## GET /drive/list
List the files and subfolders within a Drive folder. Defaults to the root folder if no `folder` is specified.
### Request
```text theme={null}
GET https://api.scoutos.com/drive/list
Authorization: Bearer YOUR_API_KEY
```
### Query Parameters
Folder path to list, for example `/reports`. Defaults to root (`/`) if omitted.
When `true`, returns all nested files and folders at every depth within the target folder.
### Response
`200 OK`
```json theme={null}
{
"data": {
"folder": "/reports",
"files": [
{
"id": "file_abc123",
"name": "q1-report.pdf",
"path": "/reports/q1-report.pdf",
"size": 102400,
"created_at": "2024-01-15T10:30:00Z"
}
],
"folders": [
{
"id": "folder_xyz789",
"name": "2024",
"path": "/reports/2024"
}
]
}
}
```
The folder path that was listed.
Files directly inside the folder. Includes all nested files when `recursive: true`.
Unique file identifier.
Filename.
Full path to the file in Drive.
File size in bytes.
ISO 8601 creation timestamp.
Immediate subfolders within the listed folder.
Unique folder identifier.
Folder name.
Full folder path in Drive.
### Examples
```bash cURL theme={null}
# List root folder
curl -X GET "https://api.scoutos.com/drive/list" \
-H "Authorization: Bearer YOUR_API_KEY"
# List a specific folder
curl -X GET "https://api.scoutos.com/drive/list?folder=/reports" \
-H "Authorization: Bearer YOUR_API_KEY"
# List recursively
curl -X GET "https://api.scoutos.com/drive/list?folder=/reports&recursive=true" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
# List root folder
contents = client.drive.list()
# List a specific folder
contents = client.drive.list(folder="/reports")
# List all files recursively
contents = client.drive.list(folder="/reports", recursive=True)
for file in contents["data"]["files"]:
print(f"{file['path']} ({file['size']} bytes)")
```
```typescript TypeScript theme={null}
import { ScoutClient } from "scoutos";
const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });
// List a specific folder
const contents = await client.drive.list({ folder: "/reports" });
// List recursively
const allFiles = await client.drive.list({
folder: "/reports",
recursive: true
});
for (const file of allFiles.data.files) {
console.log(`${file.path} (${file.size} bytes)`);
}
```
***
## POST /drive/folders
Create a new folder in Drive. Intermediate parent folders are created automatically if they do not already exist.
### Request
```text theme={null}
POST https://api.scoutos.com/drive/folders
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```
### Request Body
Full path for the new folder, for example `/reports/2024/q1`. Intermediate folders are created automatically.
### Response
`200 OK`
```json theme={null}
{
"data": {
"id": "folder_abc123",
"path": "/reports/2024",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
Unique identifier for the created folder.
Full path of the created folder.
ISO 8601 creation timestamp.
### Examples
```bash cURL theme={null}
# Create a folder
curl -X POST https://api.scoutos.com/drive/folders \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "/reports/2024"}'
# Create nested folders — intermediate paths are created automatically
curl -X POST https://api.scoutos.com/drive/folders \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "/projects/research/analysis"}'
```
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
# Create a single folder
result = client.drive.create_folder(path="/reports/2024")
print(result["data"]["id"]) # folder_abc123
# Create nested folders — intermediate paths are created automatically
result = client.drive.create_folder(path="/projects/research/analysis")
```
```typescript TypeScript theme={null}
import { ScoutClient } from "scoutos";
const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });
// Create a folder
const result = await client.drive.createFolder({ path: "/reports/2024" });
console.log(result.data.id); // folder_abc123
// Nested folders are created automatically
const nested = await client.drive.createFolder({
path: "/projects/research/analysis"
});
```
***
## DELETE /drive/folders
Delete a folder from Drive. By default, deletion fails if the folder contains files or subfolders. Set `recursive: true` to force deletion of all contents.
Deletion is permanent. Files and folders removed with this endpoint cannot be recovered. Use the archive pattern — move files to `/archive/...` — if you want to preserve history.
### Request
```text theme={null}
DELETE https://api.scoutos.com/drive/folders
Authorization: Bearer YOUR_API_KEY
```
### Query Parameters
Full path of the folder to delete, for example `/reports/archived`.
When `true`, deletes all files and subfolders within the target folder. When `false` and the folder is non-empty, the request returns `409 Conflict`.
### Response
`200 OK`
```json theme={null}
{
"data": {
"deleted": true,
"path": "/reports/archived",
"files_deleted": 5
}
}
```
`true` if deletion succeeded.
Path of the deleted folder.
Number of files deleted, including files in subfolders when `recursive: true`.
### Examples
```bash cURL theme={null}
# Delete an empty folder
curl -X DELETE "https://api.scoutos.com/drive/folders?path=/reports/archived" \
-H "Authorization: Bearer YOUR_API_KEY"
# Delete a folder and all its contents
curl -X DELETE "https://api.scoutos.com/drive/folders?path=/reports/old&recursive=true" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
# Delete an empty folder
result = client.drive.delete_folder(path="/reports/archived")
# Delete a folder and all its contents
result = client.drive.delete_folder(path="/reports/old", recursive=True)
print(result["data"]["files_deleted"]) # e.g. 12
```
```typescript TypeScript theme={null}
import { ScoutClient } from "scoutos";
const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });
// Delete an empty folder
const result = await client.drive.deleteFolder({ path: "/reports/archived" });
// Delete a folder and all its contents
const recursive = await client.drive.deleteFolder({
path: "/reports/old",
recursive: true
});
console.log(recursive.data.files_deleted); // e.g. 12
```
***
## Error Handling
All Drive API errors follow a consistent JSON structure:
```json theme={null}
{
"error": {
"code": "not_found",
"message": "No file found at path /reports/missing.pdf"
}
}
```
### HTTP Status Codes
| Status | Code | Description |
| ------ | ------------------ | ------------------------------------------------------------------------------- |
| `200` | — | Request succeeded |
| `400` | `bad_request` | Malformed request — missing required fields or invalid JSON |
| `401` | `unauthorized` | Missing or invalid API key |
| `404` | `not_found` | The specified file or folder does not exist |
| `409` | `conflict` | Attempted to delete a non-empty folder without `recursive: true` |
| `422` | `validation_error` | Request parameters failed validation; `message` describes the invalid parameter |
| `429` | `rate_limited` | Too many requests; check `Retry-After` header |
| `500` | `internal_error` | Unexpected server error; contact Scout support if it persists |
### Common Error Scenarios
**Missing required parameter (422)**
```json theme={null}
{
"error": {
"code": "validation_error",
"message": "Parameter 'path' is required for folder deletion"
}
}
```
**File not found (404)**
```json theme={null}
{
"error": {
"code": "not_found",
"message": "No file found at path /reports/missing.pdf"
}
}
```
**Non-empty folder without recursive flag (409)**
```json theme={null}
{
"error": {
"code": "conflict",
"message": "Folder /reports/2024 is not empty. Set recursive=true to delete its contents."
}
}
```
**Rate limit exceeded (429)**
```json theme={null}
{
"error": {
"code": "rate_limited",
"message": "Upload rate limit exceeded. Retry after 15 seconds."
}
}
```
## Next Steps
Learn how Drive works, common use cases, and how to give agents file access.
Use Databases for structured data and semantic search across your agent's knowledge base.
# Drive
Source: https://docs.scoutos.com/drive/overview
Scout Drive is built-in file storage for agents and workflows. Upload PDFs and documents, then let agents read, write, and organize files autonomously.
Scout Drive is the file storage layer built directly into your Scout workspace. When your agents need to read a contract, save a generated report, or pass a document between workflow steps, Drive is where those files live. Unlike external storage services, Drive is natively connected to your agents and workflows — no integration setup, no separate credentials, no glue code.
## What Is Scout Drive?
Drive handles file I/O for your entire Scout workspace. It supports any file type your agents produce or consume: PDFs, images, markdown reports, CSVs, Word documents, exported data, and more. You can upload files manually via the API or SDK, and agents can read and write files autonomously as part of their tasks.
Drive is purpose-built for file operations. For structured data that your agents need to search semantically — FAQs, documentation, knowledge bases — use [Databases](/databases/overview) instead.
## Drive vs. Databases
Scout provides multiple storage options. Here's how Drive compares:
| Feature | Drive | Databases & Tables |
| --------------------- | -------------------------------------- | -------------------------------------- |
| **Purpose** | File storage — PDFs, images, documents | Structured data with vector search |
| **Access pattern** | By path or filename | Semantic, keyword, or hybrid search |
| **Best for** | Assets, attachments, generated outputs | RAG pipelines, knowledge bases, tables |
| **Agent interaction** | Agents read and write files directly | Agents search by meaning |
| **Sync** | Manual upload or agent writes | Notion, Sheets, web scraping |
| **Search** | Browse by folder path | Full-text and vector search |
**Use Drive when you need to:**
* Store PDFs or documents for agents to read and summarize
* Save generated reports, exports, or deliverables
* Pass files between workflow steps
* Manage reference assets like prompt templates or checklists
* Persist agent outputs across sessions
**Use Databases when you need to:**
* Build RAG applications with semantic search
* Store structured data in queryable tables
* Create knowledge bases agents search with natural language
* Sync data from Notion, Google Sheets, or scraped websites
## Getting Started
Use the API, Python SDK, or TypeScript SDK to upload a file to Drive.
```bash cURL theme={null}
curl -X POST https://api.scoutos.com/drive/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "files=@report.pdf"
```
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
result = client.drive.upload(files=["report.pdf"])
print(result)
# {'data': [{'url': 'https://...', 'name': 'report.pdf', 'id': 'file_abc123'}]}
```
```typescript TypeScript theme={null}
import { ScoutClient } from "scoutos";
import * as fs from "fs";
const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });
const result = await client.drive.upload({
files: [fs.createReadStream("report.pdf")]
});
console.log(result);
```
When no destination is specified, the file is stored at the root (`/`) using its original filename.
Create a folder structure that mirrors how your agents work. Use the `folder` or `path` metadata field to control where each file lands.
```python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
# Create the destination folder
client.drive.create_folder(path="/reports/2026")
# Upload into that folder
client.drive.upload(
files=["q1_summary.pdf"],
metadata=[{"folder": "/reports/2026", "name": "q1_summary.pdf"}]
)
# List the folder contents
files = client.drive.list(folder="/reports/2026")
for file in files["data"]["files"]:
print(f"{file['name']} — {file['path']}")
```
Open your agent in Scout, go to the **Tools** tab, and enable **Drive**. Once enabled, your agent can read and write files using natural language instructions.
Try this prompt:
> "Read `/reports/2026/q1_summary.pdf` and extract the top three findings."
Your agent locates the file, reads it, and returns a structured response — no code required.
## Organizing Files
### Folder Structure
Design folder hierarchies that match your workflows. Some common patterns:
```text theme={null}
/inbox — files waiting to be processed
/reports — generated outputs, organized by date or type
/exports — data exports and CSV files
/archive — older files moved out of active paths
/memory — agent-persisted notes and goals
/clients — per-client deliverables and assets
/briefs — synthesized research and summaries
```
### Path Resolution
When you upload a file, Drive resolves its destination path using the following priority order:
| Option | Example | Result |
| ----------------- | --------------------------------- | --------------------------------------- |
| `path` | `/docs/report.pdf` | Exact path — highest priority |
| `folder` + `name` | folder=`/docs`, name=`report.pdf` | `/docs/report.pdf` |
| `folder` only | folder=`/docs` | `/docs/{original_filename}` |
| `name` only | name=`report.pdf` | `/report.pdf` (stored at root) |
| Neither | — | `/{original_filename}` (stored at root) |
Use `path` whenever you need a deterministic, collision-safe output location. It gives you full control with a single parameter.
### Moving Files Between Folders
Drive doesn't have a dedicated move endpoint. Use this three-step pattern to relocate files:
1. Download from the source path.
2. Upload to the new destination path using `metadata.path`.
3. Archive or delete the source when appropriate.
This keeps relocations explicit and visible in workflow logs.
## What Agents Can Do with Drive
Once Drive is enabled as a tool, agents can perform a wide range of file operations autonomously.
### Reading and Summarizing Files
```text theme={null}
"Read /contracts/incoming/acme_nda.pdf and summarize the key obligations."
"Find all files in /reports/monthly and tell me which ones are missing an executive summary."
"Read the latest file in /exports/crm and identify any contacts without an assigned owner."
```
### Writing Reports and Exports
```text theme={null}
"Write a daily standup summary to /reports/daily/2026-05-04.md."
"Export this contact list to a CSV and save it to /exports/crm/."
"Create a markdown brief from this meeting transcript and save it to /briefs/."
```
### Organizing and Relocating Files
```text theme={null}
"Create /archive/2025/q4, then move all files from /reports/q4-2025 into it."
"List everything in /handoff and tell me which files are older than 30 days."
"Rename /drafts/brief-v1.md to /drafts/brief-final.md."
```
### Using Drive for Agent Memory
Agents can use Drive to persist information across sessions — keeping state visible and inspectable as plain files:
```text theme={null}
User: "Remember that our Q1 revenue target is $2.4M."
Agent: "Saved to /memory/goals.md. I'll reference this in future conversations."
```
This pattern works well for long-running agents that need to maintain goals, preferences, or context between interactions.
## Giving Agents Drive Access
### 1. Enable the Drive Tool
In your agent's **Tools** tab, enable **Drive**. This grants the agent permission to read and write files within your workspace.
### 2. Add Instruction Context
Include the following in your agent's system prompt to encourage consistent, safe file behavior:
```markdown theme={null}
When handling file tasks:
1. List the destination folder before writing new files.
2. Use explicit paths for all outputs — avoid implicit root writes.
3. For relocation requests, copy content to the new path, then confirm
archive or cleanup behavior with the user.
4. Always confirm the written file path and name in your final response.
5. Never delete folders unless the user explicitly requests cleanup.
```
### 3. Expected Agent Behavior
With Drive enabled and clear system prompt guidance, your agents will:
* Check folder contents before writing to avoid collisions
* Use predictable, deterministic paths when creating files
* Confirm the output location after each write
* Avoid destructive cleanup unless explicitly asked
## Practical Use Cases
Upload incoming contracts to `/contracts/incoming`. Your agent reads each file, extracts key clauses, and writes a structured summary to `/contracts/summaries`. A workflow routes summaries to the right team channel.
An agent runs on a schedule, pulls data from your CRM integration, and writes a formatted markdown report to `/reports/daily/{date}.md`. Stakeholders access the latest report directly from Drive.
An agent reads multiple PDFs in a `/research` folder, synthesizes findings, and writes a consolidated brief to `/briefs/`. It lists what it read so the output is fully auditable.
Agents generate proposals, summaries, or exports and save them to client-specific folders like `/clients/acme/deliverables/`. Each output is timestamped and versioned by filename.
Multiple agents share a `/handoff` folder. Agent A writes a structured context file after finishing its task. Agent B reads that file at the start of its run to pick up where the first agent left off.
Agents persist goals, preferences, and session notes to `/memory/`. This pattern keeps long-running agent state visible and inspectable rather than buried in opaque context windows.
## Troubleshooting
**File not found after upload**
Check the path you specified in the `metadata` parameter. If no `folder` or `path` was set, the file was saved to the root (`/`). Run `client.drive.list(folder="/")` to confirm its location.
**Agent is not finding files**
Verify that Drive is enabled in the agent's **Tools** tab. Also confirm the file path you're referencing exists exactly as specified — paths are case-sensitive.
**Agent writes to the wrong location**
Add explicit path guidance to your system prompt. The instruction snippet in [Giving Agents Drive Access](#giving-agents-drive-access) helps agents default to predictable, scoped paths.
**Upload fails with a 413 or size error**
The file exceeds the size limit for your Scout plan. For large files, consider splitting the content into smaller chunks or compressing the file before upload.
**Folder delete removed files I needed**
Drive folder deletion is permanent. Use the archive pattern — move files to `/archive/...` — instead of deleting when you want to preserve history. Only call `delete_folder` when you are certain the contents are no longer needed.
## Best Practices
* Use descriptive, date-stamped filenames for generated outputs (for example, `standup-2026-05-04.md`).
* Keep folder conventions stable — agents perform better with consistent, predictable paths.
* Separate input and output paths (for example, `/inbox` vs. `/reports`) to avoid accidental overwrites.
* Schedule regular archive jobs to prevent storage sprawl.
* Use Databases instead of Drive when your agents need to search content semantically.
## Next Steps
Full endpoint documentation for upload, download, list, create folder, and delete.
Use Databases when agents need semantic search over structured content.
# Sharing Drive Files: Public and Password-Protected Links
Source: https://docs.scoutos.com/drive/sharing
Share files from Scout Drive with a unique link. Create public or password-protected links, copy and rotate them, and let agents publish files automatically.
Every file in Scout Drive can be shared through a unique URL that lets others view or download it — no Scout account required. This makes Drive a natural place for agents that generate artifacts like reports, exports, and documents to publish their output and hand it off to users or external systems.
Files with an active share link display a globe icon (🌐) next to their name. The Drive panel lives in the left sidebar of your Studio workspace.
## How to Share a File
Open **Drive** from the left sidebar of your Studio workspace.
Find the file you want to share in the file list.
Click the **···** menu on the file's row.
Choose **Share** to open the sharing options submenu.
## Sharing Options
Drive offers two sharing modes. A checkmark indicates the active mode.
| Mode | Access | Best for |
| ---------------------- | ------------------------------------------- | --------------------------------------------------------------- |
| **Public** | Anyone with the link — no login or password | Low-friction sharing with clients, teammates, or external tools |
| **Password Protected** | Anyone with the link plus the password | Sensitive material like financial reports or client data |
For **Password Protected** links, Scout generates the initial password, which you can change at any time.
## Copy the Share Link
Once sharing is active, click **Copy link** to copy the URL to your clipboard. The link stays live until you change the settings or disable sharing.
## Change the Password
For a password-protected file, click **Change password** to rotate the credentials. Scout immediately generates a new password, and the old one stops working right away. Rotate passwords whenever your audience changes.
## Stop Sharing
Click **Stop sharing** to instantly disable access. The link breaks, but the file itself stays untouched in your Drive.
Share links don't expire on their own. If access needs to end by a specific deadline, stop sharing manually.
## The Globe Icon
Files with an active share link — public or password protected — show a globe icon (🌐) next to their name. Files without it remain private to your workspace.
## Let Your Agent Do It
Scout agents can create, save, publish, and link a file in a single conversation. This works for any file type the agent can produce — HTML, markdown, CSVs, or reports.
Try this prompt:
> "Create an HTML page and save it to Drive. Let's call it 'Scout Rocks' and make it very snazzy, bright, and glowy."
The agent generates the file, saves it to Drive, and can share it back as a link — no manual steps required.
## Best Practices
* Use password protection for sensitive material like financial reports or client data.
* Rotate passwords when your audience changes so old recipients lose access.
* Turn off sharing when you're finished — links don't expire on their own.
* Stop sharing manually if you need access to expire by a specific deadline.
## Next Steps
Learn how Scout Drive works, common use cases, and how to give agents file access.
Manage files and folders programmatically with the Drive REST API.
# Scout Core Concepts: Agents, Workflows, and Databases
Source: https://docs.scoutos.com/getting-started/core-concepts
Understand the core building blocks of Scout: agents, instructions, databases, drive, syncs, observability, and workflows — with practical examples.
Scout is built around a set of composable building blocks — agents, instructions, data storage, syncs, observability, and workflows. Understanding how these pieces fit together helps you move from experimenting with templates to building production-ready automations that run reliably at scale. This page walks you through each concept with practical examples and clear definitions.
***
## Agents
Agents are AI assistants that take action across your tools. You give an agent a goal; it figures out the steps to achieve it. Unlike a chatbot that answers questions and waits, a Scout agent connects to your tools, makes decisions, and executes tasks autonomously.
**Create an agent:** Scout Studio → Agents. Connect your tools, write instructions, and let it run.
| Chatbots | Scout Agents |
| --------------------- | ---------------------------------------- |
| Answer questions | Take action |
| Wait for instructions | Figure out the steps independently |
| Single conversation | Remember context across sessions |
| One tool at a time | Connect to all your tools simultaneously |
**Example:** *"Research our top 5 competitors and summarize their pricing."*
The agent finds the competitors, searches for pricing pages, handles cases where pricing isn't publicly listed, and delivers a structured summary — all without step-by-step instructions from you.
***
## Instructions
Instructions are the natural language you write to define an agent's behavior. They tell the agent what to do, how to act, and what to prioritize. Think of them less like a one-time prompt and more like a job description — instructions persist across every run of the agent.
**Write instructions:** Studio → Agents → select your agent → Instructions field.
**What makes instructions effective:**
* Be specific about the goal, not just the task
* Describe the output format you expect
* Give context about who the agent is helping
* Explain how to handle edge cases or missing data
Here's the difference in practice:
**Vague:**
```text theme={null}
Research competitors.
```
**Specific:**
```text theme={null}
Research our top 5 SaaS competitors. For each, find their pricing
page, free tier limits, and top 3 integrations. If pricing isn't
publicly listed, note that explicitly. Return results as a table
with one row per competitor.
```
The specific version defines scope, sets expectations for incomplete data, and specifies the output format. That's what gets you a useful result on the first run — not after several rounds of back-and-forth.
**Instructions vs. prompts:** Instructions are persistent and shape every run of the agent. A prompt is a one-time request sent during a conversation. Use instructions to set the agent's default behavior; use prompts to make one-off requests.
***
## Databases
Databases are Scout's structured data storage layer — your agent's personal library. Use them to store documents, customer data, product information, or any structured content your agents need to search and retrieve.
**Create a database:** Studio → Databases. Define a schema with column types like text, number, select, datetime, or relation.
* **Databases** are top-level containers that group related data together
* **Tables** store structured records within a database, with defined schemas
**What you can do with databases:**
* Store product catalogs, FAQs, customer records, or knowledge base articles
* Let agents search and retrieve information by meaning using built-in vector search
* Sync data automatically from external sources (see [Syncs](#syncs) below)
**Example:** Upload your product catalog to a database. Now any agent can answer customer questions about specs, pricing, and availability — by searching the database semantically, not just by keyword match.
***
## Drive
Drive is Scout's file storage layer for documents, images, and assets your agents need to read, write, or reference.
**Upload files:** Studio → Drive. Organize into folders. Agents can read and write files directly.
**Common use cases:**
* Upload PDFs for an agent to analyze and extract data from
* Store images for processing or transformation workflows
* Share assets (templates, reference files, exports) across multiple workflows
Drive and Databases serve different purposes. Drive is for files (PDFs, images, CSVs). Databases are for structured, searchable records. Use whichever matches the shape of your data.
***
## Syncs
Syncs let you import data from external sources into your Databases automatically. Set up a sync once, and Scout keeps your data current without any manual effort.
**Configure a sync:** Studio → Syncs. Select a source, map fields to your database tables, and set a refresh schedule.
**Supported sources:**
| Source | What Gets Imported |
| ------------- | ----------------------------------- |
| Websites | Crawled and scraped page content |
| Sitemaps | Bulk page imports from XML sitemaps |
| Notion | Pages and databases |
| Google Drive | Docs, Sheets, and Slides |
| Microsoft 365 | SharePoint and OneDrive content |
| Laserfiche | Enterprise document repositories |
**How it works:** Point a sync at your source, map its fields to your database schema, and Scout handles the rest — pulling updates on your chosen schedule so your agents always work with fresh data.
***
## Observability
Observability gives you a clear view of what your agents are doing — every action logged, every decision traceable. This is how you build trust in your automations: not by hoping things worked, but by seeing exactly what happened.
**Activity Logs** show you:
* When an agent ran and what it completed
* How long each step took
* Whether each step succeeded or failed
**Execution Traces** show you:
* Which tools were called and in what order
* What decisions the agent made at each step
* Why the agent chose a particular approach
**Tool Usage** shows you:
* **Reads:** Documents, databases, and APIs the agent queried
* **Writes:** Content the agent created, updated, or sent
* **External calls:** Third-party services the agent contacted
Use execution traces when an agent produces an unexpected result. Traces let you pinpoint exactly where the behavior diverged from what you intended, so you can update instructions or fix the workflow quickly.
***
## Workflows
Workflows are automated sequences triggered by events or schedules. They connect your tools, execute logic, and run reliably at scale — no code required.
**Build a workflow:** Studio → Workflows. Drag and drop blocks to create logic flows, then connect a trigger to activate it.
### Triggers
A trigger is what starts a workflow. Scout supports four types:
| Trigger Type | Example |
| ---------------------- | ------------------------------------------------------ |
| **Webhook** | A form submission fires a POST request to Scout |
| **Schedule (cron)** | Run every weekday at 9:00 AM |
| **Event** | An agent completes a task; a file is uploaded to Drive |
| **Native integration** | A new calendar event is created; an email arrives |
### Blocks
Blocks are the individual steps inside a workflow. Each block does one job:
| Block Type | What It Does |
| -------------------- | ------------------------------------------------------ |
| **Action Blocks** | Make API calls, write to databases, send notifications |
| **Agent Blocks** | Run a Scout AI agent as a step in the workflow |
| **Condition Blocks** | Branch logic based on if/else conditions |
| **Transform Blocks** | Modify, reshape, or enrich data between steps |
**Example workflow:** New lead from website → Research the company → Enrich the CRM record → Draft a personalized outreach email → Notify the sales rep in Slack.
Each arrow in that sequence is a block. The whole thing runs automatically whenever a new lead arrives.
***
## Key Terms
| Term | What It Means |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| **Agent** | An AI assistant that takes action across your tools |
| **Workflow** | An automated sequence triggered by events or schedules |
| **Database** | A top-level data container in Scout — Tables of structured records, your agent's personal library |
| **Table** | Structured data records within a database |
| **Drive** | File storage for documents, images, and assets |
| **Sync** | Automatic data import from an external source |
| **Instructions** | Persistent natural language guidance that shapes agent behavior |
| **Context** | The data, files, and history an agent works with on a given run |
***
## Next Steps
Build your first agent using a pre-built template — no code required.
Go deeper on triggers, blocks, and building production workflows.
Learn how to store, structure, and sync data for your agents.
See every tool and service your agents can connect to.
# Quick Start: Create Your First AI Agent with Scout
Source: https://docs.scoutos.com/getting-started/quick-start
Build your first AI agent in Scout using a pre-built template. Connect your calendar, email, Slack, and schedule a daily briefing in minutes.
The fastest way to experience Scout is to let an agent set itself up. In about five minutes, you'll have a personal AI assistant connected to your calendar, email, and chat platform — and delivering a daily briefing every morning. All you need is a Scout account (a free plan is available) and a few minutes to answer some questions.
**Prerequisite:** A Scout account. Sign up at [scoutos.com](https://scoutos.com) — no credit card required for the free plan.
The fastest way to create your first agent is with a pre-built template from the Marketplace.
1. Open **Marketplace** in Scout Studio
2. Find the **Personal Agent** template
3. Click **Use Template**
4. Complete the **12-question interview**
The interview covers your working style, communication preferences, and the tools you use most. Once you finish, your agent is live — send it a message to see how it responds.
Be honest and specific in the interview. The more context your agent has about how you work, the more useful it will be from day one.
Your assistant can connect tools for you. You don't need to navigate settings menus or configure integrations manually.
**Ask your assistant:**
```text theme={null}
Help me connect my calendar.
```
It will guide you through the authorization steps and confirm when the connection is live. Once connected, your agent can check your schedule, find open meeting times, and remind you of upcoming events.
Give your agent the ability to read, summarize, and draft emails on your behalf.
**Ask your assistant:**
```text theme={null}
Help me connect my email.
```
Your agent will walk you through connecting Gmail, Outlook, or another provider. After that, it can triage your inbox, surface important messages, and draft replies — all from a single prompt.
Talk to your agent where you already work. Slack and Telegram are both supported.
**Ask your assistant:**
```text theme={null}
Help me connect Slack.
```
or
```text theme={null}
Help me connect Telegram.
```
This is where your agent will reach you day-to-day. Once it's set up, you won't need to open Scout Studio to interact with it — just message it directly from your chat app.
Add only one tool at a time and verify each connection before moving to the next. It's easier to troubleshoot a single integration than to untangle multiple ones at once.
Set up a morning routine that keeps you informed before the day begins. Copy and paste the prompt below directly to your assistant:
```text theme={null}
Set up a daily brief that runs every morning at 8:00 AM.
It should check my email for important messages, review my
calendar for the day's events, search for news on topics I
care about, and post a summary to my Slack or Telegram channel.
```
Your assistant creates the schedule for you — no manual configuration needed. Check back the next morning to see your first brief arrive in your chat platform.
You can adjust the time, news topics, and output format by simply asking your assistant to update the brief. Changes take effect on the next scheduled run.
## Key Principle
Your assistant is equipped to help you integrate with all core tools. You don't need to dig through settings menus or read integration documentation. If you're unsure how to do something, just ask — your agent can configure itself, schedule tasks, and connect tools on demand.
## Tips for Getting the Most Out of Your Agent
* **Be specific** — Clearer instructions produce better results. Instead of "summarize my emails," try "summarize unread emails from the past 24 hours and flag anything that needs a reply today."
* **Chat regularly** — Your agent becomes more useful the more context it has. The more you interact, the better it understands your priorities.
* **Ask for anything** — If you're unsure whether your agent can do something, just ask. It will tell you what it needs to make it happen.
* **Iterate freely** — You can update your agent's instructions, add tools, or change its schedule at any time by chatting with it directly.
## What's Next
Understand agents, instructions, databases, workflows, and the other building blocks of Scout.
See every tool and service your agent can connect to.
Explore pre-built agents beyond the personal assistant — for support, research, and more.
Go deeper on building intelligent agents that adapt and take action.
# Search: Navigate Scout Studio with Cmd+K
Source: https://docs.scoutos.com/getting-started/search
Use Search to jump to any part of Scout Studio instantly from anywhere in the app — search destinations, tab through sections, and navigate without leaving the keyboard.
Search lets you jump to any part of Scout Studio without taking your hands off the keyboard. Open it from anywhere in the app and go directly to Agents, Drive, Tables, Workflows, and more.
![Search open over Scout Studio, showing the search field, section tabs, and recent searches and items]()
## Opening Search
Press `Cmd+K` on Mac or `Ctrl+K` on Windows. Search opens as a modal overlay on top of whatever you were working on.
To close it, press `Escape` or click anywhere outside the modal.
## Navigating with Search
Once Search is open, you have two ways to get where you want to go.
### Type to search
Type any destination — an agent name, a section, a table, or a workflow — and matching results appear instantly, grouped by section.
![Search filtering results as you type, grouped by section]()
Press `Enter` to navigate to the top result, or use the arrow keys to highlight a different one before opening it.
![Search with a result highlighted, ready to open with Enter]()
### Tab through sections
Press `Tab` to cycle through Scout's main areas. Each tab stop shows a preview of that section's content — including recent agents, workflows, chat history, and more — so you can orient yourself before navigating.
![Search with the Chats tab selected, previewing recent chat history]()
## What you can reach
Search gives you quick access to every major area of Scout Studio:
| Destination | What you find there |
| ------------ | ------------------------------------------------ |
| Agents | Your org's agents — open, edit, or run any agent |
| Drive | Files and documents stored in Scout Drive |
| Tables | Collections and table views |
| Workflows | Workflow editor and run history |
| Chat History | Past conversations across agents |
| Settings | Org settings, API Keys, Model Management |
## Keyboard reference
| Key | Action |
| ------------------------- | -------------------------------- |
| `Cmd+K` / `Ctrl+K` | Open Search |
| Type to search | Filter destinations in real time |
| `Arrow Up` / `Arrow Down` | Move through results |
| `Enter` | Navigate to selected result |
| `Tab` | Cycle through main sections |
| `Escape` | Close Search |
## Tips
Search works from any screen in Scout Studio — you never need to navigate back to a home view first.
* Use it to switch between agents quickly during testing without losing your place.
* Section tab-through is useful when you know the area but not the exact item name.
## What's Next
Understand agents, instructions, collections, workflows, and the other building blocks of Scout.
Go deeper on building intelligent agents that adapt and take action.
# What is Scout? Build AI Agents for Any Business Task
Source: https://docs.scoutos.com/getting-started/what-is-scout
Scout is an agentic workforce studio for building autonomous AI agents. Learn how it differs from traditional automation and chatbots.
Scout is an **agentic workforce studio** — a platform where you create, deploy, and manage autonomous AI agents that get real work done. Whether you're a developer who wants full API access or a business operator who prefers a visual interface, Scout gives you the tools to build agents that work independently, adapt to unexpected situations, and connect to the systems you already use.
## Goals Over Scripts
Traditional automation is fragile. A rule-based script breaks the moment something falls outside its predefined conditions. Scout agents work differently — you give them a goal in plain language, and they figure out the path.
| Traditional Automation | Scout Agents |
| --------------------------------- | ------------------------------------ |
| Breaks on unexpected input | Adapts and recovers automatically |
| Requires precise rule definitions | Understands goals in plain language |
| Single-path execution | Tries different approaches as needed |
| Fails silently or loudly | Handles edge cases gracefully |
**Old way:** `"If email subject contains 'urgent', forward to support@..."`
**Scout way:** `"Handle all incoming support emails and escalate the ones that need immediate attention."`
Agents handle edge cases, try different approaches, and recover from errors — all without you writing conditional logic for every scenario.
## Core Components
Scout is built around four foundational components that work together to give your agents the tools, memory, and structure they need.
### Agents
Intelligent, autonomous workers that connect to your tools, understand natural language instructions, and execute complex tasks. Agents collaborate across workflows, handle errors gracefully, and adapt to situations that no static script could anticipate.
### Workflows
Automated processes that connect your tools, trigger on events, and run reliably at scale. Workflows are the automation backbone of Scout — event-driven sequences with branching logic, error handling, and AI agents built right in.
### Drive
Secure file storage built for AI workflows. Upload documents, images, and data files that your agents can access and process — PDFs to analyze, images to transform, or assets to reference across automations.
### Databases
Structured data storage with built-in vector search. Create knowledge bases, power retrieval-augmented generation (RAG) applications, and let your agents find information by meaning, not just keywords.
No external infrastructure required. Drive and Databases are included with your Scout account — your agents have memory out of the box.
## Connect Everything, Configure Nothing
You shouldn't have to wrestle with OAuth flows or manage API keys manually. Scout handles authentication so you can focus on building:
* **One-click connections** to Slack, Google Workspace, Notion, CRMs, databases, and more
* **Secure credential management** built into the platform
* **Automatic token refresh** so connections stay alive without intervention
## No-Code and Code — You Get Both
Build with **Scout Studio**, the visual workflow builder, or write code with the Python and TypeScript SDKs. Mix and match as your project evolves:
* Start in the visual builder, export to code when you're ready
* Prototype in the studio, deploy via API in production
* Build custom tools visually, then reference them in code
## Who Is Scout For?
Scout is designed for a wide range of builders and operators — not just AI specialists.
Build with Python or TypeScript SDKs. Deploy agents via API. Create custom tools and integrations with full control when you need it.
Prototype AI features without waiting for engineering. Build internal tools visually, iterate quickly, and ship faster.
Automate repetitive workflows, build knowledge assistants, and connect your tools without writing a line of code.
Build AI-powered workflows in hours, not months. No dedicated AI team required — prototype, validate, and scale what works.
## Real-World Use Cases
### Customer Support Automation
> *"Handle incoming support tickets, look up customer history, and escalate urgent issues to the right team."*
An agent connects to your email, Slack, CRM, and internal knowledge base to triage tickets automatically — routing, responding, and escalating without manual intervention.
### Research & Analysis
> *"Research our top five competitors and create a pricing comparison report."*
The agent searches the web, extracts pricing pages, handles gaps in publicly available data, and synthesizes findings into a structured report — ready for your next strategy meeting.
### Document Processing
> *"Process all incoming invoices, extract key data, and update our accounting system."*
Agents read PDFs, pull out line items and totals, then push that data into QuickBooks or your ERP — no manual data entry required.
### Knowledge Assistant
> *"Answer employee questions about our policies and procedures."*
Connect your Notion wiki, Google Drive, and internal docs. Employees get instant, accurate answers without digging through folders or pinging HR.
These use cases are just starting points. The most powerful Scout deployments are built around the specific workflows your team runs every day.
## Ready to Build?
Build your first AI agent in five minutes using a pre-built template. No code required.
Understand agents, instructions, databases, drive, syncs, observability, and workflows.
# Connect Gmail to Your Scout Agents
Source: https://docs.scoutos.com/integrations/gmail
Give Scout agents access to Gmail to draft emails, summarize threads, triage inboxes, and automate communication workflows.
Communication work is one of the biggest time sinks in any role — triaging inboxes, writing follow-ups, prepping for calls. Connecting Gmail gives your agents the context and capabilities to handle this work with you, not just alongside you. An agent that can read your last 30 days of email with a contact can draft a follow-up that actually sounds right.
## Connecting Gmail
Scout connects to Gmail using OAuth. You authorize Scout once and it can read threads, draft messages, and — with explicit confirmation — send on your behalf.
Go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations) and click **Connect** next to **Gmail**.
You'll be redirected to Google's authorization screen. Review the permissions Scout requests and click **Allow**. Scout requests the minimum scopes needed for each capability:
| Scope | What it's for |
| ---------------- | ------------------------------------------ |
| `gmail.readonly` | Read messages and threads |
| `gmail.compose` | Create and save drafts |
| `gmail.send` | Send messages (only used when you confirm) |
| `gmail.modify` | Label and archive messages |
Back in Scout, your Gmail account should show as **Connected**. Open your agent, go to the **Tools** tab, and toggle on the Gmail tools.
In your agent's **Instructions**, add the guardrail snippet from the section below. This ensures the agent drafts before it sends.
Gmail and Google Calendar share the same Google OAuth flow. If you've already connected Gmail, you can [add Calendar access](/integrations/google-calendar) without authorizing from scratch.
## What Your Agent Can Do with Gmail
Once Gmail is connected and enabled on your agent:
* **Read and summarize threads** — pull recent email history with a contact or on a topic without opening your inbox
* **Draft replies** — write responses grounded in CRM context, prior emails, or documents
* **Triage inboxes** — flag high-priority messages and surface what needs a response
* **Generate pre-call briefs** — summarize the last 30 days of email with a contact before a meeting
* **Send follow-ups** — draft and send post-meeting notes after you confirm the content
A sent email cannot be unsent. Always use the draft-first guardrail (below) for any agent that has Gmail send access. Review drafts before approving a send action.
## Instruction Guardrails
Email actions reach real people immediately. A sent message is in their inbox. This instruction block enforces a draft-first, confirm-before-send pattern:
```markdown theme={null}
For email actions:
1. Draft first, send second. Show me the draft before sending.
2. Confirm recipient and subject before sending.
3. Return message IDs after actions complete.
```
If your agent skips the draft step and sends directly, paste this guardrail block verbatim into the agent's **Instructions**. Explicit instructions override default agent behavior.
## Prompt Examples
These prompts work once Gmail is connected and enabled on your agent:
* "Summarize my unread high-priority emails and draft replies for each. Don't send yet."
* "Create a prep brief for tomorrow's customer call using the last 30 days of email context."
* "Draft a follow-up to today's product sync and show it to me before sending."
* "Flag any emails in my inbox that mention contract renewals or pricing."
* "Find the latest thread with this contact and summarize where things stand."
## Testing Your Integration
Run through these steps in order before using the agent in production:
Ask your agent to summarize your inbox. It should return a readable list of recent messages without sending anything. If this fails, check that Gmail is connected and tools are toggled on.
Ask it to draft a reply to a specific email. Confirm the draft looks right and matches the tone and context you'd expect. Check that it appears as a draft in Gmail.
Only after the read and draft steps work, test a send action — start with a low-stakes email to yourself before involving others.
## Troubleshooting
Agent can't read my emails
Check that:
* The integration shows as **Connected** in [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations)
* Gmail tools are toggled **on** in your agent's **Tools** tab
* You authorized all requested permissions during setup — partial authorization can cause read failures
Try disconnecting and reconnecting the integration if you're still getting errors.
Agent sent an email without asking first
Add explicit instructions that require a draft step:
```
Never send an email without showing me a draft and getting confirmation first.
```
The guardrail snippet in this guide includes this behavior by default. If your agent is skipping it, paste the full snippet into your agent's **Instructions**.
## Use Cases
**Inbox triage** — Start your day by asking your agent to flag high-priority emails, identify anything that needs a same-day response, and draft replies to the top three. Review and approve before anything leaves your outbox.
**Pre-call prep** — Before a customer call, ask your agent to pull the last 30 days of email with that contact, combine it with their CRM record, and generate a structured brief with context, open items, and talking points.
**Post-meeting follow-up** — After a meeting, paste your notes into the agent and ask it to draft a follow-up email with action items, owners, and next steps. Confirm the draft, then send.
## Next Steps
Add scheduling so agents can find open slots, book meetings, and combine calendar context with email history.
Add Salesforce or HubSpot context to outreach drafts and pre-call briefs.
Route email summaries to team channels automatically.
Pull document context into email drafts and meeting prep workflows.
# Connect Google Calendar to Your Scout Agents
Source: https://docs.scoutos.com/integrations/google-calendar
Give Scout agents access to Google Calendar to check schedules, find open slots, book meetings, and automate scheduling workflows.
Finding meeting times, prepping for calls, and keeping a calendar accurate is steady, low-value work that adds up fast. Connecting Google Calendar lets your agents read your schedule, propose availability across timezones, and book meetings on your behalf — grounded in your real calendar data rather than guesswork.
## Connecting Google Calendar
Google Calendar connects through Google OAuth. If you've already connected [Gmail](/integrations/gmail), you can add Calendar access without authorizing from scratch — both services use the same Google account.
Go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations) and click **Connect** next to **Google Calendar**.
Review the permissions and click **Allow**. Scout requests:
| Scope | What it's for |
| ------------------- | --------------------------------- |
| `calendar.readonly` | Read your events and availability |
| `calendar.events` | Create and update events |
Open your agent's **Tools** tab and toggle on the Google Calendar tools.
In your agent's **Instructions**, add the guardrail snippet from the section below so the agent confirms details before booking.
## What Your Agent Can Do with Google Calendar
Once Google Calendar is connected and enabled on your agent:
* **Check your schedule** — read upcoming events, participants, and descriptions
* **Find open slots** — identify available windows across a time range or set of participants
* **Create events** — book meetings with titles, descriptions, participants, and video links
* **Propose availability** — suggest times across timezones based on real calendar data
* **Generate pre-meeting context** — combine calendar events with email history and CRM records for a full prep brief
A booked meeting shows up on someone else's calendar immediately. Use the guardrail below so the agent confirms the timezone, participants, and time before creating any event.
## Instruction Guardrails
Calendar actions reach real people immediately. This instruction block enforces a confirm-before-book pattern:
```markdown theme={null}
For calendar actions:
1. Confirm timezone, participants, and time before booking.
2. Include a concise rationale for each scheduling decision.
3. Show me the invite details before creating the event.
4. Return event IDs after actions complete.
```
If your agent uses the wrong timezone, specify it in the agent's **Instructions** or in each prompt: "Always use Pacific Time (PT) for scheduling unless I specify otherwise."
## Prompt Examples
These prompts work once Google Calendar is connected and enabled on your agent:
* "Find two 30-minute windows next week for a call with this group. Use Pacific time."
* "Book a 45-minute kickoff call with these four attendees sometime next week."
* "List my events for the next three days and flag any conflicts."
* "Create a prep brief for tomorrow's customer call using my calendar and the last 30 days of email context."
* "Propose three times that work across US Eastern and Central European time."
## Testing Your Integration
Run through these steps in order before using the agent in production:
Ask it to list your events for the next three days. Verify that it reads your calendar correctly and uses the right timezone.
Ask it to find open windows next week. Confirm the slots it returns don't conflict with existing events.
Only after the read steps work, test a booking action — start with an event on your own calendar before involving others.
## Troubleshooting
Agent can't read my calendar
Check that:
* The integration shows as **Connected** in [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations)
* Calendar tools are toggled **on** in your agent's **Tools** tab
* You authorized all requested permissions during setup — partial authorization can cause read failures
Try disconnecting and reconnecting the integration if you're still getting errors.
Agent is using the wrong timezone for scheduling
Specify your timezone in your agent's instructions or in each prompt:
```
Always use Pacific Time (PT) for scheduling unless I specify otherwise.
```
## Use Cases
**Scheduling across teams** — Ask your agent to find two 45-minute windows next week that work for four people across two timezones and propose them as calendar invites. The agent reads real availability and avoids conflicts.
**Pre-meeting prep** — Before a call, ask your agent to pull the relevant event, combine it with email history and CRM records, and generate a structured prep brief with context and talking points.
**Calendar hygiene** — Ask your agent to review the week ahead, flag double-bookings or back-to-back conflicts, and suggest fixes before they become a problem.
## Next Steps
Add email so agents can draft follow-ups and combine inbox context with your schedule.
Add Salesforce or HubSpot context to pre-meeting briefs.
Route calendar digests to team channels automatically.
Pull document context into meeting prep workflows.
# Connect Google Drive to Scout Agents
Source: https://docs.scoutos.com/integrations/google-drive
Give Scout agents access to Google Drive to read, summarize, and write Docs, Sheets, and Slides across your Drive.
Your files already contain a significant amount of institutional knowledge — strategy decks, QBR materials, policy documents, project briefs. Connecting Google Drive means your agents can read that content directly instead of relying on you to copy and paste it. You ask the agent to summarize a folder, find an outdated policy, or write an exec brief from a deck, and it does the work against your actual files.
## What Your Agent Can Do
Once Google Drive is connected and enabled:
* **Read Docs, Sheets, and Slides** — pull content from any file you've shared access to
* **List folders** — navigate your Drive structure to find files by path
* **Search by keyword or filename** — locate documents without knowing the exact path
* **Summarize documents** — condense long files into structured briefs
* **Create and update files** — write outputs back to specific folders in Drive
* **Sync to Databases** — pull content into Scout for search
## Connecting Google Drive
Go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations) and click **Connect** next to **Google Drive**.
You'll be redirected to Google's authorization screen. Sign in and approve the permissions Scout requests:
| Permission | What it's for |
| ---------------- | ------------------------------------------ |
| `drive.readonly` | Read your files and folders |
| `drive.file` | Create and edit files your agent generates |
Scout only accesses folders your agent is explicitly configured to use — it won't browse your entire Drive without direction.
Back in Scout, Google Drive should show as **Connected** in your integrations list.
Open your agent, go to the **Tools** tab, and toggle on the Google Drive tools. Then add path conventions to your agent's **Instructions** (see the guardrail section below).
## Instruction Guardrails
Without explicit path instructions, an agent writing files will choose its own output location, which makes files hard to find later. This instruction block establishes consistent read and write behavior:
```markdown theme={null}
For file operations:
1. List folders before reading or writing.
2. Use explicit folder paths for outputs (e.g., /reports/weekly/).
3. Keep source files and generated files in separate folders.
4. Return the final file path and name after each write.
```
Add this to your agent's **Instructions** before enabling any write tools.
If your agent frequently creates files, add a naming convention to your instructions: "Name new files as `[YYYY-MM-DD] - [Topic]` and place them in the `/reports/` folder." This keeps your file system organized without manual cleanup.
## Testing Your Integration
Ask your agent to list the files in a specific folder. It should return the contents with file names and types — no writes, no side effects.
Ask it to read a document and summarize it. Verify the summary is accurate and grounded in the actual file content.
If write access is enabled, ask the agent to create a test file with a specific name in a specific folder. Confirm it appears in Drive at the correct path.
## Prompt Examples
These prompts work once Google Drive is connected and enabled on your agent:
* "Read the latest QBR deck in Google Drive and write an executive brief."
* "Create a weekly summary doc from these folders and save it to /reports/weekly."
* "List everything in the /contracts folder and flag any files older than 90 days."
* "Find any Google Slides decks about product roadmap and extract the key initiatives."
## Use Cases
**Research and synthesis** — Ask your agent to read five documents in a folder and produce a structured summary with themes, conflicts, and open questions. The agent does the reading; you focus on the decisions.
**Meeting prep** — Before a QBR or board meeting, ask your agent to pull the relevant decks and reports from Drive, summarize the key numbers and narratives, and write a structured pre-read brief. Combine this with calendar context for a complete prep package.
**Executive briefs** — Regularly ask your agent to distill a folder of reports into a one-page brief for leadership. Point it at /reports/weekly in Drive, set a naming convention, and let it run on a schedule.
**Document hygiene** — Ask your agent to list files in a folder, identify anything older than a specified threshold, and flag items for review or archival. Useful for keeping shared drives from accumulating outdated materials.
## Troubleshooting
Agent can't find a file I know exists
Check two things:
* The folder path in your instructions matches exactly — capitalization matters in Drive paths
* The file is in a location Scout has access to — personal folders outside a shared drive may not be accessible depending on your permissions setup
Agent created a file but I can't find it
Ask your agent: "What path did you save the file to?" and check that location. If it's missing, the agent may have written to a default working folder rather than your intended destination. Add an explicit output path to your agent's instructions to prevent this.
I connected the integration but my agent doesn't see any tools
1. Go to your agent's **Settings** and open the **Tools** section
2. Make sure the Google Drive tools are toggled **on**
3. Confirm the integration shows as **Connected** at [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations)
If it still doesn't work, try disconnecting and reconnecting the integration.
## Next Steps
Connect SharePoint, OneDrive, and the Office file suite for mixed environments.
Combine file content with CRM data for meeting prep and account research.
Pull document context into email drafts and pre-call briefs.
Post document summaries and file-based digests to team channels.
# Connect HubSpot to Your Scout Agents
Source: https://docs.scoutos.com/integrations/hubspot
Integrate HubSpot CRM with Scout so agents can read and write contacts, companies, deals, tickets, and custom objects directly within workflows.
Connecting Scout to HubSpot CRM lets agents read and write CRM data — looking up contacts, creating deals, updating properties — directly within workflows. After connecting, you can issue natural-language requests and the agent handles them without manual entry. Setup takes about five minutes through a HubSpot Private App.
If your team also uses Salesforce, connect it independently from the [Salesforce integration page](/integrations/salesforce) — an agent can use tools from both CRMs in the same workflow.
## What Your Agent Can Do
Available actions depend on the scopes you grant during setup.
* Look up, create, and update contacts, companies, and deals
* Search and filter records (for example, finding open deals over a threshold)
* Create and manage tickets for support workflows
* Read and update custom objects and properties
* Access associations between records — contacts linked to a company, deals linked to a contact
* Trigger and check automation workflows
* Manage lists and list membership
## Prerequisites
* A HubSpot account with admin access
* A Scout workspace
## Getting Started
Log in to HubSpot, click the **Settings** (gear) icon in the top navigation, then go to **Integrations → Private Apps** in the left sidebar. Click **Create private app** and give it a recognizable name like "Scout CRM Integration" plus an optional description.
Under the **Scopes** tab, grant only the scopes you plan to use — you can update them later.
| Category | Scopes |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **CRM Objects** | Read/write for `contacts`, `companies`, `deals`, `tickets`, `custom`, and `line_items`, plus `crm.objects.owners.read` |
| **CRM Schemas** | Read/write for `contacts`, `companies`, `deals`, and `custom` |
| **Additional** | Associations read/write, `sales-email-read`, `tickets`, `timeline`, `automation`, and lists read/write |
Click **Create app** when finished.
Copy the access token from the confirmation screen for the next step. Treat it like a password — anyone with this token can read and write your CRM data.
Go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations), find **Enhanced HubSpot**, and click **Add Workspace**. Paste your access token into the API key field and click **Create Connection**. A confirmation appears once connected.
Open an agent, go to its **Tools** section, and enable the HubSpot integration for that agent. Then start a chat and try a prompt like:
```
List the 5 most recently created contacts in HubSpot.
```
If set up correctly, the agent returns real contact records.
## Best Practices
* **Least privilege** — enable only the scopes you need. Skip write scopes for read-only agents.
* **Rotate tokens periodically** — revoke and recreate the token if it's ever exposed.
* **Use clear app names** — distinguish multiple workspaces (e.g., "Scout Prod", "Scout Staging").
* **Review unused apps** — private apps don't expire, so clean up old ones you no longer use.
## Instruction Guardrails
CRM writes are consequential. A bad update can corrupt a record, create a duplicate, or overwrite data another rep entered. Add this block to your agent's **Instructions** before enabling any write tools:
```markdown theme={null}
For CRM tasks:
1. Look up the record before writing.
2. Match by stable identifier (record ID, email, domain) before updates.
3. Return the CRM object ID, fields changed, and reason after each write.
4. Ask before creating duplicates when confidence is low.
```
## Troubleshooting
| Issue | Solution |
| -------------------------- | --------------------------------------------------------------------- |
| "Invalid access token" | Ensure you copied the full token — they're long and easy to truncate. |
| "Insufficient permissions" | Add the missing scope to your private app in HubSpot. |
| "App not found" | Confirm the private app is active, not archived. |
## Next Steps
Connect Salesforce too — agents can use HubSpot and Salesforce tools in the same workflow.
Learn how to use HubSpot tools with agents and workflows.
See the full integration stack and recommended connection order.
Route pipeline summaries and deal alerts to your team channels.
# Connect Microsoft 365 to Scout Agents
Source: https://docs.scoutos.com/integrations/microsoft-365
Give Scout agents access to SharePoint, OneDrive, and the Microsoft 365 suite to read, summarize, and write Word, Excel, and PowerPoint files.
Your files already contain a significant amount of institutional knowledge — strategy decks, QBR materials, policy documents, project briefs. Connecting Microsoft 365 means your agents can read that content directly instead of relying on you to copy and paste it. You ask the agent to summarize a folder, find an outdated policy, or write an exec brief from a deck, and it does the work against your actual files.
Microsoft 365 connects via OAuth through your Microsoft account, giving agents access to OneDrive, SharePoint, and the full Office file suite.
## What Your Agent Can Do
Once Microsoft 365 is connected and enabled:
* **Read Word, Excel, and PowerPoint files** — pull content from OneDrive and SharePoint
* **Browse SharePoint sites** — navigate site libraries and document collections
* **Search across OneDrive** — find files by name or keyword
* **Create and update Word and Excel files** — write outputs back to your file system
* **Summarize spreadsheets** — extract key figures and tables from Excel workbooks
* **Sync to Databases** — pull content into Scout for search
## Connecting Microsoft 365
Go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations) and click **Connect** next to **Microsoft 365**.
You'll be redirected to Microsoft's authorization screen. Sign in with your Microsoft account and approve the permissions:
| Permission | What it's for |
| ----------------- | ----------------------------------------------- |
| `Files.ReadWrite` | Read and write files in OneDrive and SharePoint |
| `Sites.Read.All` | Browse SharePoint sites and their contents |
Back in Scout, Microsoft 365 should show as **Connected** in your integrations list.
Open your agent, go to the **Tools** tab, and toggle on the Microsoft 365 tools. Add path conventions to your agent's **Instructions** using the guardrail below.
## Instruction Guardrails
Without explicit path instructions, an agent writing files will choose its own output location, which makes files hard to find later. This instruction block establishes consistent read and write behavior:
```markdown theme={null}
For file operations:
1. List folders before reading or writing.
2. Use explicit folder paths for outputs (e.g., /reports/weekly/).
3. Keep source files and generated files in separate folders.
4. Return the final file path and name after each write.
```
Add this to your agent's **Instructions** before enabling any write tools.
If your agent frequently creates files, add a naming convention to your instructions: "Name new files as `[YYYY-MM-DD] - [Topic]` and place them in the `/reports/` folder." This keeps your file system organized without manual cleanup.
## Testing Your Integration
Ask your agent to list the files in a specific folder. It should return the contents with file names and types — no writes, no side effects.
Ask it to read a document and summarize it. Verify the summary is accurate and grounded in the actual file content.
If write access is enabled, ask the agent to create a test file with a specific name in a specific folder. Confirm it appears in OneDrive or SharePoint at the correct path.
## Prompt Examples
These prompts work once Microsoft 365 is connected and enabled on your agent:
* "Find policy updates in Microsoft 365 and summarize changes by department."
* "Summarize all the Excel reports in the /finance/Q2 folder and identify key trends."
* "Create a weekly summary doc from these folders and save it to /reports/weekly."
* "List everything in the /contracts folder and flag any files older than 90 days."
## Use Cases
**Research and synthesis** — Ask your agent to read five documents in a folder and produce a structured summary with themes, conflicts, and open questions. The agent does the reading; you focus on the decisions.
**Meeting prep** — Before a QBR or board meeting, ask your agent to pull the relevant decks and reports from SharePoint, summarize the key numbers and narratives, and write a structured pre-read brief. Combine this with calendar context for a complete prep package.
**Executive briefs** — Regularly ask your agent to distill a folder of reports into a one-page brief for leadership. Point it at /reports/weekly in OneDrive, set a naming convention, and let it run on a schedule.
**Document hygiene** — Ask your agent to list files in a folder, identify anything older than a specified threshold, and flag items for review or archival. Useful for keeping SharePoint libraries from accumulating outdated materials.
## Troubleshooting
Agent can't find a file I know exists
Check two things:
* The folder path in your instructions matches exactly — capitalization matters in SharePoint paths
* The file is in a location Scout has access to — personal folders outside a shared site may not be accessible depending on your permissions setup
Agent created a file but I can't find it
Ask your agent: "What path did you save the file to?" and check that location. If it's missing, the agent may have written to a default working folder rather than your intended destination. Add an explicit output path to your agent's instructions to prevent this.
I connected the integration but my agent doesn't see any tools
1. Go to your agent's **Settings** and open the **Tools** section
2. Make sure the Microsoft 365 tools are toggled **on**
3. Confirm the integration shows as **Connected** at [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations)
If it still doesn't work, try disconnecting and reconnecting the integration.
## Next Steps
Connect Google Drive to read and write Docs, Sheets, and Slides for mixed environments.
Combine file content with CRM data for meeting prep and account research.
Pull document context into email drafts and pre-call briefs.
Post document summaries and file-based digests to team channels.
# Microsoft Teams
Source: https://docs.scoutos.com/integrations/microsoft-teams
Integrate Microsoft Teams with Scout to let agents respond to messages, search history, and deliver your daily briefing directly in your channels.
Connecting Teams to Scout lets your agents work where your team already communicates. An agent can post pipeline summaries to a sales channel, summarize a support thread before a rep picks it up, or answer questions in a dedicated help channel. Setup takes about five minutes, and you'll be prompted to connect to Teams directly in Scout.
## What Scout Agents Can Do in Teams
| Capability | Example |
| ----------------------- | ------------------------------------------------------------------ |
| **Post to channels** | Share daily pipeline summaries, incident alerts, or weekly digests |
| **Read threads** | Understand context from a conversation before responding |
| **Search history** | Find past decisions, discussions, or referenced documents |
| **React and reply** | Acknowledge messages and continue in-thread conversations |
| **Respond to mentions** | Answer questions when someone mentions the agent in a channel |
## How to Connect Teams
Go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations), find **Microsoft Teams bot**, and click **Add Connection**. You'll see a pop-up window to a Teams authorization page.
Enter the Teams Tenant ID for the workspace you want to connect, then sign in with your account.
This step must be completed by an admin of your Microsoft Teams tenant.
**Deployments (channel-first)**
Use this when you want the agent to live in a Teams channel, responding and staying in the conversation rather than acting only on demand.
1. Go to your agent's **Settings**
2. Click **+ Add Deployments** → **Teams**
3. In the configuration panel, select your **Teams Workspace** and the **Channel** where the agent should operate
4. Configure the deployment options (see below) and click **+ Add channel** to save
| Option | What it does |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Workspace** | The Teams workspace to deploy to. Must be connected first. |
| **Channels** | The specific channel this deployment monitors and responds in |
| **Threaded context** | Passes prior thread messages to the agent for in-context replies |
| **Respond if** | An optional condition that filters when the agent responds, such as "the user is asking a technical question." Leave blank to respond to all messages. |
| **Additional instructions** | Channel-specific instructions appended to the agent's system prompt, useful for adjusting tone or scope per channel |
If you leave **Respond if** blank, the agent replies to every message in the channel. That's right for a dedicated support bot, but too noisy for a general channel like #general. Use a condition to keep the agent focused.
Scout can only read messages posted *after* it's added to a channel. It won't have access to earlier history. If you need context from past discussions, copy the relevant content into your agent's instructions or a connected knowledge source.
Scout can only be deployed to **public channels**. Private channels are not supported due to Microsoft's permissions model for Teams bots.
## Teams as a Deployment Channel
Some of the most useful Teams setups run on a schedule. Instead of posting only when someone asks, the agent delivers something useful every day on its own.
A few examples of what this looks like in practice:
**Daily pipeline brief.** An agent connected to Salesforce runs each morning, pulls open deals with no activity in the last seven days, and posts a summary to #sales-leadership before standup. The team reviews it instead of pulling a manual report.
**Incident summaries.** An agent monitors #incidents, reads the thread when a new incident is posted, and replies with a structured summary of what's affected, the current status, and the latest update. On-call engineers get context without reading back through a noisy thread.
**Weekly digest.** An agent reads activity across your engineering channels each Friday afternoon, generates a summary of decisions, PRs merged, and open questions, and posts it to #general-engineering before the weekend.
## Instruction Examples
Add channel-specific instructions to your agent so it knows what to post and where:
```markdown theme={null}
For Teams tasks:
1. Post pipeline summaries to #sales-leadership in a bullet list format.
2. Keep posts under 400 words. Use headers for readability.
3. Always mention the data source (e.g., "Source: Salesforce as of [date]").
4. Never post PII or customer contact information to public channels.
5. Use threaded replies rather than new top-level messages when responding in context.
```
## Prompt Examples
These prompts work once Teams is connected and enabled on your agent:
* "Summarize the discussion in #engineering and post the key points to #general."
* "Find messages about the API outage yesterday and create a timeline."
* "Post a weekly digest to #general-engineering based on activity this week."
* "Read the thread in #support about the login issue and propose solutions."
* "Post today's pipeline summary to #sales-leadership using Salesforce data."
## Testing Your Integration
Go to one of your configured channels in Teams, mention the agent or send a message that matches your **Respond if** condition, and verify it replies in the thread.
## Next Steps
Feed Salesforce data into your Teams pipeline summaries.
Post email summaries and follow-up drafts to Teams automatically.
Summarize documents from Drive and post results to channels.
See the full integration stack and recommended connection order.
# Connect Notion to Scout: Agents That Read and Write Your Knowledge Base
Source: https://docs.scoutos.com/integrations/notion
Integrate Notion with Scout so agents can search pages and databases, create documentation, and update records across your knowledge base.
Notion is where many teams keep their runbooks, project briefs, and decision logs. Connecting it to Scout lets your agents work with that knowledge directly — searching existing pages before drafting new ones, generating incident reports into a database, or pulling structured context to ground a response. Setup takes about five minutes and you'll switch to Notion once to authorize the connection.
This page covers the **Notion integration** that lets agents read and write pages and databases as a tool. If you instead want to sync Notion content into a searchable knowledge base, see [Databases sources](/databases/sources).
## What Scout Agents Can Do in Notion
| Capability | Example |
| ------------------------------ | --------------------------------------------------------------- |
| **Search pages and databases** | Find existing runbooks or project briefs to avoid duplicates |
| **Create new pages** | Auto-generate incident reports, meeting notes, or decision logs |
| **Update database entries** | Add rows to a project tracker or update status fields |
| **Read structured content** | Pull context from a Notion database to inform responses |
## How to Connect Notion
Go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations), find **Notion**, and click **Connect**. You'll be redirected to Notion's authorization page.
Choose the workspace you want to connect, then select which pages and databases Scout can access. Click **Allow access** to finish — you'll be redirected back to Scout.
What permissions does Scout request?
| Permission | What it's for |
| -------------- | -------------------------------------- |
| Read content | View page content and database entries |
| Insert content | Create new pages and add database rows |
| Update content | Edit existing pages and modify entries |
Scout only accesses the pages and databases you explicitly share, and you can adjust what's shared at any time.
1. Go to your agent's **Settings**
2. Click **Add Tool** in the Tools section and search for **Notion**
3. In your agent's **Instructions**, specify which databases and pages it should use
```markdown theme={null}
For Notion tasks:
1. When an incident is resolved, create an entry in the Incidents database.
2. Before drafting a new runbook, search existing pages for the same topic.
3. Name new pages as "[Date] - [Topic]" and place them in the correct database.
4. Always return the Notion page URL after creating or updating content.
```
## Prompt Examples
These prompts work once Notion is connected and enabled on your agent:
* "Create a Notion page for this project brief and post the link in Slack."
* "Update the incident runbook database with the steps from this thread."
* "Find pages about the Q1 roadmap and summarize the key initiatives."
* "Check if we already have a runbook for this error type, and create one if not."
## Best Practices
* **Scope access appropriately.** Share only what the agent needs. A single database is safer and easier to reason about than a whole workspace section.
* **Use databases for structured data.** For recurring content like incidents, decisions, or tasks, databases give you a consistent schema and make content far easier to search and filter.
* **Set naming conventions in instructions.** Tell the agent how to name pages — for example `"[Date] - [Topic]"` — and which database to place them in, so content stays organized.
## Testing Your Integration
In Scout chat, ask your agent to search Notion for a topic you know exists. Confirm it returns the right page.
Ask the agent to create a test page, then verify it appears in Notion with the expected content.
Ask the agent to update a database entry and confirm the change in Notion.
## Troubleshooting
Agent can't find a page or database
Open the page or database in Notion, click **Share**, and make sure the Scout integration has access. If it still doesn't appear, disconnect and reconnect Notion in [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations) to re-select which pages and databases Scout can see.
I connected Notion but my agent doesn't see Notion tools
1. Go to your agent's **Tools** tab and make sure the Notion tool is toggled **on**
2. Confirm Notion shows as **Connected** in [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations)
3. If it's still missing, try reconnecting
Agent is creating duplicate pages
Add a search step to your instructions so the agent searches for existing pages on the same topic before creating a new one. For example: `"Before creating a page, search for existing pages on the same topic and update one if it exists."`
Authorization failed or timed out
Disconnect Notion, click **Connect** again, and complete the authorization — making sure you select the correct workspace. Pop-up blockers can interrupt the OAuth redirect, so allow pop-ups for Scout if the flow doesn't complete.
## Next Steps
Post the pages and links your agent creates in Notion straight to a Slack channel.
Sync Notion content into a database so agents can search it as a knowledge base.
Pull context from documents and summarize it into Notion pages.
See the full integration stack and recommended connection order.
# Integrations
Source: https://docs.scoutos.com/integrations/overview
Connect Scout agents to Salesforce, HubSpot, Gmail, Slack, Google Drive, Microsoft 365, and more. One-click OAuth with secure credential storage.
Scout agents become genuinely useful when they can reach the tools your team already lives in. Rather than copying data between tabs or asking your agent to work from memory, you connect your stack once and let agents read, update, and act on live data — from your CRM to your inbox to your file system — without any manual handoffs.
## Available Integrations
| Integration | Category | What agents can do |
| ------------------------------------------------ | -------------- | --------------------------------------------------------- |
| [Salesforce](/integrations/salesforce) | CRM | Read and update opportunities, contacts, tasks, and notes |
| [HubSpot](/integrations/hubspot) | CRM | Manage deals, companies, contacts, and activity timelines |
| [Gmail](/integrations/gmail) | Email | Draft emails, read threads, and triage inboxes |
| [Google Calendar](/integrations/google-calendar) | Calendar | Check schedules, find open slots, and book meetings |
| [Slack](/integrations/slack) | Messaging | Post to channels, read threads, and search history |
| [Microsoft Teams](/integrations/microsoft-teams) | Messaging | Post to channels, read threads, and respond to mentions |
| [Notion](/integrations/notion) | Knowledge base | Read pages, create docs, and update databases |
| [Google Drive](/integrations/google-drive) | Files | Read and summarize documents, spreadsheets, and slides |
| [Microsoft 365](/integrations/microsoft-365) | Files | Work across Word, Excel, SharePoint, and OneDrive |
## How Integrations Work
Every integration follows the same four-step pattern. You connect your account once at the workspace level, then control which agents can use it — keeping each agent scoped to exactly the tools it needs.
Go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations) and click **Connect** next to the integration you want. Most integrations use OAuth, so you'll authorize Scout from your existing account with no passwords to store.
Open any agent in Scout Studio, go to its **Tools** tab, and toggle on the integrations that agent should be able to use. Each agent only sees the tools you explicitly enable — a support agent doesn't need Salesforce write access if it only answers questions.
In the agent's **Instructions**, tell it when and how to use each tool. Guardrails prevent mistakes like writing records without reading them first or sending emails without confirmation.
Before rolling the agent out to your team, run real prompts against live data. Ask it to read a record, draft a message, or summarize a document. Confirm the output before enabling any write actions.
## Priority Order for Connecting
Most teams get the highest return by connecting integrations in this order:
1. **CRM first** — Salesforce or HubSpot data is the foundation for most high-value automations: deal reviews, follow-up drafts, pipeline snapshots.
2. **Email and Calendar** — once your agent knows the CRM context, it can draft outreach and manage scheduling on your behalf.
3. **Slack and Notion** — route insights to where your team communicates and document decisions durably.
4. **Google Drive and Microsoft 365** — give agents access to the files and docs that already capture your institutional knowledge.
## Add Guardrails in Agent Instructions
When you give an agent access to external tools, it can take real action: updating a record, sending a message, booking a meeting. A short instruction block prevents unintended writes and keeps every action auditable.
```markdown theme={null}
When using external integrations:
1. Read before write when possible.
2. Confirm record identity before updates.
3. Return the object ID and action taken after each write.
4. For risky actions (delete, overwrite, bulk update), ask for explicit confirmation.
```
Paste this block at the top of the instructions for any agent that has write access to an external system. You can customize it per integration — the CRM, email, and file pages each include a tailored version.
## Prompt Examples
These prompts work once you have the relevant integrations connected and enabled on your agent:
* "Find open enterprise opportunities in Salesforce and summarize top risks."
* "Check my calendar for next week and draft prep notes in Notion."
* "Post today's pipeline summary to #sales-leadership in Slack."
* "Read QBR docs from Google Drive and create an exec brief."
* "Find all HubSpot deals closing this quarter with no activity in 14 days."
* "Summarize my unread emails and draft replies — don't send yet."
## Explore by Integration
Connect Salesforce and HubSpot so agents can read pipeline data, enrich records, and draft follow-ups grounded in real CRM context.
Give agents access to Gmail to triage inboxes, draft communications, and send follow-ups on your behalf.
Give agents access to Google Calendar to check schedules, find open slots, and book meetings across timezones.
Deploy agents directly into Slack channels to post summaries, respond to messages, and deliver daily briefings where your team works.
Deploy agents directly into Teams channels to post summaries, respond to mentions, and deliver daily briefings where your team works.
Let agents read and summarize Docs, Sheets, and Slides across your Google Drive.
Let agents work across Word, Excel, and PowerPoint files in SharePoint and OneDrive.
# Connect Salesforce to Scout: Quick Connect, OAuth, and JWT
Source: https://docs.scoutos.com/integrations/salesforce
Connect Salesforce to Scout with Quick Connect, a custom OAuth app, or JWT Bearer Flow. Query records with SOQL, manage data, and act as specific users.
Salesforce holds the structured pipeline and account data your agents can act on directly — opportunities, contacts, leads, tasks, and any custom object in your org. Once connected, agents can run SOQL queries, create and update records, and search across objects, all scoped to the authorizing user's permissions. Scout supports both **Production** and **Sandbox** environments.
If your team also uses HubSpot, connect it independently from the [HubSpot integration page](/integrations/hubspot) — an agent can use tools from both CRMs in the same workflow.
## Choosing a Connection Method
Salesforce supports three ways to connect. Pick the one that matches your security requirements.
| Method | Best for |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| **Quick Connect** | Testing and teams without Salesforce admin access — the fastest path |
| **Custom OAuth App** | Enterprise deployments that require their own Connected App and security controls |
| **JWT Bearer Flow** | Server-to-server automation where the agent acts on behalf of a specific user with no interactive login |
## Quick Connect (Recommended)
Quick Connect uses Scout's managed OAuth app, so there's nothing to configure in Salesforce.
Go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations) and click the **Salesforce** card.
Click **Connect with OAuth** and choose your environment — **Production** (login.salesforce.com) or **Sandbox** (test.salesforce.com).
Sign in to Salesforce, review the requested permissions, and click **Allow**. You'll be redirected back to Scout.
Your workspace should show a green status indicator, the environment type, and the connection date.
## Custom OAuth App
Use a custom Connected App when your security team requires Scout to authenticate through credentials you own and control.
**Prerequisites:** Available across Group through Developer editions, in both Classic and Lightning. You need either `Customize Application` + `Modify All Data`, or `Customize Application` + `Manage Connected Apps`.
In Salesforce, go to **Setup → External Client App Settings** and turn on the option to allow creation of connected apps. This is a one-time setting per org.
Click the gear icon → **Setup → App Manager → New Connected App**.
Enter a connected app name, contact email, and (optionally) a logo URL, info URL, and description (256 characters max). The API name fills in automatically.
Turn on OAuth and configure:
* **Callback URL:** `https://studio.scoutos.com/oauth/salesforce/success`
* **Scopes:** Full access (`full`), Access the identity URL service, Manage user data via APIs (`api`), Manage user data via Web browsers (`web`), and Perform requests at any time (`refresh_token`, `offline_access`)
* Enable **Client Credentials Flow** and **Authorization Code and Credentials Flow**
* Require a secret for the **Web Server Flow** and **Refresh Token Flow**
Copy the **Consumer Key** (Client ID), then reveal and copy the **Consumer Secret** (Client Secret).
On the Salesforce card, click **Add Workspace**, check **Use custom Salesforce Connected App credentials**, select your environment, enter your Client ID and Client Secret, and click **Connect with OAuth**.
Salesforce can take a few minutes to activate a newly created Connected App. If authorization fails immediately after setup, wait a few minutes and try again.
## JWT Bearer Flow (User-Scoped)
JWT Bearer Flow uses certificate-based authentication so Scout can act as a specific user without an interactive login. It's ideal for scheduled and background jobs.
**Why use it:**
* No user interaction required — authentication happens automatically
* Access is scoped to a specific user
* Uses cryptographic signing instead of stored passwords
* Well suited to scheduled agents and server-to-server automation
Use OpenSSL to generate an RSA private key, a certificate signing request, and a self-signed certificate valid for 365 days:
```bash theme={null}
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr
openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
```
Keep `server.key` secure — anyone with it can authenticate as the connected user.
Go to **App Manager → New External Client App** and fill in the basics (set **Distribution State** to Local). Enable OAuth, set the callback URL to any HTTPS URL, and add the scopes `api` and `refresh_token, offline_access`. Enable **JWT Bearer Flow** and upload your `server.crt`.
Open **External Client App Manager → Policies → Edit**. Set **Permitted Users** to "Admin approved users are pre-authorized" and **IP Relaxation** to "Relax IP restrictions", then add the profiles or permission sets that should be allowed. Only pre-authorized users can authenticate.
Open the app, go to the **OAuth Settings** tab, and copy the **Consumer Key**.
On the **Salesforce (User Scoped)** card, click **Add Workspace** and complete the checklist. Paste your Consumer Key and the full PEM private key (including its headers), select your environment, and click **Create Connection**. Confirm the workspace shows a green status.
### JWT Troubleshooting
| Issue | Solution |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| Invalid JWT token | Verify the key matches the uploaded certificate and is in PEM format with the correct headers |
| User not pre-authorized | Add the user's profile or permission set to the approved list |
| Certificate expired | Generate a new certificate and key, upload to Salesforce, and update the key in Scout |
| Invalid client identifier | Verify the correct Consumer Key and ensure the app is active |
### JWT Security Best Practices
* Protect your private key and never commit it to source control
* Rotate certificates regularly (typically yearly)
* Grant the minimum permissions the agent needs
* Use separate apps for Production and Sandbox
* Monitor usage logs for unexpected activity
## Verify the Connection
Open an agent, go to the **Tools** tab, and toggle Salesforce on. Then test with a prompt:
* "List the last 5 accounts from Salesforce."
* "Find the contact with email [jane@example.com](mailto:jane@example.com)."
* "Get opportunity by ID and summarize its stage and next steps."
* "How many open opportunities do we have this quarter?"
The authorizing user's Salesforce permissions apply. If a user can't read a field or object in Salesforce, the agent can't either. Check field-level security in Salesforce Setup if the agent returns incomplete records.
## Available Capabilities
Once connected and enabled, your agent can:
| Category | Capabilities |
| ----------------------- | ---------------------------------------------------------------- |
| **Data querying** | SOQL queries, SOSL search, list objects, get field metadata |
| **Record management** | Get a record by ID, create, update, and delete records |
| **Advanced operations** | Direct REST API calls, bulk operations, and relationship queries |
## Instruction Guardrails
CRM writes are consequential. A bad update can corrupt a record, create a duplicate, or overwrite data another rep entered. Add this block to your agent's **Instructions** before enabling any write tools:
```markdown theme={null}
For CRM tasks:
1. Look up the record before writing.
2. Match by stable identifier (record ID, email, domain) before updates.
3. Return the CRM object ID, fields changed, and reason after each write.
4. Ask before creating duplicates when confidence is low.
```
## Troubleshooting
| Issue | Solution |
| -------------------------------------- | -------------------------------------------------------------------------------------- |
| No permission to create Connected Apps | Contact your admin or use a free Developer Edition org |
| Invalid client credentials | Verify the Consumer Key and Secret were copied correctly |
| Redirect URI mismatch | The callback URL must be exactly `https://studio.scoutos.com/oauth/salesforce/success` |
| User hasn't approved the app | Sign in as an authorized user and check app approval for the profile |
| Authentication failure | Verify you're using the correct environment (Production vs. Sandbox) |
| Token expired | Open the Salesforce integration in Scout and click **Reconnect** |
| Insufficient privileges | Ensure proper permissions and object/field-level security |
| API limit exceeded | Monitor usage in **System Overview** and optimize your queries |
## Next Steps
Connect HubSpot too — agents can use Salesforce and HubSpot tools in the same workflow.
Route pipeline summaries and deal alerts from Salesforce to team channels.
Add email context to Salesforce-driven outreach workflows.
See the full integration stack and recommended connection order.
# Connect Slack to Scout: Agents That Work Where You Do
Source: https://docs.scoutos.com/integrations/slack
Integrate Slack with Scout to let agents post summaries, respond to messages, search history, and deliver your daily briefing directly to a channel.
Most teams don't want another dashboard to check. Connecting Slack to Scout lets your agents work where your team already communicates — posting pipeline summaries to a sales channel, summarizing a support thread before a rep picks it up, or responding to questions in a dedicated help channel. Setup takes about five minutes and you'll switch between Scout and Slack once to authorize the connection.
## What Scout Agents Can Do in Slack
| Capability | Example |
| ----------------------- | ------------------------------------------------------------------ |
| **Post to channels** | Share daily pipeline summaries, incident alerts, or weekly digests |
| **Read threads** | Understand context from a conversation before responding |
| **Search history** | Find past decisions, discussions, or referenced documents |
| **React and reply** | Acknowledge messages and continue in-thread conversations |
| **Respond to mentions** | Answer questions when someone mentions the agent in a channel |
## How to Connect Slack
Go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations), find **Slack**, and click **Connect**. You'll be redirected to Slack's authorization page.
Select the Slack workspace you want to connect, review the permissions Scout requests, and click **Allow**. You'll be redirected back to Scout when the authorization is complete.
What permissions does Scout request?
| Permission | What it's for |
| ------------------ | --------------------------------- |
| `channels:history` | Read messages in public channels |
| `groups:history` | Read messages in private channels |
| `chat:write` | Post messages to channels |
| `channels:read` | List available channels |
| `groups:read` | List private channels |
| `users:read` | Look up user information |
| `reactions:write` | Add emoji reactions to messages |
Scout only accesses channels you explicitly add it to in Step 4.
Choose how you want your agent to work in Slack — as a **tool** it uses on demand, or as a **deployment** that lives persistently in a channel.
**Option A: Tools + Instructions (flexible)**
Use this when you want the agent to post to or read from Slack as part of a broader workflow, but not actively monitor conversations.
1. Go to your agent's **Settings**
2. Click **Add Tool** in the Tools section and search for **Slack**
3. In your agent's **Instructions**, specify which channels it can access:
```
You can access the following Slack channels:
- #sales-leadership — for posting pipeline summaries
- #engineering — for technical discussion summaries
- #alerts — for posting incident updates
```
**Option B: Deployments (channel-first)**
Use this when you want the agent to live in a Slack channel — listening, responding, and staying in the conversation rather than acting only on demand.
1. Go to your agent's **Settings**
2. Click **+ Add Deployments** → **Slack**
3. In the configuration panel, select your **Workspace** and the **Channel** where the agent should operate
4. Configure the deployment options (see below) and click **+ Add channel** to save
| Option | What it does |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace** | The Slack workspace to deploy to — must be connected first |
| **Channels** | The specific channel this deployment monitors and responds in |
| **Threaded context** | Passes prior thread messages to the agent for in-context replies |
| **Respond if** | An optional condition that filters when the agent responds — e.g., "the user is asking a technical question." Leave blank to respond to all messages. |
| **Additional instructions** | Channel-specific instructions appended to the agent's system prompt — useful for adjusting tone or scope per channel |
If you leave **Respond if** blank, the agent replies to every message in the channel. That's right for a dedicated support bot, but too noisy for a general channel like #general. Use a condition to keep the agent focused.
This step is the most commonly skipped. Even after connecting and configuring everything in Scout, your agent cannot see any channel until you invite it in Slack.
For each channel where you want Scout to work, go to that channel in Slack and run:
```
/invite @Scout
```
Or open the channel, click the channel name at the top, go to **Integrations → Add apps**, search for "Scout," and click **Add**. Repeat for every channel your agent needs to access.
Scout can only read messages posted *after* it's added to a channel. It won't have access to earlier history. If you need context from past discussions, copy the relevant content into your agent's instructions or a connected knowledge source.
## Slack as a Deployment Channel
The most powerful Slack use case isn't an agent that occasionally posts — it's an agent that runs on a schedule and delivers something useful every day without being prompted.
A few examples of what this looks like in practice:
**Daily pipeline brief** — An agent connected to Salesforce runs each morning, pulls open deals with no activity in the last seven days, and posts a summary to #sales-leadership before standup. The team reviews it asynchronously instead of pulling a manual report.
**Incident summaries** — An agent monitors #incidents, reads the thread when a new incident is posted, and replies with a structured summary: what's affected, current status, and the latest update. On-call engineers get context without reading back through a noisy thread.
**Weekly digest** — An agent reads activity across your engineering channels each Friday afternoon, generates a summary of decisions, PRs merged, and open questions, and posts it to #general-engineering before the weekend.
## Instruction Examples
Add channel-specific instructions to your agent so it knows what to post and where:
```markdown theme={null}
For Slack tasks:
1. Post pipeline summaries to #sales-leadership in a bullet list format.
2. Keep posts under 400 words. Use headers for readability.
3. Always mention the data source (e.g., "Source: Salesforce as of [date]").
4. Never post PII or customer contact information to public channels.
5. Use threaded replies rather than new top-level messages when responding in context.
```
## Prompt Examples
These prompts work once Slack is connected and enabled on your agent:
* "Summarize the discussion in #engineering and post the key points to #general."
* "Find messages about the API outage yesterday and create a timeline."
* "Post a weekly digest to #general-engineering based on activity this week."
* "Read the thread in #support about the login issue and propose solutions."
* "Post today's pipeline summary to #sales-leadership — use Salesforce data."
## Testing Your Integration
In Scout chat, ask your agent to post a test message to a channel. Verify the message appears in Slack with the correct formatting.
Ask your agent to summarize the last five messages in a channel. Confirm it returns the correct content.
Go to one of your configured channels in Slack, mention the agent or send a message that matches your **Respond if** condition, and verify it replies in the thread.
## Troubleshooting
Agent says it can't access a channel
Scout needs to be added to each channel individually. Go to the channel in Slack and run `/invite @Scout`. Also check that:
* You're in the workspace you connected (not a different one)
* The channel name in your instructions matches exactly, including capitalization
* For Deployments: the channel is listed in your deployment configuration in Scout Studio
Agent can't read replies to its messages
Scout can only read messages posted after it was added to the channel. Historical messages aren't accessible. For new threads, make sure Scout is in the channel before the conversation starts.
I connected Slack but my agent doesn't see Slack tools
1. Go to your agent's **Tools** tab
2. Make sure the Slack tools are toggled **on**
3. Confirm Slack shows as **Connected** in [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations)
Deployment isn't responding in Slack
Check in order:
1. Go to your agent's **Settings → Deployments** and confirm the Slack deployment exists and the channel is listed
2. Run `/invite @Scout` in the channel if you haven't already
3. If you set a **Respond if** condition, confirm your test message meets it
4. Check that your agent is published and not in draft mode
My Slack workspace isn't showing up during authorization
If you're signed into multiple Slack workspaces, make sure you select the correct one. To fix a wrong workspace: go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations), disconnect Slack, click **Connect** again, and select the right workspace.
## Next Steps
Feed Salesforce and HubSpot data into your Slack pipeline summaries.
Post email summaries and follow-up drafts to Slack automatically.
Summarize documents from Drive or SharePoint and post results to channels.
See the full integration stack and recommended connection order.
# Introduction
Source: https://docs.scoutos.com/introduction
Scout is an agentic workforce studio for building and deploying autonomous AI agents. Automate workflows and get real work done at scale.
Scout is a platform where you can build and deploy autonomous AI agents that handle real business tasks — from customer support and research to document processing and CRM hygiene — without constant human oversight.
Build your first AI agent in under five minutes with a pre-built template.
Understand the platform, core components, and what makes Scout different.
Learn about agents, workflows, databases, and the Scout data model.
Dive deep into building intelligent agents that adapt and take action.
## What Can You Build?
Scout agents are already handling real workloads across teams:
* **Customer Support** — Resolve tickets, look up account history, and escalate urgent issues automatically
* **Research & Analysis** — Gather competitive intel, summarize findings, and generate polished reports
* **Document Processing** — Extract data from PDFs, update CRM records, and automate paperwork pipelines
* **Knowledge Assistance** — Answer questions from your internal docs, wikis, and databases
* **Workflow Automation** — Connect your tools and run multi-step processes on a schedule or trigger
## Core Building Blocks
| Component | What It Does |
| ---------------------- | -------------------------------------------------------------------------------------- |
| **Agents** | Execute tasks using instructions, planning, and tool calls — autonomously and at scale |
| **Workflows** | Orchestrate repeatable multi-step automations with conditional logic and triggers |
| **Integrations** | Connect Salesforce, HubSpot, Slack, Notion, email, calendar, and more |
| **Databases & Tables** | Store structured data with semantic and hybrid retrieval for your agents |
| **Drive** | Manage files, folders, and generated artifacts for agents and workflows |
| **Skills** | Package reusable capabilities and tool guidance that agents can call on |
## Where to Begin
Head to [Scout Studio](https://studio.scoutos.com) and pick a template from the Agent Marketplace. Your agent is live in minutes.
Open [Integrations](/integrations/overview) to connect Salesforce, Slack, Notion, Gmail, and more. Agents get one-click access to everything.
Use [Workflows](/workflows/overview) to chain agents, tools, and logic into reliable, event-driven automations that run without manual intervention.
Use the [Python or TypeScript SDK](/agents/getting-started) to run agents programmatically, or call the REST API directly for full control.
Questions or feedback? Reach the Scout team at [support@scoutos.com](mailto:support@scoutos.com).
# MCP Server
Source: https://docs.scoutos.com/mcp-server/index
Scout MCP is a hosted [Model Context Protocol](https://modelcontextprotocol.io/specification/latest) server that gives MCP-compatible clients access to Scout over HTTP. Clients connect directly to Scout's hosted MCP endpoint and use Scout through standard MCP tool calls — without installing or running a separate local server.
Scout MCP is designed for MCP-compatible IDEs, agents, and developer tools that support remote HTTP MCP servers.
![A translucent Scout MCP Server card with the Scout asterisk mark]()
## Setup
To connect a client, you'll need:
* **MCP endpoint:** `https://mcp.scoutos.com/mcp`
* **HTTP header:** `Authorization: Bearer YOUR_SCOUT_TOKEN`
Scout MCP uses **JSON-RPC 2.0 over Streamable HTTP**.
For credentials, use a Scout private key or a signed JWT in the `Authorization` header. Prefer a short-lived signed JWT when possible. Create or copy a key from [Settings → API Keys](/settings/api-keys).
If your client only supports local stdio MCP servers and not remote HTTP MCP servers, you may need a bridge or a different client.
## Connect your client
Configure your MCP client to connect to `https://mcp.scoutos.com/mcp` and include `Authorization: Bearer YOUR_SCOUT_TOKEN` with requests.
### Claude
Claude supports custom connectors using remote MCP servers. To connect Scout, configure it with:
* **Name:** `Scout`
* **Server URL:** `https://mcp.scoutos.com/mcp`
* **Header:** `Authorization: Bearer YOUR_SCOUT_TOKEN`
After saving the connector, confirm Scout's tools appear in Claude.
### Claude Code
```bash theme={null}
claude mcp add --transport http scout https://mcp.scoutos.com/mcp
```
If Claude Code supports custom auth headers in your environment, add your Scout bearer token in the MCP server configuration:
```json theme={null}
{
"mcpServers": {
"scout": {
"url": "https://mcp.scoutos.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_SCOUT_TOKEN"
}
}
}
}
```
After adding the server, reload MCP connections in Claude Code and verify Scout's tools are discovered.
### Codex
```bash theme={null}
codex mcp add scout --url https://mcp.scoutos.com/mcp
```
If needed, configure it directly in `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.scout]
url = "https://mcp.scoutos.com/mcp"
[mcp_servers.scout.headers]
Authorization = "Bearer YOUR_SCOUT_TOKEN"
```
If your Codex install requires remote MCP support to be enabled, make sure the relevant MCP feature flag is turned on first.
### Cursor
Add a custom MCP server in Cursor using Scout's hosted endpoint:
```json theme={null}
{
"mcpServers": {
"scout": {
"url": "https://mcp.scoutos.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_SCOUT_TOKEN"
}
}
}
}
```
After saving the configuration, reload Cursor's MCP tools and confirm the Scout server is active.
### Visual Studio Code
If you're using a VS Code MCP extension or MCP-compatible setup that supports remote HTTP servers, configure Scout like this:
```json theme={null}
{
"mcpServers": {
"scout": {
"url": "https://mcp.scoutos.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_SCOUT_TOKEN"
}
}
}
}
```
If your MCP extension only supports command-based local servers, you may need a bridge layer or a client that supports remote MCP natively.
### v0 by Vercel
If your v0 environment supports connecting a custom MCP server, use:
* **Name:** `Scout`
* **URL:** `https://mcp.scoutos.com/mcp`
* **Header:** `Authorization: Bearer YOUR_SCOUT_TOKEN`
If the interface accepts JSON configuration, use:
```json theme={null}
{
"mcpServers": {
"scout": {
"url": "https://mcp.scoutos.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_SCOUT_TOKEN"
}
}
}
}
```
## Verify the connection
After connecting, your client should automatically discover Scout's available MCP tools.
A quick smoke test is to ask:
```text theme={null}
List my Scout workflows.
```
```text theme={null}
Show my Scout agents.
```
If the client connects successfully but no tools appear, reload the MCP server configuration and confirm your bearer token is valid.
## Tools
Scout MCP exposes the following tool groups:
| Tool group | What it covers |
| ------------- | ------------------------------------------------------------- |
| **Agents** | List, upsert, and interact with Scout agents. |
| **Databases** | Create, inspect, update, and delete databases and views. |
| **Tables** | Manage tables and schemas inside databases. |
| **Documents** | Create, list, update, delete, and batch-edit table documents. |
| **Workflows** | List, inspect, create, and run Scout workflows. |
| **Triggers** | List, create, update, delete, and execute Scout triggers. |
| **Drive** | Upload and download files in Scout Drive. |
## Example usage
Once Scout MCP is connected, here are practical things you can ask your client to do.
### Explore your workspace
```text theme={null}
List my Scout workflows and explain what each one does.
```
```text theme={null}
Show my databases and summarize which tables look customer-related.
```
```text theme={null}
Find the agent named "SDR Assistant" and show its current configuration.
```
### Run and debug workflows
```text theme={null}
Run workflow wf_abc123 with this sample payload and summarize the output:
{ "company": "Acme Corp", "contact_email": "hello@acme.com" }
```
```text theme={null}
Check recent Scout run logs and surface any failures from today.
Show me the error details for any failed runs.
```
### Manage data
```text theme={null}
Upload this CSV to Scout Drive and then sync it to the customers table.
```
```text theme={null}
Create a new database called "Support Tickets" with a table that has
columns: ticket_id, status, priority, and summary.
```
### Work with triggers
```text theme={null}
List all my Scout triggers. Which ones are active?
```
```text theme={null}
Update the Slack trigger on workflow wf_abc123 to only respond
in the #support channel.
```
## Per-call headers
When a Scout agent calls an MCP-backed tool, it can supply request headers for a single call through a reserved `headers` input. These headers are merged over the connection's base auth headers and aren't forwarded as normal tool arguments. Paired with [Variables](/agents/variables), header values can reference non-sensitive interaction data such as tenant or workspace routing metadata:
```json theme={null}
{
"headers": {
"X-Tenant": "{{tenant.id}}",
"X-Workspace": "{{workspace_id}}"
}
}
```
Use per-call headers only for non-sensitive, request-specific metadata such as tenant, workspace, locale, or routing values. Configure standing credentials in the MCP connection's base headers. Do not put environment-variable references or credentials in agent-authored per-call headers. See [Variables](/agents/variables) for the security model and runtime syntax.
## FAQ
No. Scout MCP is a protocol layer on top of Scout's existing APIs. It exists to make Scout easier to use from MCP-compatible clients.
The default hosted model is designed around client-provided bearer tokens that are passed upstream to Scout APIs.
Yes. The hosted service is exposed publicly at the network layer, while protected access is enforced through Scout authentication.
The current documented surface includes Agents, Tables, Databases, Documents, Workflows, Triggers, and Drive.
## Troubleshooting
| Issue | What to check |
| -------------------------------------------- | --------------------------------------------------------------------------- |
| Client says the server is unreachable | Confirm the endpoint is exactly `https://mcp.scoutos.com/mcp`. |
| Authentication fails | Verify the `Authorization: Bearer YOUR_SCOUT_TOKEN` header is being sent. |
| Server connects but no tools appear | Refresh MCP discovery or reload the client. |
| Client only supports OAuth connector flows | Use the custom MCP server option instead. |
| Client only supports local stdio MCP servers | Use a remote-compatible client or a bridge/proxy approach. |
| Tool calls fail after connecting | Confirm the bearer token has access to the Scout resources being requested. |
## References
Create and manage the credentials you use to authenticate Scout MCP.
Full reference for the Scout HTTP API.
Reference interaction-scoped values in tool inputs and MCP per-call metadata.
The open standard Scout MCP implements for client-to-service communication.
# API Keys: Authenticate Your Scout Integrations Securely
Source: https://docs.scoutos.com/settings/api-keys
Create and manage Scout API keys (Org Credentials) to authenticate REST API calls, SDK clients, and CI/CD pipelines. Rotate without downtime.
API keys let you authenticate programmatic requests to Scout. Whether you're building an integration, connecting a service to Scout, or running automated workflows from a CI/CD pipeline, you need an API key. Scout gives you fine-grained control over your keys: create multiple per organization, name them by purpose, toggle them on and off, and rotate them without downtime.
## Two Types of Credentials
Scout provides two types of API credentials:
The modern, recommended credential type. Asymmetric key pairs you can create in any quantity, name by purpose, enable or disable, and rotate safely.
Older single-key credentials that continue to work. Org Credentials replace them with more flexibility and security options.
### Org Credentials vs. Legacy Keys
| Feature | Legacy Key | Org Credentials |
| ----------------------------- | ---------- | --------------- |
| Multiple keys per org | No | Yes |
| Enable / disable toggle | No | Yes |
| Key rotation without downtime | No | Yes |
| Named keys | No | Yes |
| Asymmetric key pair | No | Yes |
| Assigned role | No | Yes |
Org Credentials are asymmetric key pairs. When using bearer token authentication, use the **private key** portion of your Org Credential as the token value. You can view and copy it at any time from Scout Studio.
## Creating an API Key
### Who can manage keys
Owners and Admins can open **Settings → API Keys** and create or manage keys. Editors and Members cannot. See [Roles](/settings/roles) for what each role can do.
### Steps
Open the workspace switcher, choose **Settings**, then choose **API Keys**.
Click **Create New Key** to open the **Add a key pair** modal.
Enter a descriptive name that tells you what this key is for six months from now — for example, `prod-api-server`, `github-actions-deploy`, or `staging-tests`.
Assign a role to the key. The key can only perform actions that role allows. You can assign a system role or a [custom role](/settings/roles).
Click **Save**. Your new key is active immediately. The key pair (public and private) appears in your keys list.
Each key row in the list shows:
* **Name** and assigned role
* **Public key** — masked by default; use the eye icon to reveal or the copy icon to copy
* **Private key** — masked by default; use the eye icon to reveal or the copy icon to copy
* **Enable / disable toggle** — suspend access without deleting the key
* **Actions menu (⋮)** — rename, rotate, or delete
Scout does not re-display the private key after you navigate away from the creation screen. If you lose it, create a new key and rotate your applications to use it.
## Using API Keys
Scout API keys support two authentication methods. Both use the `Authorization: Bearer` header. Choose based on your security requirements.
| Method | What you send | Best for |
| ------------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
| **Private key as Bearer token** | The private key string directly | Quick scripts, internal tools, local testing |
| **Signed JWT** | A short-lived JWT signed with the private key | Production integrations, anything that handles sensitive data |
In both cases, the key's role determines what operations are permitted.
***
### Method 1: Private Key as Bearer Token
Use the private key string exactly as shown in Settings as your Bearer token.
```bash cURL theme={null}
curl -X GET "https://api.scoutos.com/v2/workflows" \
-H "Authorization: Bearer YOUR_PRIVATE_KEY"
```
```python Python theme={null}
from scout import Scout
client = Scout(api_key="YOUR_PRIVATE_KEY")
```
```typescript TypeScript theme={null}
import Scout from "scoutos";
const client = new Scout({ apiKey: "YOUR_PRIVATE_KEY" });
```
The private key travels over the network on every request when you use this method. Use it only over TLS (HTTPS). For persistent or production integrations, use the signed JWT method below — the private key never leaves your environment.
***
### Method 2: Signed JWT
Sign a short-lived JWT locally with the private key and send that as the Bearer token. Scout verifies the signature against the stored public key. The private key never leaves your environment.
#### Step 1: Convert the key to PEM format
Scout keys are stored as base64url-encoded DER. Most JWT libraries expect PEM format. Run this conversion once at startup.
```javascript theme={null}
// key-utils.js
export function derToPem(base64urlDer, type = 'PRIVATE KEY') {
const b64 = base64urlDer
.replace(/-/g, '+')
.replace(/_/g, '/')
.padEnd(base64urlDer.length + (4 - base64urlDer.length % 4) % 4, '=');
const lines = b64.match(/.{1,64}/g).join('\n');
const sep = '-----';
return `${sep}BEGIN ${type}${sep}\n${lines}\n${sep}END ${type}${sep}`;
}
```
```python theme={null}
# key_utils.py
import base64
def der_to_pem(base64url_der: str, key_type: str = "PRIVATE KEY") -> str:
padded = base64url_der + "=" * (4 - len(base64url_der) % 4)
der_bytes = base64.urlsafe_b64decode(padded)
b64 = base64.b64encode(der_bytes).decode()
lines = "\n".join(b64[i:i+64] for i in range(0, len(b64), 64))
sep = "-----"
return f"{sep}BEGIN {key_type}{sep}\n{lines}\n{sep}END {key_type}{sep}"
```
If your JWT signing call throws a key parsing error, a missing PEM conversion is almost always the cause.
#### Step 2: Sign and send the JWT
```javascript theme={null}
import jwt from 'jsonwebtoken';
import { derToPem } from './key-utils.js';
const keyPem = derToPem(process.env.SCOUT_PRIVATE_KEY);
const CREDENTIAL_ID = process.env.SCOUT_CREDENTIAL_ID;
const KID = process.env.SCOUT_KID; // shown in Settings → API Keys
function makeToken() {
const now = Math.floor(Date.now() / 1000);
return jwt.sign(
{ iss: 'scout', sub: CREDENTIAL_ID, iat: now, exp: now + 300 },
keyPem,
{ algorithm: 'RS256', header: { alg: 'RS256', kid: KID } }
);
}
const res = await fetch('https://api.scoutos.com/v2/workflows', {
headers: { Authorization: `Bearer ${makeToken()}` },
});
```
```python theme={null}
import jwt, time, os, requests
from key_utils import der_to_pem
key_pem = der_to_pem(os.environ["SCOUT_PRIVATE_KEY"])
CREDENTIAL_ID = os.environ["SCOUT_CREDENTIAL_ID"]
KID = os.environ["SCOUT_KID"] # shown in Settings → API Keys
def make_token():
now = int(time.time())
return jwt.encode(
{ "iss": "scout", "sub": CREDENTIAL_ID, "iat": now, "exp": now + 300 },
key_pem,
algorithm="RS256",
headers={ "kid": KID }
)
res = requests.get(
"https://api.scoutos.com/v2/workflows",
headers={ "Authorization": f"Bearer {make_token()}" }
)
```
Generate a token once per process startup and cache it in memory. Regenerate it when fewer than 30 seconds remain before expiry. Tokens are valid for 5 minutes (300 seconds).
#### JWT Claims Reference
| Claim | Required | Value |
| ----- | -------- | ------------------------------------------------------------------- |
| `iss` | Yes | Must be the string `scout` |
| `sub` | Yes | Your credential ID, shown in Settings → API Keys |
| `iat` | Yes | Current Unix timestamp in seconds |
| `exp` | No | Expiry Unix timestamp. Maximum 300 seconds after `iat`. |
| `kid` | Header | RFC 7638 thumbprint of the public key, shown in Settings → API Keys |
***
### Authentication Troubleshooting
| Error | Check |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | The key is disabled or deleted. Confirm it is enabled in Settings → API Keys. Verify you are using the **private** key, not the public key. |
| `403 Forbidden` | The key is valid but lacks permission for this operation. Check the role assigned to the key. |
| JWT parse error | The key needs PEM conversion before use with a JWT library. Follow Step 1 above. |
## Managing Keys
### Enabling and Disabling a Key
Disable a key temporarily without deleting it — useful for suspending access during a security review or pausing an integration.
1. Go to **Settings** → **API Keys**.
2. Find the key and toggle the **Enabled** switch off.
Disabled keys return `401 Unauthorized` on all requests. Re-enable at any time by toggling it back on.
### Rotating Keys
Because Org Credentials support multiple active keys, you can rotate without downtime:
Create a new key with a version suffix (e.g., `prod-api-v2`).
Update your application or secrets manager to use the new private key.
Confirm the new key is working in all affected services.
Disable the old key and monitor for unexpected `401` errors.
Once you confirm no service depends on the old key, delete it.
### Deleting Keys
Deleting a key is **permanent**. Any service using that key immediately receives `401 Unauthorized` errors.
1. Go to **Settings** → **API Keys**.
2. Click the **Actions menu (⋮)** → **Delete**.
3. Confirm the deletion in the dialog.
Always disable a key and monitor for errors before permanently deleting it.
## Security Best Practices
Treat API keys like passwords. Follow these practices to reduce risk:
* **Never commit keys to source control.** Use `.gitignore` to exclude `.env` files. Use tools like [git-secrets](https://github.com/awslabs/git-secrets) or pre-commit hooks to scan for accidental commits.
* **Use one key per service or environment.** Separate keys for production, staging, CI/CD, and local development let you revoke access for one system without affecting others.
* **Use descriptive names.** Names like `prod-api-server` or `github-actions-deploy` make it easy to audit which key is used where.
* **Rotate keys on a schedule.** Quarterly rotation is a reasonable baseline for most teams.
* **Disable before you delete.** Disabling first lets you confirm no active service depends on a key before permanently removing it.
* **Store keys in a secrets manager.** Prefer AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, or Doppler over plain environment files in production.
* **Audit access regularly.** Review your active keys and remove any that are no longer in use.
### Multi-Key Strategy
Use separate keys for each environment and integration:
| Key Name | Purpose | Environment |
| ----------------- | -------------------------- | ----------- |
| `prod-api-server` | Main production backend | Production |
| `prod-cicd` | GitHub Actions deployments | Production |
| `staging-api` | Staging and QA testing | Staging |
| `dev-local` | Local development | Development |
This pattern lets you rotate or revoke one key without disrupting unrelated services.
## Key Management Troubleshooting
| Error | Likely Cause | Solution |
| ------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Key is disabled, deleted, or copied incorrectly | Confirm the key is enabled in Settings. Re-copy the private key from Scout Studio. |
| `403 Forbidden` | Key doesn't have permission for this resource | Confirm your organization has access to the feature you are calling. Check the key's role. |
| Key not appearing in Settings | Session or membership issue | Refresh the page. Verify you are logged into the correct organization. |
| Requests failing after rotation | Old key still in use somewhere | Search your codebase and secrets manager for references to the old key. Check CI/CD environment variables. |
| Private key only shown once | Expected behavior | Scout does not re-display the private key after creation. If lost, create a new key and rotate your applications to use it. |
## Migrating from Legacy Keys
Legacy Keys continue to work and Scout will provide advance notice before any deprecation. When you're ready to migrate:
Create a new Org Credential for each service or use case that currently uses a Legacy Key.
Update your applications and environment variables to use the new private keys.
Confirm all services are working correctly with the new credentials.
Disable the Legacy Key and monitor for errors over the next 24 hours.
Once you confirm no service depends on it, delete the Legacy Key.
## Upcoming Features
**Audit Trail** will provide a time-stamped log of every key creation, rotation, disable, and delete event, useful for compliance reviews and incident response. This feature is in active development.
To limit what a key can do, assign it a role with the permissions you want. See [Roles](/settings/roles).
## Next Steps
Understand system roles and custom roles, including what a key can do.
Configure Skills to authenticate with your API key via the `SCOUT_API_KEY` environment variable.
Use your API key to authenticate the Scout MCP server for coding agent access.
Full reference for all Scout REST API endpoints you can authenticate with your key.
# Billing: Understand Scout Plans and Agent Pricing
Source: https://docs.scoutos.com/settings/billing
Understand how Scout billing works — plan-level pricing and limits, plus Agent pricing based on the underlying LLM cost plus a 5% platform fee.
Scout billing has two parts: your **plan**, which sets the features and usage limits available to your organization, and **Agent usage**, which is metered on the underlying LLM cost of the work your agents do. This page explains both so you can predict and understand your bill.
Only **Owners** can open **Settings → Billing** and change the plan. If you don't see Billing, ask an Owner. See [Roles](/settings/roles).
## Plans
Scout offers a Free plan to get started and a Scale plan for teams that need higher limits and dedicated support. Current plan pricing and limits are shown on [scoutos.com/pricing](https://www.scoutos.com/pricing).
**\$0/month.** Try Scout and build with the full platform on a single seat with starter limits.
**Custom pricing.** Higher and custom limits, unlimited seats, and dedicated support with an SLA. [Talk with a Scout engineer](https://www.scoutos.com/pricing).
### Plan Limits
The Free plan includes a fixed set of limits. Scale plans are customized per workspace to fit the scale and support your team needs.
| Limit | Free | Scale |
| ---------------- | ---------- | -------------------------- |
| Seats | 1 | Unlimited |
| Agent messages | 200 | Custom |
| Active workflows | 3 | Custom |
| Workflow runs | 50 / month | Custom |
| Storage | 1 GB | Custom |
| Integrations | 2 | Custom |
| Log retention | 1 hour | 3 day window |
| Support | Community | Dedicated support with SLA |
Plan pricing and limits on [scoutos.com/pricing](https://www.scoutos.com/pricing) are the source of truth. If a limit on your account differs, it reflects a custom Scale agreement.
## Agent Pricing
Agent usage is billed on the **underlying LLM cost of the work your agents do, plus a 5% platform fee**. There is no flat per-agent or per-message fee for this usage — you pay for the tokens your agents actually consume.
**Billed Agent cost = provider LLM cost × 1.05**
The underlying LLM cost is the amount charged by the model provider (for example, OpenAI or Anthropic) for the input and output tokens processed on a given run. Scout meters this usage per model and applies a 5% markup to arrive at the amount billed to you.
Because pricing is metered on real token usage, your Agent cost scales with:
* **How often your agents run** — more runs mean more tokens processed.
* **Which model each agent uses** — providers charge different rates per model. See [Model Management](/settings/model-management) to control which models your team can use.
* **How much context each run processes** — longer instructions, larger inputs, and more tool output all increase token counts.
### Example
Suppose an agent run processes tokens that cost **\$0.40** at the model provider's published rates. Scout applies the 5% platform fee:
```
Provider LLM cost: $0.40
Platform fee (5%): $0.02
Billed Agent cost: $0.42
```
Your bill for that run is **\$0.42**. The same run on a lower-cost model would cost proportionally less, since the fee is always 5% of the underlying LLM cost.
## How Usage Becomes Your Bill
Your final billed amount combines the two parts of Scout billing:
Your plan sets your features and usage limits. The Free plan is \$0/month; Scale pricing is agreed with the Scout team.
Scout meters the underlying LLM cost of your agent runs per model and adds the 5% platform fee.
Your bill is your plan cost plus metered Agent usage for the period.
### Plan Limits and Agent Usage
Plan limits and Agent usage pricing are separate. Limits such as agent messages, workflow runs, and storage govern what your plan allows; Agent pricing meters the LLM cost of the work that runs within those limits. Metered Agent usage is billed in addition to your plan.
To keep Agent costs predictable, use [Model Management](/settings/model-management) to restrict your organization to approved, cost-efficient models and set a sensible org-wide default.
Questions about your plan, limits, or a specific charge? Reach the Scout team at [support@scoutos.com](mailto:support@scoutos.com).
## Next Steps
See who can manage billing and other workspace settings.
Control which models your team can use to keep Agent costs predictable.
Monitor agent runs and usage to understand what drives your costs.
# Model Management: Control AI Models Across Your Organization
Source: https://docs.scoutos.com/settings/model-management
Enable provider models, set an org-wide default, and restrict agents to approved models in Scout Studio. Owners control model access for the whole team.
Model Management gives your organization control over which AI models your team can access in Scout Studio. Owners enable models by provider, choose an org-wide default, and keep agents restricted to approved, cost-effective options. These settings apply org-wide and govern which models appear everywhere models are used, including the agent editor.
![The Settings > Models page showing a Default chat model dropdown above a provider list with enabled counts]()
## Where to Find It
In Scout Studio, open the workspace switcher and choose **Settings**, then choose **Models**.
These settings apply org-wide, and only **Owners** can enable, disable, or change defaults. If you don't see editable controls, ask an Owner to make the change. See [Roles](/settings/roles).
## Enabling Models
Models are grouped by provider. Each provider row shows how many of its models are enabled versus the total available (for example, **OpenAI 3/10**).
Open the workspace switcher, choose **Settings**, then choose **Models**.
Click a provider to reveal its individual models.
Switch on each model you want available to your team.
To narrow the list, filter by type using the **All**, **Completion**, and **Image** tabs, or search by model name or provider. Enabled models become usable in agents right away.
## Setting a Default Model
The org default is pre-selected for new chats unless an agent overrides it. A cost-efficient model is recommended for the default so everyday usage stays predictable.
Open the workspace switcher, choose **Settings**, then choose **Models**.
Under **Default chat model**, open the dropdown.
Choose the model to use as the organization default.
The chosen model pre-fills new chats and serves as the starting option in the agent editor.
## How It Affects Agents
The agent editor's model picker only shows **enabled** models, with the org default pre-selected. Anyone who can edit an agent can still choose any other enabled option. This lets you:
* Restrict agents to vetted, approved models
* Keep costs predictable by limiting the available choices
* Set an efficient default while keeping powerful models available for specific needs
* Adjust models on existing agents individually or in bulk
## Disabling a Model
When you disable a model that's used by agents or workflows, Scout shows how many items are affected and requires you to choose a replacement before the model can be disabled. Affected agents continue running until a replacement is applied.
![The disable-model confirmation modal with a replacement model picker and a count of affected items]()
You have two replacement options:
Apply a single replacement model to every affected item, then click **Replace & disable**.
Open a table to assign a different replacement per item, then click **Disable**.
Choosing **Review individually** opens a table listing each affected item with its own replacement dropdown, so you can map different models per agent before disabling.
![The per-item review table listing affected agents, each with its own replacement model dropdown]()
Confirm your replacements before closing the dialog. The model is only disabled once a replacement has been applied to the affected items.
## Troubleshooting
| Issue | Likely cause | Solution |
| ------------------------------------------ | --------------------------------- | --------------------------------------------------- |
| Model not appearing in agent editor | Not enabled for the org | Go to **Settings** → **Models** and toggle it on |
| Cannot change settings | You are not an Owner | Ask an Owner to make the change |
| Default model not pre-selected | Browser cache | Hard refresh (`Cmd+Shift+R` / `Ctrl+Shift+R`) |
| Agent using the wrong model after a change | Agent has a pinned model override | Open the agent editor and update the model directly |
## Next Steps
See who can change Models and other workspace settings.
Create and manage credentials to authenticate your Scout integrations.
Build agents that use your approved models in the agent editor.
# Roles
Source: https://docs.scoutos.com/settings/roles
Understand Scout's system roles, create custom roles, and assign them to members from Settings.
Roles control what each person in your workspace can see and do. Scout includes four system roles. Owners can also create custom roles with a specific set of permissions.
## Open the Roles page
In Scout Studio, open the workspace switcher and choose **Settings**, then choose **Roles**.
![The Settings > Roles page with a permissions search field, an Owner role selected, and a list of resources with access levels]()
**Owners** can create, edit, and delete custom roles. **Admins** can open the same page and review every role, but cannot change them. If you don't see **Roles** in Settings, ask an Admin or Owner to review access for you.
Pick a role from the dropdown. System roles and custom roles appear in separate groups. Use **Search permissions...** to filter the list. Each row is a resource, with granted actions on the left and an access level on the right (**View**, **Edit**, **Full access**).
System roles include a short summary of how they build on the role below them. For **Owner**, that reads **Everything Admin can do, plus 10 additions.** You cannot edit those levels on a system role.
## System roles
You cannot edit or delete the four system roles. Each role includes everything the role below it can do, plus more.
| Role | Who it's for | What they can do |
| ---------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner** | People who own the workspace | Full access, including billing, models, organization settings, members, and roles. Every workspace must keep at least one Owner. |
| **Admin** | People who administer the workspace | Manage members, API keys, environment variables, and org usage. View roles. Cannot change billing, models, organization settings, or custom roles. |
| **Editor** | People who build in Scout | Create and edit agents, workflows, databases, and Drive files. Cannot manage workspace settings or members. |
| **Member** | People who use existing work | View and run shared agents and workflows. View databases. View and download Drive files. Cannot create or edit those resources, and cannot open workspace settings. |
Assign **Member** to people who should run agents without changing them. Assign **Editor** to people who should author agents and workflows.
## Create a custom role
Only an Owner can create a custom role. Custom roles do not inherit from a system role.
![The Create role dialog with Name, optional Description, Quick start chips, and a searchable permissions list]()
Open the workspace switcher, choose **Settings**, then choose **Roles**.
Click **New Role**. The **Create role** dialog opens.
Enter a **Name** (required), for example `Support Agent`. Add an optional **Description**.
Use a **Quick start** chip (**Read-only**, **Editor**, or **Full access**) to apply a starting set, then check or uncheck individual permissions. Search to find a resource. The footer shows how many permissions are selected.
Click **Create role**. The button stays disabled until the role has a name and at least one permission. The new role appears in the role dropdown and is ready to assign on **Members**.
### Permission levels
For each resource, choose a level. Switch to **Custom** if you need to pick exact actions.
| Level | Grants |
| --------------- | ------------------------------------------- |
| **No access** | Nothing on that resource |
| **View** | Read and list |
| **Edit** | Create and update, but not delete or manage |
| **Full access** | Every action on that resource |
| **Custom** | The exact actions you check |
On the Roles page, Owners can change these levels inline for a custom role. Scout saves after a short pause and shows **Changes saved**. System roles stay read-only.
To rename a custom role or change its permissions in the dialog, open the **⋯** menu and choose **Edit role**.
## Delete a custom role
Open **⋯** on a custom role and choose **Delete role**. Confirm in the dialog.
Members still assigned that role lose the permissions it granted. This cannot be undone. If they still need access, assign a different role on **Settings → Members** first.
## Assign roles to members
Owners and Admins assign roles from **Settings → Members**. You can set a role when you invite someone, and you can change it later for an existing member or a pending invite.
### Invite someone with a role
Open the workspace switcher, choose **Settings**, then choose **Members**.
Click **Add Member**.
Select the system or custom role they should receive.
Enter their email and send the invitation. They join with that role when they accept.
### Change a member or invite role
On **Settings → Members**, open the actions menu on a person or pending invite and choose **Edit role**. Pick the new role and save.
You cannot change your own role. Ask another Admin or Owner to update it. You also cannot remove or demote the last Owner in the workspace.
## Who can do what on Roles and Members
| Action | Owner | Admin | Editor / Member |
| ------------------------------------ | ----- | --------------- | --------------- |
| Open **Settings → Roles** | Yes | Yes (view only) | No |
| Create, edit, or delete custom roles | Yes | No | No |
| Open **Settings → Members** | Yes | Yes | No |
| Invite people and assign roles | Yes | Yes | No |
## Troubleshooting
| Issue | What to do |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| **Roles** is missing from Settings | You need Admin or Owner. Ask an Owner to change your role on **Members**. |
| You can open Roles but there is no **New Role** button | You are viewing as Admin. Ask an Owner to create or edit custom roles. |
| Permission dropdowns are not editable | System roles are read-only. Select a custom role, or create one if you are an Owner. |
| Can't change your own role | Open **Members** as a different Admin or Owner, then use **Edit role** on your row. |
| Can't remove or demote an Owner | The workspace must keep at least one Owner. Promote someone else first. |
## Next steps
Create credentials for integrations and pipelines. Admins and Owners manage keys.
Owners control which models the workspace can use.
Owners manage plan and usage billing.
# Available Scout Skills: scout and scout-workflow Pack
Source: https://docs.scoutos.com/skills/available-skills
Explore the two official Scout Skills: the scout skill for platform API access and scout-workflow for running and managing workflow automations.
Scout ships two official, production-ready Skills in the [`scoutos/scout-skills`](https://github.com/scoutos/scout-skills) repository. The `scout` Skill covers Scout's core data and platform APIs, while `scout-workflow` covers workflow execution and management. Install both with a single command and your agents immediately gain access to the full Scout platform.
## Install the Official Skill Pack
Install both Skills from GitHub using the Scout Skills CLI:
```bash theme={null}
npx skills add scoutos/scout-skills
```
Then set your API key so the Skills can authenticate with the Scout API:
```bash theme={null}
export SCOUT_API_KEY="your-api-key-here"
```
Get your API key from [Scout Studio](https://app.scoutos.com) → **Settings** → **API Keys**. Both Skills read `SCOUT_API_KEY` automatically as a Bearer token — no additional configuration required.
***
## The `scout` Skill
Use the `scout` Skill when your task involves data operations in Scout: reading and writing databases, managing documents, uploading files, or monitoring usage.
### Capabilities
| Feature | Description |
| ------------- | ------------------------------------------------------------------------------------- |
| **Databases** | Create, list, update, and delete top-level data containers |
| **Tables** | Manage structured data with custom schemas (text, number, select, datetime, and more) |
| **Documents** | Full CRUD on table records with bulk insert support |
| **Agents** | List agents and invoke them programmatically |
| **Drive** | Upload and download files to Scout storage |
| **Syncs** | Sync data from external sources including websites, Notion, Google Drive, and more |
| **Usage** | Query API usage metrics and quotas for your organization |
### Sync Sources
The `scout` Skill can configure data syncs from a wide range of external sources:
| Source | Archetype ID | Best for |
| --------------- | --------------------------- | ------------------------------------------------------ |
| Website Crawler | `com.scoutos.website` | General documentation sites and public content |
| Sitemap | `com.scoutos.sitemap` | Sites with a comprehensive `sitemap.xml` |
| Crawl | `com.scoutos.crawl` | Multi-page crawls across linked pages |
| Page Crawl | `com.scoutos.page_crawl` | Single-page content extraction |
| Notion | `com.notion.notion` | Internal wikis, pages, and databases |
| Google Drive | `com.google.drive` | Google Docs and Drive folders |
| Microsoft 365 | `com.microsoft.365` | SharePoint and OneDrive |
| Laserfiche | `com.laserfiche.repository` | Laserfiche document repositories |
| Guided Crawl | `com.scoutos.guided_crawl` | Sites requiring login or complex JavaScript navigation |
### Example Prompts
When an agent has the `scout` Skill enabled, you can ask it:
* "List all my databases and their tables."
* "Search the knowledge base for documents about API design."
* "Create a new table called Tasks with columns for title, status, and due date."
* "Upload this PDF to Drive and make it searchable."
* "Set up a sync from our Notion docs to the knowledge base database."
* "Show me API usage for this month."
### API Examples
```bash List Databases theme={null}
curl -H "Authorization: Bearer $SCOUT_API_KEY" \
"https://api.scoutos.com/v2/collections"
```
```bash Create Documents (Bulk) theme={null}
curl -X POST \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{"title": "Task 1", "completed": false},
{"title": "Task 2", "completed": true}
]' \
"https://api.scoutos.com/v2/collections/{col_id}/tables/{tbl_id}/documents"
```
```bash Configure a Website Sync theme={null}
curl -X POST \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sync_config": {
"source_settings": {
"source_archetype_id": "com.scoutos.website",
"start_urls": ["https://docs.example.com"],
"max_depth": 3,
"max_page_count": 100
},
"destination": {
"destination_type": "collections.v2",
"collection_id": "col_abc123",
"table_id": "tbl_xyz789"
}
}
}' \
"https://api.scoutos.com/v2/syncs"
```
```bash Upload a File to Drive theme={null}
curl -X POST \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-F "files=@report.pdf" \
"https://api.scoutos.com/drive/upload"
```
***
## The `scout-workflow` Skill
Use the `scout-workflow` Skill when your task involves creating, running, or deploying Scout workflows. This Skill handles everything from triggering a single run to streaming long-running workflow output in real time.
### Capabilities
| Feature | Description |
| ------------------------- | ---------------------------------------------------------------------------- |
| **Workflow execution** | Trigger runs via `POST /v2/workflows/{workflow_id}/execute` |
| **Streaming runs** | Consume real-time streaming output for long-running jobs |
| **Revisions** | Create runs against specific workflow revisions and inspect revision history |
| **SDK support** | Python and TypeScript patterns for programmatic workflow execution |
| **CLI workflows as code** | Local run and deployment via `scout workflows` commands |
### Execution Environments
The `scout-workflow` Skill supports four execution environments:
| Environment | Use case |
| ------------- | -------------------------------- |
| `production` | Live production runs (default) |
| `staging` | Pre-production testing |
| `development` | Active development and iteration |
| `console` | Interactive console testing |
### Example Prompts
When an agent has the `scout-workflow` Skill enabled, you can ask it:
* "Run workflow `wf_abc123` with these inputs."
* "Execute the lead-enrichment workflow in staging with this contact payload."
* "Stream workflow output so I can monitor progress in real time."
* "List all revisions for workflow `wf_abc123` and tell me what changed."
* "Deploy this workflow definition using the Scout CLI."
### API Example
```bash Execute a Workflow theme={null}
curl -X POST "https://api.scoutos.com/v2/workflows/wf_abc123/execute?environment=production" \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inputs": {
"user_message": "Generate a weekly summary"
},
"streaming": false
}'
```
```bash Execute with Streaming theme={null}
curl -X POST "https://api.scoutos.com/v2/workflows/wf_abc123/execute?environment=production" \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inputs": {
"user_message": "Analyze this dataset and produce a full report"
},
"streaming": true
}'
```
***
## Using Both Skills Together
An agent can have both Skills active at the same time. It automatically routes to the right Skill based on the task. For example:
| Prompt | Skill used |
| ----------------------------------------------------------------- | ----------------------------- |
| "List all documents in the `customers` database." | `scout` |
| "Run the `onboarding-workflow` for this new user." | `scout-workflow` |
| "Upload this file to Drive, then trigger the ingestion workflow." | `scout` then `scout-workflow` |
| "Search the knowledge base and summarize the top results." | `scout` |
| "Stream the `report-generator` workflow output." | `scout-workflow` |
***
## Additional Resources
Browse the full source for both official Skills, including complete SKILL.md files and tool definitions.
Full reference for all Scout API endpoints used by the official Skills.
Build a Skill for any API or service your agents need.
Learn how Skills work and why they make agents more reliable.
# Build and Install Custom Scout Skills for Your Agents
Source: https://docs.scoutos.com/skills/creating-skills
Build custom Scout Skills for any API or service your agents need. Define a SKILL.md with execution guidance and error handling for reliability.
Custom Skills let you give agents a consistent, reusable playbook for any API or service your team depends on. Rather than re-explaining how to interact with a service in every conversation or agent config, you define the behavior once in a `SKILL.md` file — and the agent uses it reliably every time the request matches.
## When to Create a Custom Skill
Build a custom Skill when:
* Your agents need to call an internal or third-party API that isn't covered by an official Skill.
* You find yourself writing the same tool instructions in multiple agent configs.
* An agent is making inconsistent API calls that a clear playbook would fix.
* You want to share a capability across your team or publish it for others to use.
For Scout platform operations and workflow execution, the official [`scoutos/scout-skills`](/skills/available-skills) pack already covers what you need. Custom Skills are for everything outside of that.
## The SKILL.md Format
A Skill is a directory containing a `SKILL.md` file. The file has two parts: a YAML frontmatter block and a free-form Markdown instruction body.
```
my-skill/
├── SKILL.md # Agent instructions (required)
└── skill.json # Tool definitions and metadata (optional)
```
### Frontmatter
The frontmatter defines the Skill's identity and — most importantly — its activation criteria:
```yaml theme={null}
---
name: my-custom-skill
description: >
Use this skill when the user asks about X, Y, or Z.
Describe the trigger conditions clearly — the agent
reads this to decide whether to activate the skill.
---
```
Write the `description` from the agent's perspective: "Use this skill when…" — not as a general summary of what the Skill does. The agent reads this field to decide whether to load the Skill for a given request. Vague descriptions lead to missed activations or false positives.
### Instruction Body Sections
The body is free-form Markdown. Structure it with these sections for best results:
A short list of what the Skill can do. Helps the agent understand the Skill's scope.
Explicit trigger conditions. Be precise about the user requests that should activate this Skill.
Each tool or endpoint with method, URL, and parameters. The agent follows this exactly.
Required credentials and the environment variable names that hold them.
Concrete user prompts and the expected agent action. Include the most common cases.
HTTP error codes and what the agent should do for each. Don't leave the agent to guess.
## Complete Example: Weather Skill
Here is a full `SKILL.md` for a hypothetical weather API integration. Use it as a template for your own Skills.
````markdown theme={null}
---
name: weather-skill
description: >
Use this skill when the user asks about weather, forecasts,
temperature, rain, or climate conditions for any location.
---
# Weather Skill
Retrieve current weather conditions and multi-day forecasts for any city worldwide.
## Capabilities
- Get current conditions: temperature, humidity, wind speed
- Retrieve 7-day forecasts
- Check active weather alerts
## When to Use
Use this skill when the user:
- Asks about current weather or conditions in a location
- Wants a forecast ("tomorrow", "this week", "next weekend")
- Mentions rain, snow, temperature, or similar weather terms
- Is planning travel and wants weather information
Do not use this skill for climate history, long-range predictions beyond 7 days,
or questions about non-weather environmental conditions.
## Available Tools
### get_current_weather
Fetches real-time conditions for a location.
- Method: `GET`
- URL: `https://api.weather.example.com/current`
- Parameters:
- `location` (required): City name or lat/lng coordinates
- `units` (optional): `metric` or `imperial` (default: `metric`)
- Headers:
- `Authorization: Bearer ${WEATHER_API_KEY}`
### get_forecast
Fetches a multi-day forecast.
- Method: `GET`
- URL: `https://api.weather.example.com/forecast`
- Parameters:
- `location` (required): City name or coordinates
- `days` (optional): Number of days, 1–7 (default: `3`)
- Headers:
- `Authorization: Bearer ${WEATHER_API_KEY}`
## Authentication
This skill requires an API key from weather.example.com.
1. Sign up at https://weather.example.com/signup
2. Copy your API key from Settings → API Keys
3. Export it in your shell or `.env` file:
```bash
export WEATHER_API_KEY=your-api-key-here
````
## Usage Examples
**User**: "What's the weather in San Francisco right now?"
**Action**: Call `get_current_weather` with `location: "San Francisco"`.
Present temperature, conditions, and humidity in a friendly summary.
***
**User**: "Should I bring an umbrella to Seattle this week?"
**Action**: Call `get_forecast` with `location: "Seattle"` and `days: 7`.
Check for rain probability and advise accordingly.
***
**User**: "What's the temperature in Tokyo in Fahrenheit?"
**Action**: Call `get_current_weather` with `location: "Tokyo"` and `units: "imperial"`.
## Error Handling
* **401 Unauthorized**: The API key is missing or invalid. Ask the user to verify
that `WEATHER_API_KEY` is set correctly.
* **404 Not Found**: The location wasn't recognized. Ask the user to clarify
or try a nearby major city.
* **429 Rate Limited**: Too many requests. Wait a few seconds and retry once.
Inform the user if the retry also fails.
* **Network errors**: Inform the user the service is temporarily unavailable
and suggest trying again shortly.
```
## Folder Layout
Keep your Skills organized in a `skills/` directory in your project:
```
your-project/
└── skills/
├── weather-skill/
│ ├── SKILL.md
│ └── skill.json # optional tool definitions
├── crm-search/
│ └── SKILL.md
└── internal-api/
├── SKILL.md
└── README.md
````
Use lowercase names with hyphens for Skill directory names (e.g., `weather-lookup`, `crm-search`, `slack-notifier`).
## Adding Tool Definitions (Optional)
For Skills that call HTTP endpoints, you can define tools explicitly in a `skill.json` file. This gives the agent structured access to each endpoint with typed parameters.
```json
{
"name": "weather-skill",
"version": "1.0.0",
"tools": [
{
"name": "get_current_weather",
"description": "Get current weather conditions for a location",
"type": "http",
"method": "GET",
"url": "https://api.weather.example.com/current",
"headers": {
"Authorization": "Bearer ${WEATHER_API_KEY}"
},
"parameters": {
"location": {
"type": "string",
"description": "City name or lat/lng coordinates",
"required": true
},
"units": {
"type": "string",
"description": "metric or imperial",
"required": false,
"default": "metric"
}
}
},
{
"name": "get_forecast",
"description": "Get a multi-day weather forecast",
"type": "http",
"method": "GET",
"url": "https://api.weather.example.com/forecast",
"headers": {
"Authorization": "Bearer ${WEATHER_API_KEY}"
},
"parameters": {
"location": {
"type": "string",
"required": true
},
"days": {
"type": "integer",
"description": "Number of forecast days (1-7)",
"required": false,
"default": 3
}
}
}
]
}
````
Use `${VAR_NAME}` syntax anywhere in `skill.json` to reference environment variables at runtime:
```json theme={null}
{
"headers": {
"Authorization": "Bearer ${MY_SERVICE_API_KEY}",
"X-Tenant-ID": "${TENANT_ID}"
}
}
```
## Installing Your Skill
Once your files are ready, install the Skill so your agents can use it:
```bash theme={null}
# Install from a local directory
npx skills add ./skills/weather-skill
# Install from a GitHub repository
npx skills add your-org/weather-skill
# List all installed skills
npx skills list
# Remove a skill
npx skills remove weather-skill
```
## Testing Your Skill
Before sharing your Skill, test it with the exact phrases real users will say. A Skill that works for "weather in London" but not "will it rain tomorrow in London?" has a trigger description problem.
```bash theme={null}
npx skills add ./skills/your-skill-name
```
Try at least five different phrasings of requests the Skill should handle. Confirm the agent activates the Skill for each one.
Try prompts that should NOT activate the Skill. Confirm the agent doesn't load it for unrelated requests.
Temporarily set an invalid API key and confirm the agent responds as your Error Handling section documents.
Every time you edit `SKILL.md`, reinstall the Skill:
```bash theme={null}
npx skills add ./skills/your-skill-name
```
## Best Practices
### Write trigger-focused descriptions
The frontmatter `description` is how the agent decides to activate your Skill. Write it as activation criteria, not marketing copy.
```yaml Good theme={null}
description: >
Use when the user asks about weather, temperature, forecasts,
rain, snow, or climate conditions for any city or location.
```
```yaml Too vague theme={null}
description: Handles weather data for locations.
```
### Be explicit about which tool to call
Don't make the agent guess which tool to call. Spell it out in your Usage Examples:
```markdown theme={null}
**User**: "Is it going to rain in Paris this weekend?"
**Action**: Call `get_forecast` with `location: "Paris"` and `days: 3`.
Check the `precipitation_probability` field and advise accordingly.
```
### Keep instructions actionable
Every instruction should describe an action, not a concept:
| Vague | Actionable |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| "This skill handles weather data." | "When the user asks about weather, extract the location, call `get_current_weather`, and summarize temperature and conditions." |
| "Handle errors appropriately." | "On 404, ask the user to clarify the location or try a nearby major city." |
### One Skill per domain
Resist combining unrelated capabilities into one Skill. An agent that has a "weather and CRM and billing" Skill will activate it incorrectly. Keep each Skill focused on a single domain or service.
## Sharing Your Skill
You can share Skills in three ways:
Push your Skill directory to a public or private repo. Others install with `npx skills add org/skill-name`.
Best for versioned releases with changelogs and semver tags.
Paste the Skill directory to teammates for quick sharing in a monorepo or shared workspace.
To publish to GitHub:
1. Create a repository with your Skill files at the root.
2. Add a `README.md` with installation instructions and example prompts.
3. Tag releases with semantic versions (e.g., `v1.0.0`).
Your teammates install it with:
```bash theme={null}
npx skills add your-org/your-skill-name
```
## Troubleshooting
| Issue | What to check |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent doesn't activate the Skill | The description doesn't match the user's phrasing. Add the exact words and synonyms users say to the `description` frontmatter, then reinstall. |
| Agent activates but does the wrong thing | Add more prescriptive instructions to `SKILL.md`. Tell the agent exactly which tool to call and what to do with the response. Add an example covering the failing case. |
| Authentication errors at runtime | Run `echo $YOUR_API_KEY` to confirm the variable is exported. Check that the variable name in `skill.json` matches exactly. Restart your agent session after setting new variables. |
| Skill installs but doesn't appear in `npx skills list` | Confirm the `name` field in your frontmatter matches what you expect. The list uses the frontmatter `name`, not the directory name. |
| Tool calls return unexpected errors | Add an Error Handling section to `SKILL.md` that covers the specific HTTP status codes your API returns. The agent will follow those instructions when errors occur. |
## Reference
Use the official Scout Skills repository as a model for structure and style. The `scout` and `scout-workflow` Skills demonstrate well-written trigger descriptions, authentication setup, and concrete endpoint documentation with parameters:
* Repository: [github.com/scoutos/scout-skills](https://github.com/scoutos/scout-skills)
Learn how Skills load, route, and execute inside an agent's context.
Explore the official Scout and Scout Workflow Skills as reference implementations.
# Skills
Source: https://docs.scoutos.com/skills/overview
Scout Skills are reusable instruction bundles that give agents reliable capabilities. Build once, share across agents, and keep prompts clean.
Scout Skills give your agents focused, reliable capabilities they can load on demand. Instead of hoping an agent improvises correctly when it encounters an API it hasn't seen before, you hand it a tested playbook that covers exactly which endpoints to call, how to authenticate, and how to handle errors — every single time.
## What is a Skill?
A Scout Skill is a reusable instruction bundle that lives in its own folder. At its core is a `SKILL.md` file that teaches an agent everything it needs to know about a specific capability. The agent reads this file at startup and uses it to decide when and how to act.
Each `SKILL.md` contains three things:
A name and description in frontmatter so the agent can identify the skill and decide when to invoke it.
What to do, when to do it, and how to handle errors — a complete playbook for the capability.
API endpoints, authentication requirements, payload shapes, and usage examples the agent follows directly.
Think of a Skill as a specialist you can hand to any agent. The agent doesn't need to figure out the API from scratch — the Skill already knows it.
## Why Use Skills?
### Consistent, predictable behavior
Without a Skill, agents can improvise in ways that are hard to predict or debug. A Skill gives them a tested playbook with clear rules:
* **Clear triggers** — The agent knows exactly when to use the Skill vs. when to skip it.
* **Correct API patterns** — The agent follows known endpoints and payload shapes instead of guessing.
* **Safer execution** — Auth, rate limits, and failure handling are all documented up front.
For example, instead of an agent constructing a Scout API call from scratch and potentially getting the payload wrong, the `scout` Skill tells it precisely how to query a database, create a document, or trigger a workflow run.
### Build once, use everywhere
Skills are designed for reuse across your entire agent fleet:
* Share the same Skill across multiple agents without duplicating instructions.
* Update a capability in one place and every agent that uses it benefits immediately.
* Compose focused Skills — one for Scout core APIs, another for workflow execution, another for a third-party integration.
### Keep agent prompts clean
When every tool's documentation lives in the agent prompt, it gets unwieldy fast. Skills let you separate concerns:
* Complex tool instructions live in the Skill, not in the agent config.
* Agents reference the Skill by name — short and readable.
* You can update or swap Skills without touching agent configurations at all.
## How Skills Work
When an agent has access to a Skill, here is the flow from request to response:
The Skill's `SKILL.md` is added to the agent's context window at startup.
The agent reads the Skill's description and decides whether it matches the current request.
The agent follows the Skill's instructions and calls the appropriate tool or API endpoint.
The agent returns results and handles errors or follow-up actions exactly as the Skill documents.
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Agent │────▶│ Skill │────▶│ Tools │
│ │ │ (SKILL.md) │ │ (APIs) │
└─────────────┘ └─────────────┘ └─────────────┘
│ │
└────────────────────────────────────────┘
Results flow back
```
The agent stays in control of the conversation — the Skill just tells it what to do when a particular capability is needed.
## Skill Structure
### The SKILL.md file
Every Skill is defined by a `SKILL.md` file. The file has two parts: a YAML frontmatter block and a free-form Markdown instruction body. Here is what a well-structured Skill looks like:
```markdown theme={null}
---
name: my-skill
description: What this skill does and when to use it. Be specific — this is how
the agent decides whether to invoke the skill.
---
# Skill Instructions
## When to use this skill
Describe the user requests or situations that should trigger this skill.
## Available tools and endpoints
List the APIs, endpoints, or tools this skill exposes.
## Authentication
Explain what credentials are required and how to pass them.
## Usage examples
Show concrete request/response patterns the agent should follow.
## Error handling
Document common errors and how the agent should respond to them.
```
A good `description` in the frontmatter is the single most important line in your Skill. It's what the agent reads to decide whether a given request should use this Skill. Write it as activation criteria: "Use this skill when the user asks about X, Y, or Z."
### Folder layout
A Skill lives in its own directory alongside its `SKILL.md`:
```
my-skill/
SKILL.md # The instruction file (required)
README.md # Optional: human-readable docs
```
Multiple Skills can live in the same repository, which makes it easy to install a whole capability set in one command.
## Official Scout Skills
The `scoutos/scout-skills` repository provides two production-ready Skills you can install immediately.
Covers the full Scout platform API: Databases, Tables, Documents, Agents, Drive, Syncs, and Usage metrics.
Covers workflow execution: trigger runs, stream real-time output, inspect revision history, and manage workflows as code.
### `scout`
The `scout` Skill gives your agent access to Scout's core data and platform APIs:
| Capability | What it covers |
| ---------------------- | --------------------------------------------------------- |
| **Databases** | Create, list, query, and delete top-level data containers |
| **Tables & Documents** | Full CRUD on structured data, including bulk insert |
| **Agents** | List and invoke agents programmatically |
| **Drive** | Upload and retrieve files from Scout storage |
| **Syncs** | Trigger and monitor data sync jobs from external sources |
| **Usage** | Query usage metrics and quotas for your organization |
### `scout-workflow`
The `scout-workflow` Skill gives your agent full control over workflow execution and management:
| Capability | What it covers |
| ------------------------- | --------------------------------------------------------- |
| **Run workflows** | Trigger workflow runs with input payloads |
| **Stream runs** | Consume real-time streaming output from long-running runs |
| **Revisions** | List and inspect workflow revision history |
| **CLI workflows as code** | Manage workflow definitions from your terminal |
Browse the source at [github.com/scoutos/scout-skills](https://github.com/scoutos/scout-skills).
## Installation
Install Skills using the Scout Skills CLI. The following command installs both official Scout Skills from GitHub:
```bash theme={null}
npx skills add scoutos/scout-skills
```
After installation, your agents load Skills by name and automatically pick the right one based on the task:
* "List all documents in the `customers` database" → uses `scout`
* "Run the `onboarding-workflow` with this user data" → uses `scout-workflow`
You can also install Skills from any GitHub repository using the same `org/repo` format:
```bash theme={null}
npx skills add your-org/your-custom-skill
```
## Authentication
Most Scout Skills call authenticated APIs. Set up your API key before running any Skill:
Navigate to **Settings → API Keys** in Scout Studio.
Click **Create New Key**, give it a descriptive name (e.g., `agent-skills`), and save it.
Copy your private key and export it in your shell or `.env` file:
```bash theme={null}
export SCOUT_API_KEY="your-api-key-here"
```
Both the `scout` and `scout-workflow` Skills use `SCOUT_API_KEY` as a Bearer token automatically. Never hardcode credentials in a Skill or agent configuration.
Store API keys in environment variables or a secrets manager — never in source code, Skill files, or agent configs. Anyone with access to a private key can make authenticated requests on behalf of your organization.
## Practical Examples
### Example 1: Querying a Scout database
Give an agent the `scout` Skill and ask:
> "Find all customers with a plan tier of 'enterprise' in the customers database."
The agent uses the Skill to construct the correct API call, handles pagination, and returns formatted results — without you having to explain anything about the Scout API.
### Example 2: Triggering a workflow run
Give an agent the `scout-workflow` Skill and ask:
> "Run the lead-enrichment workflow for this new contact: name=Jane Doe, email=[jane@example.com](mailto:jane@example.com)"
The agent uses the Skill to invoke the workflow with the right payload shape and reports back with the run ID and status.
### Example 3: Using Skills in a multi-agent setup
You have a coordinator agent that delegates to specialized sub-agents. One sub-agent gets the `scout` Skill for data access, another gets `scout-workflow` for automation. Each agent stays focused on what it knows, and the coordinator routes requests to the right one.
## Next Steps
Explore the official `scout` and `scout-workflow` Skills in detail, with example prompts and API references.
Build a custom Skill for any API or service your agents need.
# Workflow Blocks: The Building Blocks of Scout Automation
Source: https://docs.scoutos.com/workflows/blocks
Learn how to use Scout workflow blocks — Action, Agent, Condition, Transform, and more — to build powerful, data-driven automations with branching logic.
Blocks are the units of execution in a Scout workflow. Each block takes inputs, performs exactly one job, and produces structured output that downstream blocks can reference. Chain them together and you get a workflow that's easy to read, test, and debug — because every step is isolated and inspectable on its own.
## How Blocks Work
Every block has three parts:
* **Inputs** — values from the workflow's trigger payload or a prior block's output
* **Config** — the block's settings, such as a prompt, a URL, a condition expression, or a transformation rule
* **Output** — a structured result the next block can reference by name
Reference any prior block's output using double-brace syntax:
```
{{ block_id.output }}
```
For example, if you have an LLM block with the ID `classify_ticket`, the next block reads its result as `{{ classify_ticket.output }}`. You can also reference nested fields: `{{ classify_ticket.output.urgency }}`.
Here is a simple three-block chain to illustrate the pattern:
```
Input Block → accepts {{ inputs.user_query }} from the caller
LLM Block → uses {{ inputs.user_query }} in its prompt; ID: summarize
Text/Output Block → shapes the final response using {{ summarize.output }}
```
Name your blocks by what they do, not the tool they use. `fetch_customer` is more readable than `http_1` when you're tracing a failure in the logs six months later.
## Block Types
### Input and Output Blocks
Defines the runtime payload fields that callers must provide when triggering the workflow. Every workflow starts with an Input block.
Shapes or transforms data into a clean output format. Use this to restructure an API response or format a final return value.
Calls any external REST API and returns the response body. Use this for any API that doesn't have a dedicated integration block.
Persists workflow output to a Scout Database Table for later retrieval or search by agents and other workflows.
### AI Processing Blocks
Generates text, answers questions, extracts structured data, or classifies inputs. Use this when the task requires language understanding.
Runs a fully configured Scout agent as a step inside your workflow. The agent uses its own tools, memory, and instructions to complete the task.
Pulls live context from the web. Use this to ground an LLM block in current information.
Runs custom logic when built-in block configuration isn't sufficient. Use this for deterministic transformations that would be overcomplicated in a template.
### Control Flow Blocks
Branches execution with if/else or switch logic based on any value in the workflow state.
Ends the workflow immediately when a condition is true. Use this to short-circuit on invalid input or terminal errors.
Proceeds only when a condition is met; otherwise skips the remaining blocks in that branch.
Adds a time-based pause between blocks. Useful for rate-limited APIs or workflows that need to wait for an external process.
### Data and Integration Blocks
Retrieves documents from a Scout Database — your internal knowledge base or stored workflow outputs.
Sends a message or creates a thread in any Slack channel or DM. Handles authentication and formatting for you.
Sends SMS messages or initiates calls via Twilio. Handles credentials and request signing automatically.
## Choosing the Right Block
Use this reference table to select the right block for each step in your workflow.
| Situation | Block to use |
| ----------------------------------- | ---------------------- |
| Accepting caller input | Input |
| Generating or analyzing text | LLM or Reasoning |
| Calling a REST API | HTTP |
| Branching on a value | Condition |
| Stopping on an invalid state | Stop If |
| Custom deterministic logic | JavaScript |
| Storing results for later retrieval | Save Document to Table |
| Sending a Slack message | Slack |
| Sending an SMS | Twilio |
**LLM vs. JavaScript** — Use JavaScript when the logic is deterministic and testable with unit cases. Use LLM when the input is unstructured, ambiguous, or requires language understanding.
**HTTP vs. integration blocks** — Integration blocks (Slack, Twilio, CRM) handle authentication and request formatting for you. Use HTTP for any other API.
**Condition vs. Stop If** — Stop If ends the workflow immediately. Condition routes execution to different downstream branches and keeps the workflow running.
## Agent Blocks: Embedding AI Judgment
An Agent Block lets you run a fully configured Scout agent as a single step in your workflow. This is the mechanism that allows you to combine the reliability of structured automation with the adaptability of AI.
Use an Agent Block when:
* A step requires reading and interpreting unstructured text
* The right action depends on nuance that a simple condition can't express
* You want to reuse an existing agent's capabilities inside a larger process
Here is an example of an Agent Block configuration for a support ticket triage workflow:
```yaml theme={null}
block: agent
id: triage_agent
agent_id: "support_triage_v2"
inputs:
ticket_subject: "{{ inputs.subject }}"
ticket_body: "{{ inputs.body }}"
customer_tier: "{{ fetch_customer.output.tier }}"
output_key: triage_result
```
The block passes the relevant ticket fields to the agent. The agent responds with a structured decision — for example, `{ urgency: "high", queue: "engineering", draft_reply: "..." }` — which downstream Condition and Action blocks can act on immediately.
Keep Agent Block inputs small and explicit. Pass only the fields the agent needs to make its decision — not the entire workflow state.
## Condition Blocks: Branching Logic
A Condition Block evaluates an expression and routes execution to one of two or more downstream branches. Use it to handle different cases — different customer tiers, different ticket types, different API response codes — without duplicating the rest of your workflow.
```yaml theme={null}
block: condition
id: route_by_urgency
condition: "{{ triage_agent.output.urgency }}"
branches:
high:
next: escalate_to_engineering
medium:
next: assign_to_senior_support
low:
next: send_auto_reply
```
You can chain Condition blocks to handle complex routing trees. Keep each condition focused on a single decision to make the workflow readable.
## Transform Blocks: Reshaping Data
Transform blocks (Text, JSON, and JavaScript blocks) restructure data between steps. Use them to:
* Extract a specific field from a large API response
* Rename keys to match a downstream block's expected schema
* Combine values from multiple prior blocks into a single object
* Format a date, truncate a string, or compute a derived value
Here is a JavaScript Transform block that extracts and normalizes fields from a raw webhook payload:
```javascript theme={null}
// Block ID: normalize_payload
const raw = inputs.webhook_body;
return {
ticket_id: raw.id,
subject: raw.fields?.subject ?? "No subject",
body: raw.fields?.description ?? "",
customer_email: raw.reporter?.email?.toLowerCase(),
created_at: new Date(raw.created).toISOString(),
};
```
Downstream blocks reference the normalized fields as `{{ normalize_payload.output.ticket_id }}`, `{{ normalize_payload.output.subject }}`, and so on.
## Block Design Rules
Follow these rules to keep your workflows maintainable as they grow:
* **One responsibility per block.** A block that fetches data should not also transform it. Split the jobs.
* **Name blocks by what they do.** `classify_urgency` and `fetch_customer` are far more useful than `llm_1` and `http_2` when reading logs.
* **Guard expensive or irreversible actions.** Place a Condition or Stop If block before any write operation, external API call with side effects, or message send.
* **Keep transformation chains explicit.** Avoid long implicit data reshaping inside a prompt. Use a Transform block first so the LLM receives clean, predictable input.
## Next Steps
Apply the validate-fetch-decide-act-return pattern when assembling your blocks.
Execute your workflow and inspect block-level output in the Console.
Trace block-by-block execution and debug failures in production.
Promote your workflow safely from development to production.
# Workflow Console: Live-Test and Debug Scout Workflows
Source: https://docs.scoutos.com/workflows/console
Test Scout workflows during development with the Console. Run real payloads, inspect block-by-block output, and catch errors before deploying.
The Console lets you test a workflow during development by running it directly in the canvas with real input and inspecting each block's output — no production deploy needed. It's the fastest feedback loop you have while building, and the primary tool for catching problems before they reach real users.
## Opening the Console
In the workflow canvas, click the play icon (▶) in the top toolbar. The Console opens on the right side of Studio so you can see your workflow and its output at the same time.
Type or paste an input payload, click **Run**, and watch each block execute in order.
## What the Console Shows You
Running a workflow in the Console gives you a full picture of the execution:
* **Input payload** — the JSON you submitted, so you can verify its shape
* **Block-by-block output** — each block's result in order, revealing exactly where data transforms or breaks
* **Final output** — the complete response your workflow returns
* **Timing per block** — how long each block took, helpful for catching slow LLM or API calls
* **Errors** — failure messages and which block triggered them
The Console is built for live, interactive development testing. [Logs](/workflows/logs) display historical production runs instead. Reach for the Console when you're actively building; reach for Logs when you're triaging what already happened in production.
## What to Check in Each Test Run
Run these four checks before moving on from a test:
1. **Input payload shape** — confirm the input matches what your blocks expect. Mismatched field names cause silent downstream failures.
2. **Block-by-block output** — review each block. Empty or `null` results where you expected content show you exactly where to investigate.
3. **Final output schema** — verify the last block returns the fields your consumer needs, especially if you're exposing the workflow as a tool.
4. **Errors and timing** — watch for error statuses, and check timing. A slow LLM block may signal a prompt or model config problem.
## The Debug Loop
When something is wrong, work through this cycle to isolate and fix it:
1. **Run with realistic input** — use data that resembles real users, not a toy example
2. **Inspect the first failing or noisy block** — click into its output to see what went in and what came out
3. **Fix the block config or template** — adjust the prompt, logic, or field reference
4. **Re-run with the same input** — verify the fix addresses the broken case
5. **Re-run with edge-case input** — test empty strings, missing fields, or odd formats
If the same input fails in the Console but succeeds in production [Logs](/workflows/logs), check your [environment](/workflows/environments) — config values like API keys, model selection, or variables may differ between development and production.
## Console Tips
Save reusable JSON snippets — happy path, empty input, unusual characters — so you can re-run them after every change and catch regressions early.
Pass missing required fields or unexpected values so your error-handling blocks actually get exercised, not just the success path.
When a workflow is used as a [tool in Copilot](/agents/copilot) or via the API, output field names form part of your contract. Rename them here, not after deploy.
A quick Console run after a prompt or logic change takes ten seconds and saves debugging a production incident later.
## Next Steps
Analyze production run history and triage failures after they happen.
Understand how development and production config differences affect runs.
Run workflows from the REST API or SDKs once they're ready for production.
Understand block types and their failure modes to debug traces faster.
# Create a Workflow: From Trigger to Output in Scout
Source: https://docs.scoutos.com/workflows/creating-workflows
Build reliable Scout workflows by defining clear objectives, inputs, and output schemas. Follow the validate-fetch-decide-act-return pattern.
Building a workflow that's easy to maintain starts before you touch the canvas. The most reliable workflows are designed with a clear objective, a defined input schema, and an explicit output shape — then assembled using a consistent build pattern that keeps side effects isolated and failures predictable.
## Before You Build
Define three things before opening Studio:
Write one sentence describing the outcome this workflow should produce. If you can't describe it in one sentence, consider splitting it into two workflows.
List every field the workflow needs to run. Note the type (string, number, object) and whether each field is required or optional.
Describe what should be saved, sent, or returned when the workflow succeeds. Prefer structured keys over free-form text.
Skipping this planning step makes workflows hard to debug and hard to maintain. A five-minute design session saves hours of troubleshooting later.
## Build Flow in Studio
Navigate to **Studio → Workflows** and click **New Workflow**.
Define the fields your workflow expects — text strings, numbers, or nested objects. This becomes the contract between your workflow and its callers.
Add Condition blocks to branch logic, Transform blocks to reshape data, and Agent blocks to generate or classify content. See [Blocks](/workflows/blocks) for the full reference.
Click a block's output handle and drag to the next block's input handle. Reference the connected value in your block config using `{{ block_id.output }}`.
Click the play icon to open the Console. Paste a real input payload and run the workflow. Inspect each block's output before moving on.
Once tests pass, activate the workflow. It will begin running automatically when its trigger fires.
## The Practical Build Pattern
Use this five-step order for every production workflow. Keeping these phases separate makes each one easier to test, debug, and modify independently.
### 1 — Validate Input
Check that required fields exist and have the correct type before doing anything else. A Condition block or a lightweight Transform block works well here.
```yaml theme={null}
block: condition
id: validate_input
condition: "{{ inputs.ticket_id }} != null and {{ inputs.body }} != null"
on_false: stop # end the run immediately — nothing to process
```
### 2 — Fetch Context
Pull any data the workflow needs from Databases, external APIs, or integrations. Keep fetches separate from decisions so failures are easy to isolate.
```yaml theme={null}
block: http
id: fetch_customer
url: "https://api.yourcrm.com/customers/{{ inputs.customer_email }}"
method: GET
headers:
Authorization: "Bearer {{ env.CRM_API_KEY }}"
```
### 3 — Transform and Decide
Shape the data and branch as needed. This is where Condition blocks route execution and Agent blocks make judgment calls.
```yaml theme={null}
block: agent
id: classify_urgency
prompt: |
You are a support triage assistant.
Ticket subject: {{ inputs.subject }}
Ticket body: {{ inputs.body }}
Customer tier: {{ fetch_customer.output.tier }}
Classify the urgency of this ticket.
Respond with exactly one of: low, medium, high
output_key: urgency
```
### 4 — Take Action
Write data, send messages, and call external systems — but only after validation has passed. Moving writes to this phase ensures a bad input never creates a partial record in your external tools.
```yaml theme={null}
block: http
id: update_ticket
url: "https://api.yourcrm.com/tickets/{{ inputs.ticket_id }}"
method: PATCH
body:
urgency: "{{ classify_urgency.output }}"
status: "triaged"
```
### 5 — Return Structured Output
Return a clean set of keys and values. Agents and downstream systems cannot reliably parse free-form text.
```yaml theme={null}
block: output
id: workflow_output
fields:
ticket_id: "{{ inputs.ticket_id }}"
urgency: "{{ classify_urgency.output }}"
routed_to: "{{ route_ticket.output.queue }}"
status: "processed"
```
## Example: Processing a Support Ticket
Here is how the full pattern comes together for a workflow that receives a support ticket, classifies it, and routes it to the right team.
```
Input: { ticket_id, subject, body, customer_email }
1. Validate → confirm ticket_id and body are present; stop immediately if not
2. Fetch → look up customer record and tier from your CRM Database
3. Decide → run an Agent Block to classify urgency (low / medium / high)
4. Act → write urgency back to the ticket; post to the matching Slack channel
5. Output → { ticket_id, urgency, routed_to, status: "processed" }
```
Each step is a separate block. If step 2 fails, steps 3 through 5 never run — so your external systems stay consistent and you always know which block caused the failure.
## Using Workflows as Agent Tools
When you expose a workflow as a tool for an AI agent, the input and output contract becomes even more important. Agents call tools programmatically — they cannot interpret ambiguous schemas or unstructured responses.
Follow these rules for agent-facing workflows:
* **Keep the input schema small and explicit.** Accept only the fields the workflow actually needs.
* **Return predictable output keys.** The agent reads specific keys — don't change them between revisions without updating the agent's instructions.
* **Include clear failure messages in output.** Return `{ status: "failed", reason: "ticket_id missing" }` rather than throwing an unhandled error.
* **Avoid side effects before validation.** The agent may call the workflow with incomplete data during exploration — validate first so nothing is written prematurely.
Add an instruction snippet to your agent telling it how to call this workflow:
```
When calling the triage_ticket workflow tool:
1. Confirm ticket_id, subject, body, and customer_email are available before calling.
2. Pass the smallest valid payload — omit optional fields if unknown.
3. On failure, read the "reason" key from the response and surface it to the user.
4. On success, report the ticket_id, urgency, and routed_to values.
```
## Common Mistakes to Avoid
**Overloading one workflow with too many jobs.** If a workflow handles unrelated processes, split it. Each workflow should do one thing well — it will be easier to test, maintain, and debug independently.
**Writing to external systems before validation.** Always move writes to phase 4. A bad input should never create a partial record in your CRM, database, or messaging tool.
**Returning free-form text instead of structured output.** Return `{ status, result_id, message }` rather than a paragraph. Agents and downstream integrations cannot parse prose reliably.
**Skipping test runs with realistic payloads.** Use the Console with actual data — not placeholder strings like `"test"`. Edge cases appear quickly with real values and save you from production surprises.
## Next Steps
Choose the right block type for each step in your workflow.
Execute your workflow from the Console, API, or SDK.
Promote your workflow from development to production safely.
Debug run failures and trace data flow between blocks.
# Workflow Environments: Promote and Roll Back Safely
Source: https://docs.scoutos.com/workflows/environments
Use Scout workflow environments to promote changes from development to production, maintain separate configurations, and roll back to any revision safely.
Shipping a workflow change directly to production is risky — a misconfigured block or a subtle prompt change can silently degrade output quality before you notice. Scout's environment model gives you a structured path from development to live traffic, where each stage points to a specific revision of your workflow and you control when and what gets promoted.
## What Are Environments?
Scout provides three environments for every workflow. Each environment is independently mapped to a workflow revision — changing an environment's revision does not alter the workflow itself or affect other environments.
Where you build and iterate. No real user traffic hits this environment. Use it freely for experiments, structural changes, and active debugging in the Console.
Your pre-production gate. Test with realistic inputs — including edge cases and known failure payloads — before anything reaches live users.
Live traffic. Only promote here once staging has confirmed the revision behaves correctly under realistic load and inputs.
Each environment points to a revision, not a branch. You promote a specific revision to an environment — you don't "deploy a branch." This makes rollbacks instant and deterministic.
## How to Promote a Workflow Revision
Make your changes in Studio and test them thoroughly using the Console. Verify correct behavior with both happy-path and edge-case payloads before moving forward.
Open **History** in the workflow sidebar. Give the revision a descriptive name — for example, `add-urgency-classification` or `fix-null-customer-lookup`. Add a short note describing what changed.
In History, select the revision and click **Promote to Staging**. Scout updates the staging environment to run this revision immediately.
Run your full validation suite against the staging environment. Use the API with `environment=staging` to test programmatically, or use the Console with production-representative payloads.
Once staging passes, open History and click **Promote to Production**. Monitor the Logs tab for the next few minutes to confirm the first production runs succeed.
## Targeting Environments via API
When you call a workflow via the API or SDK, always pass an explicit `environment` parameter. This ensures you're testing the right revision at each stage.
```bash theme={null}
# Run against staging before promoting to production
curl -X POST "https://api.scoutos.com/v2/workflows/{workflow_id}/execute?environment=staging" \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inputs": {
"ticket_id": "TKT-TEST-001",
"subject": "Staging smoke test",
"body": "Validate that the new urgency classifier returns the correct tier.",
"customer_email": "staging-test@example.com"
}
}'
```
Switch `environment=staging` to `environment=production` once you're confident in the revision. Run the same payload against both environments to compare outputs before committing.
## Separate Configuration Per Environment
You can configure different values for each environment — API keys, feature flags, rate limits, and integration endpoints. This lets development workflows use sandbox credentials and staging workflows use pre-production accounts, while production always uses live credentials.
Store environment-specific values as **Environment Variables** in the Scout Settings panel, then reference them in your blocks:
```yaml theme={null}
block: http
id: create_crm_contact
url: "{{ env.CRM_API_BASE_URL }}/contacts"
headers:
Authorization: "Bearer {{ env.CRM_API_KEY }}"
```
Set `CRM_API_BASE_URL` and `CRM_API_KEY` to different values per environment. Your workflow definition stays identical across all three environments — only the variable values change.
## Reviewing Changes Before Promoting
Before promoting a revision to production, review what actually changed using the revision diff in History.
* **Blocks view** — shows high-level structural changes: blocks added or removed, connections modified. Use this for a quick sanity check.
* **Code view** — shows detailed JSON-level changes in every block's configuration. Use this when a subtle prompt tweak or config change might have unintended side effects.
If the diff shows more changes than you expected, investigate before promoting. A revision that looks like a small prompt edit may have accumulated other changes since the last deploy.
## Rolling Back to a Previous Revision
If a production deploy degrades output quality or increases failure rates, roll back immediately and fix forward in development.
Open **History** and look for the revision that was running before the problematic deploy. Check **Logs** to confirm it was producing correct output.
Select the previous revision in History and click **Promote to Production**. The rollback takes effect immediately — no downtime, no redeploy.
Switch to the **Logs** tab and verify that the next few runs succeed. Check that error rates and durations return to baseline.
Do not patch the production revision directly. Make your fix in development, test it in staging, and follow the normal promotion path.
Name your revisions meaningfully before every staging promotion. When you need to roll back quickly under pressure, `add-urgency-classifier` is far easier to identify than `revision-47`.
## Best Practices
* **Never promote directly from development to production.** Always validate in staging first, even for small changes. A one-word prompt edit can shift LLM output in unexpected ways.
* **Run automated checks against staging.** Write a test script that calls your workflow via API with a fixed set of payloads and asserts on the outputs. Run it every time you promote to staging.
* **Keep development noisy.** Add verbose logging blocks and debug outputs in development. Strip them before promoting to staging.
* **Pair Logs with History.** When a failure appears in Logs, note the timestamp and cross-reference it with History to identify which revision introduced the problem.
## Next Steps
Verify deployment health after every promote and debug failures fast.
Execute workflows with explicit environment targeting via API or SDK.
Structure your workflow to be testable and easy to promote confidently.
Understand how blocks and configuration work before building for multiple environments.
# Workflow History: Revision Timeline and Rollback
Source: https://docs.scoutos.com/workflows/history
Use Scout workflow history to audit revisions, understand what changed and why, and restore a previous revision to roll back a bad deployment safely.
History is the audit and rollback system for your workflows. It records a revision every time you deploy, captures who made the change and why, and lets you restore any prior revision without losing the ones that came after. When a deployment breaks something in production, History is how you understand what changed and recover quickly.
## What History Provides
Every deployment is recorded as a revision with a timestamp, so you can see the full sequence of changes over the life of the workflow.
Each revision shows who deployed it, making it clear who to ask when you need context on a change.
Revisions carry a name and description you set at deploy time, so the timeline reads as intent rather than a wall of timestamps.
Restore any prior revision to roll back to a known good state. Restoring is non-destructive — your existing history stays intact.
## When Revisions Are Created
A new revision is created when you **deploy** a workflow to an environment — not on every save. Changes you make and test in the Console remain drafts until you deploy them. At deploy time, Scout snapshots the workflow and records it as a named revision in History.
Because revisions are tied to deploys, the timeline reflects what actually shipped to an environment, not every intermediate edit. This keeps History focused on the changes that matter for auditing and rollback.
## The Revision Workflow
Build and iterate in Studio, then test your changes in the Console with realistic inputs until you're confident they behave correctly.
Before deploying, give the revision a clear name that explains the intent of the change. The name stays attached to the revision for future reference.
Add a short description of what changed and why. This is the context your future self — or a teammate — will rely on when reviewing the timeline or deciding whether to roll back.
Deploy to the target environment. Scout records the snapshot as a new revision, with its name, description, author, and timestamp.
## Naming Guidelines
A good revision name explains *intent* — what the change accomplishes — rather than which block you happened to edit. When you're rolling back under pressure, a clear name is the difference between an instant recovery and a guessing game.
| Good | Avoid |
| ----------------------------------- | ---------------- |
| `Add fallback path for CRM timeout` | `updated blocks` |
| `Cap token usage on summarizer` | `fix` |
| `Route EU users to compliant model` | `v2` |
## Writing Good Descriptions
Where the name captures *what*, the description captures *why*. A useful description explains the reasoning and the expected impact, for example:
> Fallback returns cached response if CRM is down. Prevents 503s during peak hours.
A description like this tells anyone reviewing the revision exactly why it exists and what problem it solves — invaluable when you're deciding whether a later change is safe to roll back to.
## Restoring a Previous Revision
If a deployment introduces a regression, restore the last known good revision to roll back.
Open the **History** panel in the workflow sidebar to see the full revision timeline.
Identify the revision that was running before the problematic deploy. Use the names, descriptions, and timestamps — and cross-reference Logs — to confirm it was producing correct output.
Select that revision and click **Restore**. Scout brings its configuration back as the current working state.
Restoring updates your working state but does not change what's live. Deploy the restored revision to the target environment to make the rollback take effect.
Restoring is **non-destructive**. It creates a new revision based on the older one rather than overwriting anything, so the revisions you reverted from stay in the timeline. You can always see what you rolled back from — and roll forward again if needed.
## Next Steps
Promote and roll back revisions across development, staging, and production for a complete rollback strategy.
Validate run quality after changes and confirm a rollback restored healthy behavior.
Re-test a restored revision in the Console before you deploy it.
# Jinja Templates: Wiring Data Between Workflow Blocks
Source: https://docs.scoutos.com/workflows/jinja-templates
Use Jinja templates to pull workflow state, block outputs, and environment variables into any text field in a Scout workflow block.
Jinja templates enable dynamic inputs inside workflow blocks, pulling in state, outputs, environment variables, or computed values wherever a text field is accepted. They are the core mechanism for passing data between blocks — anywhere you can type text in a block's configuration, you can reference values from elsewhere in the workflow.
## Core Syntax
Jinja has two delimiters:
* `{{ ... }}` for **expressions** — evaluated and rendered into the field.
* `{% ... %}` for **control flow** — conditionals and loops that shape the output.
```jinja theme={null}
{{ inputs.user_message }}
{{ summarize_block.output }}
{% if inputs.priority == "high" %}urgent{% else %}normal{% endif %}
```
## Variable References
Scout provides three namespaces in every template:
| Namespace | What it references |
| ------------------- | -------------------------------------------- |
| `inputs.field_name` | Fields defined on the workflow's Input block |
| `block_id.output` | Output produced by a prior block |
| `_env.VAR_NAME` | Environment variables for secrets and config |
Nested fields use chained dot notation:
```jinja theme={null}
{{ fetch_user.output.email }}
```
## Common Use Cases
### Build a prompt with workflow state
Assemble an Agent prompt from the original question and retrieved context:
```jinja theme={null}
You are a helpful assistant.
The user asked: {{ inputs.question }}
Relevant context from the knowledge base: {{ retrieval_block.output }}
Answer based only on the context above.
```
### Build an API payload dynamically
Inject workflow values into a JSON body for an Action block:
```json theme={null}
{
"user_id": "{{ inputs.user_id }}",
"action": "{{ inputs.action }}",
"timestamp": "{{ datetime.now(timezone.utc).isoformat() }}"
}
```
### Conditional messaging
Change the message based on workflow state:
```jinja theme={null}
{% if inputs.priority == "high" %}
Urgent: {{ inputs.message }}
{% else %}
FYI: {{ inputs.message }}
{% endif %}
```
## Date and Time
Use `__exp_global` for ready-made date strings, or reach for `datetime` directly when you need custom formatting:
```jinja theme={null}
{# Simple date strings #}
{{ __exp_global.current_date }}
{{ __exp_global.current_datetime }}
{{ __exp_global.current_time_utc }}
{# Custom formatting #}
{{ datetime.now(timezone.utc).isoformat() }}
{{ datetime.now(ZoneInfo("America/Los_Angeles")).strftime('%Y-%m-%d %I:%M %p') }}
```
The objects `datetime`, `timezone`, and `ZoneInfo` are available inside any template.
## Safe Templating Rules
**Reference specific fields rather than whole objects.** `{{ block.output.name }}` is safer than `{{ block.output }}` because it fails loudly if the field is missing, instead of silently rendering a large object.
**Keep logic out of templates.** Move any conditional longer than one line into a Condition block. Templates are for inserting values, not for branching business logic.
**Test in Console first.** The Console shows rendered template output, so you catch bad references before they reach production.
**Use `_env` for secrets and never hardcode credentials.** Reference API keys and tokens through `_env.VAR_NAME` so they stay out of your workflow definition.
## Next Steps
Understand how data flows between blocks through shared state.
Build cleaner workflow architectures with a consistent pattern.
See which block produces which output to reference in templates.
Validate rendered template output in the Console before going live.
# Logic and State: How Data Flows Between Blocks
Source: https://docs.scoutos.com/workflows/logic-state
Understand how Scout workflows pass data between blocks through shared state — references, conditional logic, global variables, and error handling.
A Scout workflow moves data through a shared state object that's passed from block to block. Each block reads what it needs from earlier blocks, does its job, and adds its own output back to the state for downstream blocks to use. Designing that state deliberately is what makes a workflow predictable, testable, and easy to debug.
## How State Moves Between Blocks
Every block can read from earlier blocks using double-brace template references:
* `{{ inputs.field_name }}` — reads a field from the Input block (the workflow's trigger payload)
* `{{ block_id.output }}` — reads the full output of a prior block by its ID
* `{{ block_id.some_field }}` — reads a specific field from a prior block's output
Reference the block by the ID you gave it, then the field you want. The reference is resolved at runtime with the current state.
### A Practical Example
Consider a three-block chain: an Input block, an `enrich_user` block that looks up account details, and a `send_email` block that composes a message.
```jinja theme={null}
{# In the enrich_user block — read from the workflow inputs #}
User name: {{ inputs.user_name }}
Account tier: {{ inputs.account_tier }}
```
```jinja theme={null}
{# In the send_email block — read from the enrich_user block #}
Full name: {{ enrich_user.full_name }}
Plan label: {{ enrich_user.plan_label }}
```
Each block pulls only the fields it needs. Map references explicitly rather than passing the whole state object around — when something breaks, you want to see exactly which value a block depended on.
Reference the specific fields a block needs instead of handing it the entire upstream output. Explicit mappings make failures obvious in the logs.
## Conditional Logic
Use Jinja `if`/`elif`/`else` blocks to branch on values in your state. This is useful for routing and for shaping dynamic content.
Route by account tier:
```jinja theme={null}
{% if inputs.account_tier == "enterprise" %}
Priority support queue — SLA: 4 hours
{% elif inputs.account_tier == "pro" %}
Standard support queue — SLA: 24 hours
{% else %}
Community support — check our docs first
{% endif %}
```
Build a dynamic prompt that adapts to the input:
```jinja theme={null}
You are a support assistant.
{% if inputs.has_prior_conversation %}
The user has contacted us before. Be warm and reference their history.
{% else %}
This is a new user. Introduce yourself briefly.
{% endif %}
User message: {{ inputs.message }}
```
## Global Variables
Scout exposes built-in date and time variables you can use in any template without configuration. They're handy for timestamps, logging, and report headers.
| Variable | Example output |
| ----------------------------------------- | --------------------- |
| `{{ __exp_global.current_date }}` | `2025-06-15` |
| `{{ __exp_global.current_time }}` | `14:23:01` |
| `{{ __exp_global.current_datetime }}` | `2025-06-15 14:23:01` |
| `{{ __exp_global.current_time_utc }}` | `21:23:01 UTC` |
| `{{ __exp_global.current_time_pacific }}` | `14:23:01 PDT` |
For example:
```jinja theme={null}
[{{ __exp_global.current_datetime }}] User {{ inputs.user_id }} submitted request
Report generated on {{ __exp_global.current_date }}
```
## State Design Tips
A few habits keep workflow state clean as it grows:
* **Keep payloads small.** Pass only the fields a block actually needs, not the whole state object.
* **Use stable key names.** Renaming an output field silently breaks every downstream reference to it.
* **Normalize once.** Clean and format data in one early block, then reuse the normalized values everywhere downstream.
* **Prefer structured output over string building.** Return structured data like `{ "user_id": "abc", "status": "active" }` rather than a formatted string — it's far easier to branch on later.
## Error and Fallback Paths
Don't assume the happy path. Add branch logic for the failures you can anticipate:
* Missing or empty input fields
* Empty search or lookup results
* External API failures or timeouts
Return explicit status fields so downstream blocks can branch on them. A lookup block might return either of these shapes:
```json theme={null}
{ "ok": true, "data": { "user_id": "abc", "email": "user@example.com" } }
```
```json theme={null}
{ "ok": false, "error_code": "USER_NOT_FOUND", "message": "No user found for that ID" }
```
Then branch on the `ok` field:
```jinja theme={null}
{% if lookup_user.ok %}
Found {{ lookup_user.data.email }} — continuing workflow
{% else %}
Stopping: {{ lookup_user.error_code }} — {{ lookup_user.message }}
{% endif %}
```
This keeps error handling explicit and auditable rather than buried inside block logic.
## Next Steps
Choose the right block type for each step in your workflow.
Assemble blocks with the validate-fetch-decide-act-return pattern.
Execute your workflow and inspect block-level state in the Console.
Trace block-by-block execution and debug failures in production.
# Workflow Logs: Debug and Monitor Scout Automation Runs
Source: https://docs.scoutos.com/workflows/logs
Access Scout workflow logs to debug failures, monitor performance, and trace block-by-block execution. Filter by status and date to find issues fast.
Workflow logs give you a complete record of every run — what triggered it, what each block received and returned, how long each step took, and why a run failed if it did. You don't need to add instrumentation or wire up external monitoring to get this visibility; Scout captures it automatically for every execution.
## Accessing Logs in Studio
Open the **Logs** tab in the left panel of your workflow canvas. You'll see a list of recent runs sorted by time, with status, duration, and trigger information visible at a glance.
Click any run entry to open its full execution trace. The trace expands into a block-by-block view that shows exactly what happened at each step.
Logs are scoped to the workflow you have open. To view logs across multiple workflows, use the global Logs panel in the Studio sidebar.
## What Each Log Entry Shows
Every run entry in the log list includes the following fields:
| Field | Description |
| --------------- | ------------------------------------------------------------------------------------------------------- |
| **Run ID** | A unique identifier for the run. Use this when reporting issues or correlating logs with API responses. |
| **Timestamp** | When the run started, in your local timezone. |
| **Trigger** | What initiated the run — a webhook, a schedule, a Console test, or an API/SDK call. |
| **Status** | `completed`, `failed`, or `running`. |
| **Duration** | Total time from trigger to final output, in milliseconds. |
| **Environment** | Which environment the run executed against — development, staging, or production. |
When you expand a run, you also see:
* **Input context** — the full payload passed to the workflow at trigger time
* **Output context** — the structured data returned by the workflow's final block
* **Block-level trace** — the input, config, and output of every block that executed, in order
* **Token usage and cost signals** — token counts and estimated cost for each LLM block
* **Error messages** — for failed runs, the specific block that failed and the error it returned
## Filtering and Searching Logs
Use filters to narrow the log list to the runs you care about. Scout supports filtering by:
* **Status** — filter to `failed` when actively debugging; filter to `completed` when reviewing performance
* **Date range** — set a window around an incident to find the affected runs
* **Environment** — isolate production runs from development or staging test runs
* **Trigger type** — filter to webhook runs, scheduled runs, or manual Console runs independently
When investigating an incident, start with **Status = failed** and the relevant date range. You'll typically find the first failing run within seconds, which gives you the exact timestamp to anchor your investigation.
## Reading Execution Traces
The block-by-block trace is the most powerful part of the log view. Each block entry in the trace shows:
* The **input values** it received from the trigger payload or a prior block
* The **configuration** it ran with (prompt, URL, condition expression, etc.)
* The **output** it produced
* The **duration** of that specific block in milliseconds
* An **error** if the block failed, including any error message from an external API
Read the trace top to bottom — each block's output becomes the next block's input. When a block fails, every block below it in the chain was skipped. The trace makes this clear by marking skipped blocks as such.
## Common Failure Patterns and How to Fix Them
### Input Error
**What it looks like:** The first block in your chain — or an early validation block — fails with a message like `missing required field: ticket_id` or `expected string, got null`.
**Why it happens:** The data coming into the workflow was missing a required field, had the wrong type, or was malformed. This is usually a mismatch between what the caller sent and what your Input block expects.
**How to fix it:**
1. Open the failed run and check the **Input context**. Identify which field is missing or wrong.
2. Trace back to the caller — the webhook payload, the API request, or the SDK call — and confirm it's sending the correct fields.
3. If the issue is a new edge case (a field that's sometimes absent), add a Condition or Stop If block to handle it gracefully before your downstream blocks run.
### Logic Error
**What it looks like:** The workflow completes — all blocks run — but the output is wrong. Or a Condition block routes to the wrong branch unexpectedly.
**Why it happens:** The block received valid data but produced incorrect output. Common causes include a flawed condition expression, a misconfigured prompt, or a template that references the wrong block ID.
**How to fix it:**
1. Open the failed run and expand each block in the trace. Find where the output first diverges from what you expected.
2. Copy the input payload from the run and reproduce the issue in the Console. Paste the same payload and run the workflow in development.
3. Fix the block config — correct the condition expression, adjust the prompt, or update the template reference — and rerun in Console to confirm.
### External Dependency Error
**What it looks like:** An HTTP block, integration block, or Agent block fails with an error from an external service — a `429 Too Many Requests`, a `503 Service Unavailable`, a timeout, or an authentication error.
**Why it happens:** A third-party API or integration returned an error or took too long to respond. This is outside Scout's control but is visible and actionable in the logs.
**How to fix it:**
1. Open the failed block in the trace and read the full error message, including the HTTP status code.
2. For `429` or `503` errors: wait for the dependency to recover, then rerun the workflow. Consider adding a Delay block before the failing step if rate limits are a recurring issue.
3. For `401` or `403` errors: check that the API key or OAuth token configured for that block is valid and hasn't expired.
4. For timeouts: check whether the external service is experiencing degraded performance, and consider increasing the block's timeout setting.
## Monitoring Performance Over Time
Beyond debugging individual failures, use logs to catch performance regressions before they become incidents.
A block that normally completes in 200 ms jumping to 2 s is a signal worth investigating — even if runs are still succeeding.
Recurring failures in the same block type point to a systemic issue — a flaky integration, an LLM prompt that breaks on certain inputs, or a CRM field that's occasionally null.
Cross-reference failure spikes in Logs with revision promotions in History. If failures started after a specific deploy, the revision diff is your starting point.
After every promotion to production, monitor Logs for five to ten minutes. Confirm that the first production runs succeed before considering the deploy stable.
## Next Steps
Roll back to a previous revision when logs show a promotion introduced failures.
Use the Console to reproduce failures from logs with controlled inputs.
Structure your workflow to make failures visible and easy to trace in logs.
Understand block types and their failure modes to debug traces faster.
# Workflows
Source: https://docs.scoutos.com/workflows/overview
Scout workflows connect your tools, respond to events and schedules, and run reliably at scale. Use Agent Blocks to add AI judgment to any automation.
Workflows are Scout's automation backbone. They connect your tools and services, respond to triggers, and execute sequences of actions — with branching logic, error handling, and AI judgment built in. You define the steps, and Scout runs them exactly as designed, every time.
## What Are Workflows?
A workflow is a series of connected blocks that run in response to a trigger. Each block performs one job — calling an API, evaluating a condition, running an AI agent, or transforming data — and passes its output to the next block in the chain. Workflows let you build processes that are too complex or too repetitive to handle manually, and automate them with confidence.
Common use cases include:
* A new lead fills out a form → add to CRM, research their company, notify your sales team
* A meeting ends on Zoom → transcribe the recording, extract action items, send a follow-up email
* A support ticket is created → categorize it, suggest a response, escalate if urgent
* A calendar event approaches → prepare a briefing, attach relevant documents, notify attendees
## When to Use Workflows vs. Agents
Workflows and agents solve different problems. Use the table below to choose the right tool for your situation.
| Aspect | Workflows | Agents |
| ---------------- | ------------------------------------- | --------------------------------- |
| **Best for** | Predictable, repeatable processes | Open-ended, adaptive tasks |
| **Control flow** | Predefined steps and branches | Agent decides the approach |
| **Triggers** | Events, webhooks, schedules | Chat messages, mentions |
| **Consistency** | Same output every time | May vary based on context |
| **Complexity** | Excellent for multi-step integrations | Better for nuanced judgment calls |
**Choose workflows when:**
* You know the exact steps in advance
* You need reliable, repeatable automation
* The process should run automatically on a trigger
* Multiple tools need to be connected in sequence
**Choose agents when:**
* The task requires creativity or judgment
* The approach isn't predictable in advance
* You want conversational, back-and-forth interaction
* The system needs to adapt to unexpected situations
## Triggers
Every workflow starts with a trigger — the event that kicks off a run. Scout supports four trigger types:
* **Webhooks** — HTTP requests sent from an external service (payment system, form tool, CRM)
* **Schedules** — Time-based execution using cron syntax (daily, weekly, on a specific interval)
* **Events** — Scout-native events such as an agent completing a task or a file being uploaded
* **Integrations** — Native triggers from connected tools like calendar reminders or incoming emails
## Blocks
Blocks are the individual units of execution inside a workflow. Each block takes inputs, performs exactly one job, and produces structured output that the next block can use.
Perform operations — call external APIs, write to databases, send notifications, or push data into connected tools.
Run an AI agent as a step in your workflow. Use these when a decision requires language understanding or judgment.
Branch your workflow with if/else or switch logic. Route data to different downstream blocks based on any value.
Reshape, filter, or restructure data between steps. Keep downstream blocks clean by normalizing inputs here.
## Data Flow Between Blocks
Each block outputs structured data that downstream blocks can reference directly. You connect blocks by mapping output fields to input fields — click an output handle and drag it to the next block's input handle in the Studio canvas.
Once connected, reference any prior block's output using double-brace syntax:
```
{{ block_id.output }}
```
For example, if your first block has the ID `classify_ticket`, the next block can read its result as `{{ classify_ticket.output }}`. This makes it straightforward to build chains where each step enriches or transforms data before passing it on.
## Error Handling
Workflows include built-in error handling so failures don't silently break your automation.
Configure per-block retry logic for transient failures like network timeouts or rate limits.
Set alternate branches for expected failure cases so your workflow degrades gracefully.
Get alerted immediately when a run fails so you can investigate before it impacts users.
Review the full block-by-block trace of every run to pinpoint exactly what went wrong.
## The Power of Agent Blocks
Workflows don't have to be rigid. Drop an Agent Block into any workflow to add AI judgment exactly where you need it, without sacrificing the reliability and structure of the surrounding automation.
Here's what that looks like for a support ticket workflow:
```
1. Webhook trigger fires when a ticket is created
2. Transform Block extracts subject, body, and customer ID
3. Agent Block reads the ticket and decides:
- "billing" → route to billing queue
- "bug" → create a GitHub issue, assign to engineering
- "general" → draft a reply, assign to support
4. Condition Block checks the agent's output and routes accordingly
5. Action Blocks execute: post to Slack, update CRM, send confirmation email
```
The agent handles the judgment call. The workflow handles the execution. You get both reliability and adaptability — without choosing one over the other.
## Getting Started
Navigate to **Studio → Workflows** from the left sidebar.
Click **New Workflow** and give it a descriptive name that reflects its purpose.
Choose a webhook, schedule, event, or integration trigger to define what starts your workflow.
Add blocks from the block library and connect them by dragging output handles to input handles.
Click the play icon to open the Console. Run the workflow with a real input payload and inspect each block's output.
Once your tests pass, activate the workflow. It will begin running automatically when its trigger fires.
## Next Steps
Define objectives, inputs, and outputs before you build — and follow the validate-fetch-decide-act-return pattern.
Learn which block types to use and when, including how to pass data between them.
Execute workflows from the Studio UI, REST API, Python SDK, or TypeScript SDK.
Promote changes from development to production and roll back safely when needed.
Debug failures and monitor performance with block-level execution traces.
# Run Scout Workflows: UI, API, SDK, and Webhook Triggers
Source: https://docs.scoutos.com/workflows/running-workflows
Execute Scout workflows from the Studio Console, REST API, Python SDK, or TypeScript SDK. Test with real payloads before deploying to production.
Scout workflows run from multiple surfaces: the Studio Console for development and debugging, the REST API and SDKs for production systems, and webhook triggers for event-driven integrations. Each approach targets a different stage of your workflow's lifecycle — test locally first, then move to the API or SDK when you're ready to integrate with external systems.
## Running from the Console
The Console is the fastest way to test a workflow during development. Open it by clicking the play icon on the workflow canvas in Studio.
Type or paste an input payload, click **Run**, and watch each block's output appear in real time as the workflow executes. You can inspect the input and output of every individual block without writing a single line of integration code.
Use the Console to:
* Confirm your input payload shape before wiring up a real trigger or API call
* Spot errors in individual blocks without deploying anything
* Test edge cases quickly — paste a bad payload to confirm your validation logic fires correctly
* Reproduce a production failure by copying the input from a failed run in Logs
Always test with real data, not placeholder strings like `"test"`. Edge cases and formatting issues surface immediately with actual values.
## Running via REST API
Trigger a workflow from any backend service, script, or automation tool using the Scout REST API. Send a `POST` request to the workflow execute endpoint, passing your inputs in the request body.
```bash theme={null}
curl -X POST "https://api.scoutos.com/v2/workflows/{workflow_id}/execute?environment=production" \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inputs": {
"ticket_id": "TKT-4821",
"subject": "Cannot access billing portal",
"body": "I have been trying to log in to the billing portal for two days and keep getting a 403 error.",
"customer_email": "jane.doe@example.com"
},
"streaming": false
}'
```
A successful response includes the run ID, status, duration, and your workflow's output fields:
```json theme={null}
{
"run_id": "run_abc123xyz",
"status": "success",
"outputs": {
"ticket_id": "TKT-4821",
"urgency": "high",
"routed_to": "billing-support",
"status": "processed"
},
"duration_ms": 1840
}
```
Replace `{workflow_id}` with your workflow's ID, found in the workflow settings panel in Studio. Set `environment` to `development`, `staging`, or `production` depending on which revision you want to run.
## Running via SDK
The Python and TypeScript SDKs wrap the REST API with type safety, automatic retries, and streaming support. Use the SDK when integrating Scout into your application backend.
```python python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
result = client.workflows.execute(
workflow_id="wf_support_triage",
inputs={
"ticket_id": "TKT-4821",
"subject": "Cannot access billing portal",
"body": "I have been trying to log in to the billing portal for two days and keep getting a 403 error.",
"customer_email": "jane.doe@example.com",
},
environment="production",
)
print(result.outputs["urgency"]) # "high"
print(result.outputs["routed_to"]) # "billing-support"
```
```typescript typescript theme={null}
import Scout from "scoutos";
const client = new Scout({ apiKey: "YOUR_API_KEY" });
const result = await client.workflows.execute("wf_support_triage", {
inputs: {
ticketId: "TKT-4821",
subject: "Cannot access billing portal",
body: "I have been trying to log in to the billing portal for two days and keep getting a 403 error.",
customerEmail: "jane.doe@example.com",
},
environment: "production",
});
console.log(result.outputs.urgency); // "high"
console.log(result.outputs.routed_to); // "billing-support"
```
### Streaming
For workflows that include LLM blocks or other long-running steps, use streaming to receive output tokens as they arrive rather than waiting for the full response. This is especially useful when surfacing LLM-generated text directly in a UI.
```python python theme={null}
stream = client.workflows.execute_stream(
workflow_id="wf_support_triage",
inputs={
"ticket_id": "TKT-4821",
"subject": "Cannot access billing portal",
"body": "I have been trying to log in for two days and keep getting a 403 error.",
"customer_email": "jane.doe@example.com",
},
environment="production",
)
for chunk in stream:
print(chunk.delta, end="", flush=True)
```
```typescript typescript theme={null}
const stream = await client.workflows.executeStream("wf_support_triage", {
inputs: {
ticketId: "TKT-4821",
subject: "Cannot access billing portal",
body: "I have been trying to log in for two days and keep getting a 403 error.",
customerEmail: "jane.doe@example.com",
},
environment: "production",
});
for await (const chunk of stream) {
process.stdout.write(chunk.delta ?? "");
}
```
## Webhook Triggers
Configure a webhook trigger on your workflow to run it automatically whenever an external service sends an HTTP event — a form submission, a payment notification, a CRM update, or any other webhook-capable tool.
When you add a webhook trigger in Studio, Scout generates a unique endpoint URL:
```
https://hooks.scoutos.com/v1/workflows/{workflow_id}/webhook/{token}
```
Paste this URL into your external service's webhook configuration. When the service sends a `POST` request to this URL, Scout runs the workflow immediately, passing the entire request body as `{{ inputs.webhook_body }}`.
Webhook triggers always run against the **production** revision of your workflow. Test your webhook handling in the Console first by pasting a sample payload from your external service.
## Targeting Environments
Always specify an environment when calling via the API or SDK. This determines which revision of your workflow runs — not just a label.
| Environment | When to use |
| ------------- | ----------------------------------------------- |
| `development` | Active building and iterating in Studio |
| `staging` | Pre-production validation with realistic inputs |
| `production` | Live user traffic and production integrations |
Targeting `staging` explicitly lets you run automated checks against a pre-production revision before promoting it:
```bash theme={null}
curl -X POST "https://api.scoutos.com/v2/workflows/{workflow_id}/execute?environment=staging" \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inputs": {"ticket_id": "TKT-9999", "subject": "smoke test", "body": "This is a staging smoke test.", "customer_email": "test@example.com"}}'
```
See [Environments](/workflows/environments) for how to promote revisions across stages and roll back safely.
## Next Steps
Promote workflow revisions from development to production and roll back when needed.
Inspect run status, duration, and block-level output after each execution.
Understand what each block type does and how to connect them.
Structure your workflow with the validate-fetch-decide-act-return pattern.