Skip to content

Commit afe0c19

Browse files
hugodutkahugodutka
authored
chore: update readme (#210)
1 parent 18917d4 commit afe0c19

1 file changed

Lines changed: 28 additions & 338 deletions

File tree

‎README.md‎

Lines changed: 28 additions & 338 deletions
Original file line numberDiff line numberDiff line change
@@ -5,365 +5,55 @@
55
<img src="./scripts/logo-black.svg" style="height: 40px;">
66
</a>
77

8-
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
98
[![discord](https://img.shields.io/discord/747933592273027093?label=discord)](https://discord.gg/coder)
109
![NPM Version](https://img.shields.io/npm/v/blink)
1110

12-
Blink is a way to build and deploy chat agents with the AI SDK.
11+
Blink is a self-hosted platform for building and running custom, in-house AI agents. They respond in Slack, GitHub, and a browser-based UI. They can search the web, run code in isolated environments, and securely access company data - all under your full control.
1312

14-
```ts
15-
import { Agent } from "blink";
16-
import { sendMessages } from "ai";
13+
![Blink Demo](https://github.com/user-attachments/assets/7f272246-f4e3-4e94-9619-a91d2013db4a)
1714

18-
const agent = new Agent();
15+
## Features
1916

20-
agent.on("chat", ({ messages }) => {
21-
return sendMessages({
22-
model: "anthropic/claude-sonnet-4.5",
23-
messages: convertToModelMessages(messages),
24-
});
25-
});
26-
27-
agent.serve();
28-
```
29-
30-
To chat with the agent, run `blink dev` to enter a terminal interface.
31-
32-
- Leverages the familiar [AI SDK](https://github.com/vercel/ai) at it's core.
33-
- SDKs for making Slack and GitHub bots.
34-
- Run your agent locally without ever deploying to the cloud.
17+
- 🖥️ **Web UI** where you can chat with agents
18+
- 🛠️ **Blink SDK** - a set of libraries for building agents compatible with the Blink platform
19+
- ⚙️ **Blink CLI** - a command-line tool for developing agents locally
20+
- 🔍 **Observability** - use the web UI to view logs and traces
21+
- 📦 **Docker-based deployment** - agents are deployed as Docker containers
22+
- 🔒 **User and organization management** - invite your team to use and collaborate on agents
23+
- 🤖 **Pre-built, fully-functional [Scout agent](./packages/scout-agent/README.md)**, which you can customize for your own use
3524

3625
## Get Started
3726

38-
Install Blink:
27+
### Requirements
3928

40-
```sh
41-
npm i -g blink
42-
```
29+
- Node.js 22+ or Bun
30+
- Docker (the server needs it to deploy agents)
4331

44-
Create your first agent:
32+
### Install and run the Blink server
4533

4634
```sh
47-
# creates the agent source code in your current directory
48-
blink init
49-
50-
# starts a hot-reloading terminal interface to chat with your agent
51-
blink dev
52-
```
53-
54-
Create a Slack bot in under a minute:
55-
56-
https://github.com/user-attachments/assets/6bb73e58-b4ae-4543-b2c0-0e1195113ba6
57-
58-
> [!NOTE]
59-
> You provide LLM API keys. `blink init` guides you through this, or add them to `.env.local` later.
60-
61-
## Deploy
62-
63-
If you wish to deploy your agent to the [cloud](https://blink.coder.com), run:
64-
65-
```sh
66-
blink deploy
67-
```
68-
69-
> [!IMPORTANT]
70-
> [Cloud](https://blink.coder.com) is not required to build Blink agents.
71-
> We guarantee that Blink agents will always be local-first.
72-
73-
## User Guide
74-
75-
### Developing an Agent
76-
77-
Blink has two modes: run and edit (toggle with `ctrl+t`, or `/run` and `/edit`). Run mode is blue, edit mode is orange. Run mode allows you to chat with your agent. Edit mode allows you to take context from run mode, and edit the agent.
78-
79-
Chat in run mode, switch to edit mode and provide feedback, then go back to run mode and continue chatting. Agents hot-reload as you develop, so changes are reflected instantly.
80-
81-
> [!NOTE]
82-
> Run mode cannot see edit mode messages.
83-
84-
https://github.com/user-attachments/assets/4abd47ad-4b59-41d5-abda-27ed902ae69b
85-
86-
### Chats
87-
88-
Blink allows you to start new chats from web requests:
89-
90-
```ts
91-
import blink from "blink";
92-
93-
const agent = blink.agent();
94-
95-
agent.on("request", async (request, context) => {
96-
// Check if this is a request you'd like to start a chat for.
97-
// e.g. if this is a webhook from Slack, start a chat for that thread.
98-
99-
// Specify a unique key for the chat so that on subsequent requests, the same chat is used.
100-
const chat = await blink.chat.upsert(`slack-${request.body.thread_ts}`);
101-
102-
await blink.chat.message(
103-
chat.id,
104-
{
105-
role: "user",
106-
parts: [
107-
{
108-
type: "text",
109-
text: "Hello, how can I help you today?",
110-
},
111-
],
112-
},
113-
{
114-
// Blink manages chat state for you. Interrupt, enqueue, or append messages.
115-
behavior: "interrupt",
116-
}
117-
);
118-
119-
// This would trigger the chat event handler in your agent.
120-
});
121-
122-
// ... agent.on("chat", ...) ...
123-
124-
agent.serve();
125-
```
126-
127-
Locally, all chats are stored in `./.blink/chats/<key>.json` relative to where your agent is running.
128-
129-
In the cloud, chats keys are namespaced per-agent.
130-
131-
### Storage
132-
133-
Blink has a persistent key-value store for your agent:
134-
135-
```ts
136-
import { convertToModelMessages, streamText, tool } from "ai";
137-
import blink from "blink";
138-
import { z } from "zod";
139-
140-
const agent = blink.agent();
141-
142-
agent.on("chat", async ({ messages }) => {
143-
return streamText({
144-
model: "anthropic/claude-sonnet-4",
145-
system: "You are a helpful assistant.",
146-
messages: convertToModelMessages(messages),
147-
148-
tools: {
149-
set_memory: tool({
150-
description: "Set a value to remember later.",
151-
inputSchema: z.object({
152-
key: z.string(),
153-
value: z.string(),
154-
}),
155-
execute: async ({ key, value }) => {
156-
await blink.storage.set(key, value);
157-
return "Saved memory!";
158-
},
159-
}),
160-
get_memory: tool({
161-
description: "Get a value from your memory.",
162-
inputSchema: z.object({
163-
key: z.string(),
164-
}),
165-
execute: async ({ key }) => {
166-
const value = await blink.storage.get(key);
167-
return `The value for ${key} is ${value}`;
168-
},
169-
}),
170-
delete_memory: tool({
171-
description: "Delete a value from your memory.",
172-
inputSchema: z.object({
173-
key: z.string(),
174-
}),
175-
execute: async ({ key }) => {
176-
await blink.storage.delete(key);
177-
return `Deleted memory for ${key}`;
178-
},
179-
}),
180-
},
181-
});
182-
});
183-
184-
agent.serve();
35+
npm install -g blink-server
36+
blink-server
18537
```
18638

187-
Locally, all storage is in `./.blink/storage.json` relative to where your agent is running.
188-
189-
In the cloud, storage is namespaced per-agent.
190-
191-
### Tools
192-
193-
Blink has helpers for [tool approvals](#manual-approval), and [commonly used tools](#toolsets).
194-
195-
#### Manual Approval
39+
Open the Blink web UI in your browser and create your first agent. Alternatively, you may run the server [with Docker](https://blink.coder.com/docs/server/docker) (TODO: correct link).
19640

197-
Some tools you'd prefer to approve manually, particularly if they're destructive.
41+
## Documentation
19842

199-
```ts
200-
import { convertToModelMessages, streamText, tool } from "ai";
201-
import blink from "blink";
202-
import { z } from "zod";
203-
204-
const agent = blink.agent();
205-
206-
agent.on("chat", async ({ messages }) => {
207-
return streamText({
208-
model: "anthropic/claude-sonnet-4",
209-
system: "You are a helpful assistant.",
210-
messages: convertToModelMessages(messages),
211-
212-
tools: {
213-
harmless_tool: tool({
214-
description: "A harmless tool.",
215-
inputSchema: z.object({
216-
name: z.string(),
217-
}),
218-
execute: async ({ name }) => {
219-
return `Hello, ${name}!`;
220-
},
221-
}),
222-
...blink.tools.withApproval({
223-
messages,
224-
tools: {
225-
destructive_tool: tool({
226-
description: "A destructive tool.",
227-
inputSchema: z.object({
228-
name: z.string(),
229-
}),
230-
execute: async ({ name }) => {
231-
return `Destructive tool executed!`;
232-
},
233-
}),
234-
},
235-
}),
236-
},
237-
});
238-
});
239-
240-
agent.serve();
241-
```
43+
For a closer look at Blink, visit [blink.coder.com/docs](https://blink.coder.com/docs).
24244

243-
Blink will require explicit approval by the user before `destructive_tool` is executed - displaying a UI to the user to approve or reject the tool call.
45+
## Current State of the Project
24446

245-
#### Toolsets
47+
We've been using Blink at [Coder](https://coder.com) for a few months now. We built in-house agents that:
24648

247-
Blink has SDK packages for common tools, like Slack, GitHub, and Search:
248-
249-
```ts
250-
import github from "@blink-sdk/github";
251-
import { convertToModelMessages, streamText } from "ai";
252-
import blink from "blink";
253-
254-
const agent = blink.agent();
255-
256-
agent.on("chat", async ({ messages }) => {
257-
return streamText({
258-
model: "anthropic/claude-sonnet-4",
259-
system: "You are a helpful assistant.",
260-
messages: convertToModelMessages(messages),
261-
262-
tools: {
263-
...github.tools,
264-
},
265-
});
266-
});
267-
268-
agent.serve();
269-
```
270-
271-
By default, GitHub tools will not have authentication. Provide context to tools:
272-
273-
```ts
274-
import blink from "blink";
275-
276-
blink.tools.withContext(github.tools, {
277-
accessToken: process.env.GITHUB_TOKEN,
278-
// optionally, specify app auth, or your own Octokit instance
279-
});
280-
```
281-
282-
#### Customizing Tools
283-
284-
You can override any descriptions to customize behavior:
285-
286-
```ts
287-
import github from "@blink-sdk/github";
288-
import { convertToModelMessages, streamText } from "ai";
289-
import blink from "blink";
290-
291-
const agent = blink.agent();
292-
293-
agent.on("chat", async ({ messages }) => {
294-
return streamText({
295-
model: "anthropic/claude-sonnet-4",
296-
system: "You are a helpful assistant.",
297-
messages: convertToModelMessages(messages),
298-
299-
tools: {
300-
...github.tools,
301-
// Override the default tool with your own description.
302-
create_issue: {
303-
...github.tools.create_issue,
304-
description: "Create a GitHub issue. *Never* tag users.",
305-
},
306-
},
307-
});
308-
});
309-
310-
agent.serve();
311-
```
312-
313-
### Custom Models
314-
315-
You do not need to use the AI SDK with Blink. Return a `Response` in `sendMessages` using `withResponseFormat`:
316-
317-
```ts
318-
import * as blink from "blink";
319-
import OpenAI from "openai";
320-
321-
const client = new OpenAI();
322-
const agent = blink.agent();
323-
324-
agent.on("chat", async ({ messages }) => {
325-
const stream = await client.chat.completions
326-
.create({
327-
model: "gpt-4o",
328-
messages: messages.map((m) => ({
329-
role: m.role,
330-
content: m.parts
331-
.map((p) => {
332-
if (p.type === "text") {
333-
return p.text;
334-
}
335-
})
336-
.join("\n"),
337-
})),
338-
stream: true,
339-
})
340-
.withResponse();
341-
return blink.withResponseFormat(stream.response, "openai-chat");
342-
});
343-
344-
agent.serve();
345-
```
346-
347-
### Custom Bundling
348-
349-
Create a `blink.config.ts` file in your project root (next to `package.json`):
350-
351-
```ts
352-
import { defineConfig, buildWithEsbuild } from "blink/build";
353-
354-
export default defineConfig({
355-
entry: "src/agent.ts",
356-
outdir: "dist",
357-
build: buildWithEsbuild({
358-
// ... esbuild options ...
359-
}),
360-
});
361-
```
49+
- help our customers in Slack with questions related to the Coder product by analyzing the [coder/coder repository](https://github.com/coder/coder)
50+
- automatically diagnose flaky tests in our CI pipeline, create [issues](https://github.com/coder/internal/issues/1278), and assign relevant engineers to fix them
51+
- answer questions from our sales team by aggregating data from our CRM and sales tools
36252

363-
By default, Blink uses [esbuild](https://esbuild.github.io/) to bundle your agent.
53+
and more.
36454

365-
The `build` function can be customized to use a different bundler if you wish.
55+
That being said, Blink is still in early access. You may encounter bugs and missing features. If you do, please [file an issue](https://github.com/coder/blink/issues/new).
36656

367-
## Blink Documentation
57+
## License
36858

369-
For a closer look at Blink, visit [docs.blink.coder.com](https://docs.blink.coder.com/).
59+
Server code is licensed under AGPLv3. Agent SDKs are licensed under MIT.

0 commit comments

Comments
 (0)