> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Biblos: a grounded Slack librarian
> Answer process questions in Slack from approved playbooks, and refuse when the library doesn't hold enough evidence.
Biblos is a one-shot TypeScript agent for Slack knowledge questions. A mention in an allowlisted channel starts a Guild session. Biblos reads only that thread, retrieves a bounded set of snippets from a Pinecone Assistant, and writes one reply in the same thread. When retrieval comes back weak or empty, Biblos sends a fixed refusal instead of inventing a process.
```text theme={null}
Slack mention -> channel guard -> bounded thread read -> Pinecone retrieve
-> grounded reply
-> fixed refusal
```
View the agent and its source on the Agent Hub.
## At a glance
* **Agent type:** auto-managed [TypeScript agent](/guide/coded-agents)
* **Integrations:** [Slack](/integrations/slack) (`guildai~slack`) for reactions, thread reads, posts, and updates, and the `dkountanis~pinecone-assistant` integration (`1.0.0`) for ranked retrieval
* **Runs from:** an [event trigger](/platform/event-triggers) on Slack `app_mention`
* **LLM calls:** at most one per mention, with no tools
**What it does:**
* Reacts with `:eyes:` and posts a `Writing…` placeholder right away
* Reads at most 20 Slack messages and retrieves at most 8 snippets per run
* Calls the LLM only when the evidence clears a configured floor
* Replies to the exact channel and thread from the validated webhook payload
* Neutralizes mass mentions and caps the length of what it posts
* Adds a delivery marker to each reply to guard against processing the same event twice
* Returns the reply instead of posting it when called with `delivery: "return"`
The Pinecone integration is required. You still upload your playbooks in Pinecone, because the integration exposes retrieval, not file upload.
## How it works
The input is a bounded Slack `event_callback` object. Biblos rejects an event from a channel that isn't allowlisted, or one a bot wrote, before it reads Slack, Pinecone, or the LLM.
`conversations.replies` reads at most 20 messages from the thread the mention came from. Biblos treats Slack text as untrusted content, never as authority to change its tools, recipients, or policy.
The mention and the thread context become one query. Pinecone returns at most eight snippets. Deterministic code applies the minimum score and the minimum number of snippets before the LLM is allowed to write anything.
With enough evidence, Biblos writes one short answer grounded only in the selected snippets. Without it, Biblos sends its fixed "above my head" reply. Where it can, Biblos updates the placeholder in place.
## Build the agent
### Define the webhook contract
Keep the variants inside an object-root schema. Unknown fields in the Slack envelope are stripped before orchestration or prompt construction:
```ts theme={null}
import { z } from "zod";
const slackTimestampSchema = z
.string()
.min(12)
.max(32)
.regex(/^\d{10,16}\.\d{1,6}$/);
const slackEventSchema = z
.object({
type: z.literal("app_mention"),
channel: z.string().min(9).max(32).regex(/^[CDG][A-Z0-9]+$/),
user: z.string().max(32).optional(),
text: z.string().min(1).max(4_000),
ts: slackTimestampSchema,
thread_ts: slackTimestampSchema.optional(),
bot_id: z.string().max(32).optional(),
subtype: z.string().max(64).optional(),
})
.strip();
export const inputSchema = z
.object({
type: z.literal("event_callback").optional(),
event_id: z.string().min(2).max(64).regex(/^Ev[A-Za-z0-9]+$/),
event: slackEventSchema,
delivery: z.enum(["slack", "return"]).optional(),
})
.strip();
```
The channel and thread always come from this validated envelope. Don't add a separate destination the caller controls.
### Register only the operations you need
Register each Slack operation the agent uses with `guildServiceTool("slack", ...)` rather than importing a Slack tool package. The published source includes the complete endpoint metadata and response schemas, and pins each operation to a specific integration version:
```ts theme={null}
import { guildServiceTool } from "@guildai/agents-sdk";
const tools = {
slack_conversations_replies: guildServiceTool("slack", {
description: "Read up to 20 messages from one exact Slack thread.",
inputSchema: z.object({
channel: z.string(),
ts: z.number().positive(),
limit: z.literal(20),
}),
outputSchema: z.object({
ok: z.literal(true),
messages: z.array(z.object({ text: z.string().optional() })).max(20),
}),
}),
slack_chat_post_message: guildServiceTool("slack", {
description: "Post one reply to one exact Slack channel and thread.",
inputSchema: z.object({
channel: z.string(),
thread_ts: slackTimestampSchema,
text: z.string().min(1).max(2_800),
mrkdwn: z.literal(true),
reply_broadcast: z.literal(false),
unfurl_links: z.literal(false),
unfurl_media: z.literal(false),
}),
}),
pinecone_assistant_context_assistant: guildServiceTool(
"pinecone-assistant",
{
owner: "dkountanis",
versionNumber: "1.0.0",
description: "Retrieve bounded snippets from one Pinecone Assistant.",
inputSchema: z.object({
assistant_name: z.string().min(1).max(64),
query: z.string().min(1).max(4_000),
top_k: z.number().int().min(1).max(8),
multimodal: z.literal(false),
}),
},
),
};
```
For readability, this excerpt shows only the thread-read, final-post, and retrieve contracts. The same file also registers `reactions.add` and `chat.update`, which the orchestration below uses. Copy the complete definitions from `agent.ts` when you build a fork.
Before you adapt these definitions, confirm the current schemas:
```bash theme={null}
guild integration operation list --json
```
### Gate the evidence deterministically
Evidence selection is synchronous, can be tested on its own, and runs before the LLM:
```ts theme={null}
export function selectEvidence(
snippets: readonly LibrarySnippet[],
minCount = 1,
minScore = 0.15,
): EvidenceDecision {
const selected = snippets
.filter((snippet) => snippet.content.trim().length > 0)
.filter((snippet) => snippet.score >= minScore)
.slice(0, 8)
.map((snippet) => ({
content: snippet.content.slice(0, 2_000),
score: snippet.score,
fileName: snippet.fileName,
}));
return {
sufficient: selected.length >= minCount,
snippets: selected,
};
}
```
### Acknowledge, retrieve, and reply
The two Slack acknowledgements are independent, so the agent sends them together with [`task.gatherSettled`](/sdk/task-object#task-gathersettled-—-concurrent-calls-with-individual-outcomes). The tool calls are written inline in the array, so no unresolved call is held in a variable across a suspend:
```ts theme={null}
async function runBiblos(input: Input, task: Task): Promise