> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-codex-docs-audit-20260719-0149.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Scout

> Open-source company intelligence agent that navigates web, Slack, Drive, and MCP sources and can update a wiki and CRM.

**Scout is an open-source company intelligence agent.** It navigates live information sources (web, Slack, Drive, wiki, CRM, MCP servers) to assemble context on demand, and it can update its wiki and CRM when you ask it to save information. The code is public at [agno-agi/scout](https://github.com/agno-agi/scout).

The default move when working with knowledge sources is to ingest everything into a vector database, chunk, embed, and pray. Coding agents figured out the right approach. They navigate: `ls`, `grep`, open the file, follow the import. Scout does the same thing across Slack, Drive, and the rest. It searches the channel, opens the doc, expands the thread, and assembles context at question time from the live source.

## How it works

Scout is a single agent with multiple **context providers**. Each provider exposes two natural-language tools: `query_<source>` for reads and `update_<source>` for writes, where the source supports them. This thin layer solves three problems that hit any agent with a diverse tool surface: context pollution from too many tools, degrading performance from overlapping scopes, and the main agent forgetting its job because its context is all tool quirks.

A sub-agent behind each provider owns the source's quirks. Scout sees `query_slack`. Behind it, a sub-agent knows to paginate by cursor and prefer `conversations.replies` for threads. Scout's context never sees any of that.

| Provider           | Active when                       | Tools                                                                                                                          |
| ------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Web**            | Always on                         | `query_web`. Uses the Parallel SDK when `PARALLEL_API_KEY` is set, otherwise Parallel's free MCP server.                       |
| **Workspace**      | Always on                         | `query_workspace`. Rooted at the Scout repo, so Scout can answer questions about its own codebase.                             |
| **CRM**            | Always on                         | `query_crm`, `update_crm`. Contacts, projects, notes, follow-ups.                                                              |
| **Knowledge wiki** | Always on                         | `query_knowledge`, `update_knowledge`. Scout's prose memory.                                                                   |
| **Voice wiki**     | Always on                         | `query_voice`. A code-managed style guide for emails, Slack, X, and long-form writing.                                         |
| **Slack**          | `SLACK_BOT_TOKEN`                 | Intended to expose `query_slack` for read-only access. The pinned template also exposes `update_slack`; see the warning below. |
| **Google Drive**   | `GOOGLE_SERVICE_ACCOUNT_FILE`     | `query_gdrive`. Read-only access to files, folders, and contents.                                                              |
| **MCP**            | Registered in `scout/contexts.py` | One `query_mcp_<slug>` per server.                                                                                             |

<Warning>
  Scout intends Slack context access to be read-only, but the pinned template does not pass `write=False` when it creates `SlackContextProvider`. Configuring `SLACK_BOT_TOKEN` currently exposes `update_slack`. To enforce a read-only context provider, set `write=False` in `scout/contexts.py` before deployment. The linked Slack manifest grants write scopes because the separate Slack interface uses the same bot token to reply.
</Warning>

Setup for each provider is covered in the Scout README's [Context Providers](https://github.com/agno-agi/scout#context-providers) section.

### Self-building knowledge

Most information Scout learns from working with you is perfect for a wiki and a CRM, so it maintains both.

| System   | Purpose                                                                |
| -------- | ---------------------------------------------------------------------- |
| **Wiki** | Scout's prose memory: pages about your company, projects, and runbooks |
| **CRM**  | People and relationships: contacts, projects, notes, follow-ups        |

Both start empty. Ask Scout to save that Josh from Anthropic shared a new RLM paper and to file the paper in the wiki. Scout can update both stores and link the records. See [How Scout works](https://github.com/agno-agi/scout#how-scout-works) in the README for how both systems work.

## Run locally

You need [Docker Desktop](https://docs.docker.com/desktop/) installed and running.

```bash theme={null}
git clone https://github.com/agno-agi/scout && cd scout

cp example.env .env
# set OPENAI_API_KEY in .env

docker compose up -d --build
```

Scout is now running at `http://localhost:8000`. The [Scout README](https://github.com/agno-agi/scout#quick-start) has the full walkthrough.

### Chat with Scout

1. Open [os.agno.com](https://os.agno.com) and log in.
2. Click **Add OS**, choose **Local**, enter `http://localhost:8000`, then **Connect**.
3. Try the pre-configured prompts.

## Deploy to Railway

Scout runs on any cloud provider. We provide scripts for Railway.

**Prerequisites:** [Railway CLI](https://docs.railway.app/guides/cli) installed and `railway login` run.

```bash theme={null}
cp .env .env.production
```

Edit `.env.production` if any values should differ from local, like a different Slack workspace or production-only credentials. The Railway scripts read `.env.production` first and fall back to `.env`.

```bash theme={null}
./scripts/railway/up.sh
```

The `up.sh` script provisions PostgreSQL and the `scout` service, then creates your public domain.

Your first deploy will fail. That's expected. Production endpoints require RBAC authorization by default, and without a `JWT_VERIFICATION_KEY` the app refuses to serve traffic. Scout's job is to keep your company data off the public web. To get your key:

1. Open [os.agno.com](https://os.agno.com), click **Add OS** → **Live**, and enter your Railway domain.
2. Enable **Token Based Authorization**.
3. Paste the public key into `.env.production` as `JWT_VERIFICATION_KEY` (the full PEM block, no surrounding quotes).
4. Sync the env. Railway auto-deploys when values change.

```bash theme={null}
./scripts/railway/env.sh       # sync .env.production to Railway
./scripts/railway/redeploy.sh  # push code updates after up.sh
```

For production, swap the knowledge wiki to a Git-backed repo so pages survive container restarts. The README's [Deploy to Railway](https://github.com/agno-agi/scout#deploy-to-railway) section covers that, plus connecting the repo to Railway for auto-deploys on every push.

## Connect to Slack

Scout is designed to live in Slack as your teammate. Each Slack thread becomes a session with its own context, so follow-ups in the same thread carry forward.

1. Get a public URL Slack can reach: `ngrok http 8000` locally, or your Railway domain in production.
2. Create the Slack app from the manifest in Scout's [Slack setup guide](https://github.com/agno-agi/scout/blob/main/docs/SLACK_CONNECT.md).
3. Set `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` in `.env`.
4. Restart Scout with `docker compose up -d`.

Setting `SLACK_BOT_TOKEN` activates the Slack context provider. The pinned template also exposes `update_slack` as described above. Adding `SLACK_SIGNING_SECRET` enables the Slack interface so Scout can reply in your workspace.

## Example prompts

Try these once Scout is up. Each one routes to the provider that owns the answer.

| Prompt                                                 | What Scout does                                                                         |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| "Find the latest benchmark numbers for model X."       | `query_web`, with cited sources                                                         |
| "Save that as a note."                                 | `update_crm` inserts into `scout.scout_notes`                                           |
| "File a runbook for incident response."                | `update_knowledge` writes a markdown page under `wiki/knowledge/runbooks/`              |
| "Track my coffee consumption: flat white, extra shot." | `update_crm` creates `scout.scout_coffee_orders` and inserts the row. Schema on demand. |
| "Draft a Slack message announcing the launch."         | `query_voice` loads the style guide, then Scout drafts in that voice                    |

## Run evals

Scout ships three eval tiers. PostgreSQL must be running for every tier: `docker compose up -d scout-db`.

| Tier           | Command                  | What it catches                                                            |
| -------------- | ------------------------ | -------------------------------------------------------------------------- |
| **Wiring**     | `python -m evals wiring` | Tool shape drift and missing schema guards. Code-level invariants, no LLM. |
| **Behavioral** | `python -m evals`        | Wrong tool choices, missing response content, forbidden tools firing.      |
| **Judges**     | `python -m evals judges` | Answer quality, LLM-scored.                                                |

Run a single case with `python -m evals --case <id>`. See [EVALS.md](https://github.com/agno-agi/scout/blob/main/docs/EVALS.md) for the full picture.

## Source

The [GitHub repo](https://github.com/agno-agi/scout) has the full provider setup guides under `docs/` and implementation notes in `AGENTS.md`.