Skip to content

Commit b0e64a9

Browse files
hugodutkahugodutka
authored
chore: add scout readme (#94)
1 parent 3970fff commit b0e64a9

File tree

2 files changed

+221
-2
lines changed

2 files changed

+221
-2
lines changed

‎packages/scout-agent/README.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# @blink-sdk/scout-agent
2+
3+
Scout is a foundation for quickly building AI agents that respond in Slack and GitHub, search the web, and run code in isolated environments. You can extend Scout with your own tools to build custom agents, or disable features you don't need.
4+
5+
## Installation
6+
7+
```bash
8+
bun add @blink-sdk/scout-agent
9+
```
10+
11+
## Quick Start
12+
13+
The following example is a fully-functional agent that responds in Slack and GitHub, searches the web, and runs code in isolated environments.
14+
15+
```typescript
16+
import { Scout } from "@blink-sdk/scout-agent";
17+
import * as blink from "blink";
18+
import { streamText } from "ai";
19+
20+
// Create a Blink agent
21+
const agent = new blink.Agent<Message>();
22+
23+
// Initialize Scout with desired integrations
24+
const scout = new Scout({
25+
agent,
26+
github: {
27+
appID: process.env.GITHUB_APP_ID,
28+
privateKey: process.env.GITHUB_PRIVATE_KEY, // base64 encoded
29+
webhookSecret: process.env.GITHUB_WEBHOOK_SECRET,
30+
},
31+
slack: {
32+
botToken: process.env.SLACK_BOT_TOKEN,
33+
signingSecret: process.env.SLACK_SIGNING_SECRET,
34+
},
35+
webSearch: {
36+
exaApiKey: process.env.EXA_API_KEY,
37+
},
38+
compute: { type: "docker" },
39+
});
40+
41+
// Handle webhooks
42+
agent.on("request", async (request) => {
43+
const url = new URL(request.url);
44+
if (url.pathname.startsWith("/slack")) {
45+
return scout.handleSlackWebhook(request);
46+
}
47+
if (url.pathname.startsWith("/github")) {
48+
return scout.handleGitHubWebhook(request);
49+
}
50+
});
51+
52+
// Handle chat messages
53+
agent.on("chat", async ({ id, messages }) => {
54+
const params = await scout.buildStreamTextParams({
55+
messages,
56+
chatID: id,
57+
model: "anthropic/claude-opus-4.5",
58+
});
59+
return streamText(params);
60+
});
61+
```
62+
63+
## Integrations
64+
65+
All integrations are optional - include only what you need.
66+
67+
### ScoutOptions
68+
69+
| Option | Type | Required | Description |
70+
| ----------- | ---------------------- | -------- | --------------------------------------- |
71+
| `agent` | `blink.Agent<Message>` | Yes | Blink agent instance |
72+
| `github` | `GitHubConfig` | No | GitHub App configuration |
73+
| `slack` | `SlackConfig` | No | Slack App configuration |
74+
| `webSearch` | `WebSearchConfig` | No | Exa web search configuration |
75+
| `compute` | `ComputeConfig` | No | Docker or Daytona compute configuration |
76+
| `logger` | `Logger` | No | Custom logger instance |
77+
78+
### GitHub
79+
80+
Scout provides full GitHub integration including:
81+
82+
- **Pull Request Management**: Create, update, and manage PRs
83+
- **Webhook Handling**: Respond to PR merges, reviews, comments, and check runs
84+
- **Repository Operations**: Read files, create branches, commit changes
85+
- **GitHub App Authentication**: Secure authentication via GitHub Apps
86+
87+
Webhook events are automatically routed back to the originating chat conversation.
88+
89+
```typescript
90+
{
91+
appID: string; // GitHub App ID
92+
privateKey: string; // GitHub App private key (base64 encoded)
93+
webhookSecret: string; // Webhook verification secret
94+
}
95+
```
96+
97+
### Slack
98+
99+
- **App Mentions**: Respond when mentioned in channels
100+
- **Direct Messages**: Handle DMs to the bot
101+
- **Thread Conversations**: Maintain context in threaded replies
102+
- **Status Updates**: Post progress updates to Slack threads
103+
104+
```typescript
105+
{
106+
botToken: string; // Slack bot OAuth token
107+
signingSecret: string; // Slack signing secret for webhook verification
108+
}
109+
```
110+
111+
### Web Search
112+
113+
Query the web using the Exa API.
114+
115+
```typescript
116+
{
117+
exaApiKey: string; // Exa API key
118+
}
119+
```
120+
121+
### Compute
122+
123+
Execute code in isolated environments:
124+
125+
- **Workspace Initialization**: Create and configure compute environments
126+
- **Git Authentication**: Authenticate Git with GitHub App tokens
127+
- **Process Execution**: Run shell commands with stdout/stderr capture
128+
- **File Operations**: Read, write, and manage files in the workspace
129+
130+
**Docker (local containers):**
131+
132+
```typescript
133+
{
134+
type: "docker";
135+
}
136+
```
137+
138+
**Daytona (cloud sandboxes):**
139+
140+
```typescript
141+
{
142+
type: "daytona",
143+
options: {
144+
apiKey: string // Daytona API key
145+
computeServerPort: number // Port for compute server
146+
snapshot: string // Snapshot with Blink compute server
147+
autoDeleteIntervalMinutes?: number // Auto-cleanup interval (default: 60)
148+
envVars?: Record<string, string> // Environment variables for sandboxes
149+
labels?: Record<string, string> // Labels for sandboxes
150+
}
151+
}
152+
```
153+
154+
## API Reference
155+
156+
### Scout Class
157+
158+
#### Constructor
159+
160+
```typescript
161+
new Scout(options: ScoutOptions)
162+
```
163+
164+
#### Methods
165+
166+
**`handleSlackWebhook(request: Request): Promise<Response>`**
167+
168+
Process incoming Slack webhook requests. Handles app mentions and direct messages.
169+
170+
**`handleGitHubWebhook(request: Request): Promise<Response>`**
171+
172+
Process incoming GitHub webhook requests. Routes events to associated chat conversations.
173+
174+
**`buildStreamTextParams(options: BuildStreamTextParamsOptions): Promise<StreamTextParams>`**
175+
176+
Build parameters for the AI SDK's `streamText()` function with all configured tools.
177+
178+
```typescript
179+
interface BuildStreamTextParamsOptions {
180+
messages: Message[]; // Chat messages
181+
chatID: string; // Chat conversation ID
182+
model: LanguageModel; // AI model to use
183+
tools?: Tools; // Additional custom tools
184+
maxOutputTokens?: number; // Max tokens (default: 16000)
185+
providerOptions?: ProviderOptions;
186+
getGithubAppContext?: () => Promise<GitHubAppContext | undefined>;
187+
}
188+
```
189+
190+
Returns:
191+
192+
```typescript
193+
{
194+
model: LanguageModel
195+
messages: ModelMessage[]
196+
maxOutputTokens: number
197+
providerOptions?: ProviderOptions
198+
tools: Tools // Combined built-in and custom tools
199+
}
200+
```
201+
202+
## Tools Provided
203+
204+
When configured, Scout provides these tools to the AI agent:
205+
206+
| Category | Tools | Description |
207+
| ---------- | --------------------------------- | -------------------------------------------- |
208+
| GitHub | `github_*` | Repository operations, PR management, issues |
209+
| Slack | `slack_*` | Message sending, thread management |
210+
| Web Search | `web_search` | Query the web via Exa |
211+
| Compute | `initialize_workspace` | Create compute environment |
212+
| Compute | `workspace_authenticate_git` | Set up Git authentication |
213+
| Compute | `process_execute`, `process_wait` | Run shell commands |
214+
| Compute | `file_*`, `directory_*` | File system operations |
215+
216+
## License
217+
218+
See the root of the repository for license information.

‎packages/scout-agent/package.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "@blink-sdk/scout-agent",
33
"description": "A general-purpose AI agent with GitHub, Slack, web search, and compute capabilities built on Blink SDK.",
4-
"version": "0.0.6",
4+
"version": "0.0.7",
55
"type": "module",
66
"keywords": [
77
"blink",
@@ -25,7 +25,8 @@
2525
"url": "https://github.com/coder/blink/issues"
2626
},
2727
"files": [
28-
"dist"
28+
"dist",
29+
"README.md"
2930
],
3031
"scripts": {
3132
"build": "tsdown",

0 commit comments

Comments
 (0)