Refactor TestSubscribeFrom for improved timing accuracy and reliability
- Adjusted sleep durations to 1100ms to enhance test stability in CI environments. - Modified timestamp calculations to ensure millisecond precision, improving event timing accuracy in tests.
This commit is contained in:
Max
parent
edf921324b
commit
63c91d7f28
1 changed files with 937 additions and 0 deletions
937
agent/search/DESIGN.md
Normal file
937
agent/search/DESIGN.md
Normal file
|
|
@ -0,0 +1,937 @@
|
|||
# Search Module Design
|
||||
|
||||
## Overview
|
||||
|
||||
The Search module provides a unified RAG (Retrieval-Augmented Generation) interface for Yao Agent, supporting three search types:
|
||||
|
||||
| Type | Source | Use Case |
|
||||
| ----- | -------------- | ---------------------------------------------------- |
|
||||
| `web` | Internet | Real-time information, news, external knowledge |
|
||||
| `kb` | Knowledge Base | Documents, FAQs, internal knowledge (vector + graph) |
|
||||
| `db` | Database | Structured data from Yao Models (QueryDSL) |
|
||||
|
||||
The module follows the **Handler + Registry** pattern consistent with the `content` module, and exposes JSAPI for flexible usage in Create/Next hooks.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Unified JSAPI**: `ctx.search.Web()`, `ctx.search.KB()`, `ctx.search.DB()`, `ctx.search.Parallel()`
|
||||
- **Citation System**: Auto-generate citation IDs (`#ref:xxx`) for LLM reference
|
||||
- **Real-time Output**: Stream search progress to client
|
||||
- **Trace Integration**: Report search operations to user for transparency
|
||||
- **Reranking**: Score, Model, Agent, or MCP-based result reranking
|
||||
- **Graceful Degradation**: Search errors don't block agent flow
|
||||
|
||||
## Quick Start
|
||||
|
||||
```typescript
|
||||
// In Create hook (assistants/my-assistant/index.ts)
|
||||
function Create(ctx, messages, options) {
|
||||
const query = messages[messages.length - 1].content;
|
||||
|
||||
// Simple web search
|
||||
const result = ctx.search.Web(query, { limit: 5 });
|
||||
|
||||
// Or parallel search across all sources
|
||||
const [web, kb, db] = ctx.search.Parallel([
|
||||
{ type: "web", query, limit: 5 },
|
||||
{ type: "kb", query, collections: ["docs"] },
|
||||
{ type: "db", query, models: ["product"] },
|
||||
]);
|
||||
|
||||
return {
|
||||
messages: [{ role: "system", content: formatContext(web, kb, db) }],
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Goals
|
||||
|
||||
1. **Unified Interface**: Single API for web, knowledge base, and database search
|
||||
2. **Flexibility**: Support built-in handlers and external tools (MCP/Agent delegation)
|
||||
3. **JSAPI Support**: Enable search calls from Create/Next hooks via JavaScript
|
||||
4. **Parallel Execution**: Support concurrent web + KB + DB searches
|
||||
5. **Graceful Degradation**: Search failures should not block the main agent flow
|
||||
6. **Real-time Feedback**: Stream search progress and results to users via output
|
||||
7. **Traceability**: Report search operations to users for transparency
|
||||
8. **Citation Support**: Enable LLM to reference search results with trackable citations
|
||||
|
||||
## Architecture
|
||||
|
||||
### Search Flow Diagram
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Stream Start] --> B{Options.Search?}
|
||||
B -->|false| C[Skip Search]
|
||||
B -->|true/nil| D{Hook Handled?}
|
||||
D -->|Yes| C
|
||||
D -->|No| E[Auto Search]
|
||||
|
||||
E --> F{Check Assistant Config}
|
||||
F --> G[Web Search]
|
||||
F --> H[KB Search]
|
||||
F --> I[DB Search]
|
||||
|
||||
G --> J[Parallel Execute]
|
||||
H --> J
|
||||
I --> J
|
||||
|
||||
J --> K[Merge Results]
|
||||
K --> L[Rerank]
|
||||
L --> M[Generate Citations]
|
||||
M --> N[Inject to System Prompt]
|
||||
|
||||
C --> O[LLM Call]
|
||||
N --> O
|
||||
O --> P[Output with Citations]
|
||||
```
|
||||
|
||||
### Integration in Stream()
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant Stream
|
||||
participant CreateHook
|
||||
participant Search
|
||||
participant LLM
|
||||
participant Output
|
||||
|
||||
Client->>Stream: Stream(ctx, messages, options)
|
||||
Stream->>Stream: Initialize
|
||||
|
||||
alt Has Create Hook
|
||||
Stream->>CreateHook: Create(ctx, messages, options)
|
||||
CreateHook-->>Stream: response (may include search results)
|
||||
end
|
||||
|
||||
alt Options.Search != false AND not handled by Hook
|
||||
Stream->>Search: AutoSearch(ctx, messages)
|
||||
Search->>Search: Web/KB/DB in parallel
|
||||
Search->>Search: Rerank & Citations
|
||||
Search->>Output: search_start, search_result, search_complete
|
||||
Search-->>Stream: Inject search context to messages
|
||||
end
|
||||
|
||||
Stream->>LLM: Execute with search context
|
||||
LLM->>Output: Stream response with #ref:xxx
|
||||
Stream-->>Client: Complete
|
||||
```
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
agent/search/
|
||||
├── DESIGN.md # This document
|
||||
├── interfaces.go # Core interfaces (Handler, Searcher)
|
||||
├── types.go # Type definitions (Request, Result, Citation, etc.)
|
||||
├── registry.go # Handler registry
|
||||
├── search.go # Main search logic and utilities
|
||||
├── jsapi.go # JavaScript API bindings for hooks
|
||||
├── trace.go # Trace node creation and management
|
||||
├── output.go # Real-time output/streaming to client
|
||||
├── citation.go # Citation ID generation and tracking
|
||||
├── rerank/ # Result reranking
|
||||
│ ├── interfaces.go # Reranker interface
|
||||
│ ├── score.go # Score-based reranking (default)
|
||||
│ ├── model.go # Model-based reranking (Cohere, etc.)
|
||||
│ ├── agent.go # Agent-based reranking (delegate to another assistant)
|
||||
│ └── mcp.go # MCP-based reranking (call MCP server tool)
|
||||
├── query/ # Query processing
|
||||
│ ├── interfaces.go # Query processor interface
|
||||
│ ├── keyword.go # Keyword extraction for web search
|
||||
│ ├── embedding.go # Embedding generation for KB search
|
||||
│ └── dsl.go # Query DSL generation for DB search
|
||||
├── web/ # Web search implementations
|
||||
│ ├── handler.go # Web search handler
|
||||
│ └── providers/ # Provider implementations
|
||||
│ ├── tavily.go
|
||||
│ └── serper.go
|
||||
├── kb/ # Knowledge base search
|
||||
│ ├── handler.go # KB search handler
|
||||
│ ├── vector.go # Vector similarity search
|
||||
│ └── graph.go # Graph-based association (GraphRAG)
|
||||
└── db/ # Database search (Yao Model/QueryDSL)
|
||||
├── handler.go # DB search handler
|
||||
├── query.go # QueryDSL builder
|
||||
└── schema.go # Model schema introspection
|
||||
```
|
||||
|
||||
## Core Interfaces
|
||||
|
||||
### Handler Interface
|
||||
|
||||
```go
|
||||
// Handler defines the interface for search implementations
|
||||
type Handler interface {
|
||||
// Type returns the search type this handler supports
|
||||
Type() SearchType
|
||||
|
||||
// CanHandle checks if this handler can process the given request
|
||||
CanHandle(ctx *context.Context, req *Request) bool
|
||||
|
||||
// Search executes the search and returns results
|
||||
Search(ctx *context.Context, req *Request) (*Result, error)
|
||||
}
|
||||
```
|
||||
|
||||
### Searcher Interface (Public API)
|
||||
|
||||
```go
|
||||
// Searcher is the main interface exposed to external callers
|
||||
type Searcher interface {
|
||||
// Search executes a single search request
|
||||
Search(ctx *context.Context, req *Request) (*Result, error)
|
||||
|
||||
// SearchMultiple executes multiple searches (potentially in parallel)
|
||||
SearchMultiple(ctx *context.Context, reqs []*Request) ([]*Result, error)
|
||||
}
|
||||
```
|
||||
|
||||
### QueryProcessor Interface
|
||||
|
||||
```go
|
||||
// QueryProcessor prepares queries for different search types
|
||||
type QueryProcessor interface {
|
||||
// ExtractKeywords extracts search keywords from user message (for web search)
|
||||
ExtractKeywords(ctx *context.Context, content string) ([]string, error)
|
||||
|
||||
// Embed generates vector embedding for query (for KB search)
|
||||
Embed(ctx *context.Context, content string, collection string) ([]float32, error)
|
||||
}
|
||||
```
|
||||
|
||||
### Reranker Interface
|
||||
|
||||
```go
|
||||
// Reranker reorders search results by relevance
|
||||
type Reranker interface {
|
||||
// Rerank reorders results based on query relevance
|
||||
Rerank(ctx *context.Context, query string, items []*ResultItem) ([]*ResultItem, error)
|
||||
}
|
||||
```
|
||||
|
||||
## Types
|
||||
|
||||
### SearchType
|
||||
|
||||
```go
|
||||
type SearchType string
|
||||
|
||||
const (
|
||||
SearchTypeWeb SearchType = "web" // Web/Internet search
|
||||
SearchTypeKB SearchType = "kb" // Knowledge base vector search
|
||||
SearchTypeDB SearchType = "db" // Database search (Yao Model/QueryDSL)
|
||||
)
|
||||
```
|
||||
|
||||
### RerankerType
|
||||
|
||||
```go
|
||||
type RerankerType string
|
||||
|
||||
const (
|
||||
RerankerTypeScore RerankerType = "score" // Simple score-based sorting (default)
|
||||
RerankerTypeModel RerankerType = "model" // Model-based reranking (Cohere, BGE, etc.)
|
||||
RerankerTypeAgent RerankerType = "agent" // Agent-based reranking (delegate to assistant)
|
||||
RerankerTypeMCP RerankerType = "mcp" // MCP-based reranking (call MCP server tool)
|
||||
)
|
||||
```
|
||||
|
||||
### Request
|
||||
|
||||
```go
|
||||
type Request struct {
|
||||
// Common fields
|
||||
Query string `json:"query"` // Search query (natural language)
|
||||
Type SearchType `json:"type"` // Search type: "web", "kb", or "db"
|
||||
Limit int `json:"limit,omitempty"` // Max results (default: 10)
|
||||
|
||||
// Web search specific
|
||||
Sites []string `json:"sites,omitempty"` // Restrict to specific sites
|
||||
TimeRange string `json:"time_range,omitempty"` // "day", "week", "month", "year"
|
||||
|
||||
// Knowledge base specific
|
||||
Collections []string `json:"collections,omitempty"` // KB collection IDs
|
||||
Threshold float64 `json:"threshold,omitempty"` // Similarity threshold (0-1)
|
||||
Graph bool `json:"graph,omitempty"` // Enable graph association
|
||||
|
||||
// Database search specific
|
||||
Models []string `json:"models,omitempty"` // Model IDs (e.g., "user", "agents.mybot.product")
|
||||
Wheres []QueryWhere `json:"wheres,omitempty"` // Pre-defined filters (optional)
|
||||
Orders []QueryOrder `json:"orders,omitempty"` // Sort orders (optional)
|
||||
Select []string `json:"select,omitempty"` // Fields to return (optional)
|
||||
|
||||
// Reranking
|
||||
Rerank *RerankOptions `json:"rerank,omitempty"`
|
||||
}
|
||||
|
||||
// QueryWhere represents a filter condition for DB search
|
||||
type QueryWhere struct {
|
||||
Field string `json:"field"` // Field name
|
||||
Op string `json:"op,omitempty"` // Operator: "=", "like", ">", "<", "in", etc. (default: "=")
|
||||
Value interface{} `json:"value"` // Filter value
|
||||
}
|
||||
|
||||
// QueryOrder represents a sort order for DB search
|
||||
type QueryOrder struct {
|
||||
Field string `json:"field"` // Field name
|
||||
Order string `json:"order,omitempty"` // "asc" or "desc" (default: "desc")
|
||||
}
|
||||
```
|
||||
|
||||
### RerankOptions
|
||||
|
||||
```go
|
||||
// RerankOptions controls result reranking
|
||||
type RerankOptions struct {
|
||||
Type string `json:"type,omitempty"` // "score", "model", "agent", "mcp"
|
||||
Model string `json:"model,omitempty"` // Model ID (for type="model")
|
||||
Agent string `json:"agent,omitempty"` // Agent ID (for type="agent")
|
||||
MCP string `json:"mcp,omitempty"` // MCP server ID (for type="mcp")
|
||||
TopK int `json:"top_k,omitempty"` // Return top K after reranking
|
||||
}
|
||||
```
|
||||
|
||||
### Result
|
||||
|
||||
```go
|
||||
type Result struct {
|
||||
Type SearchType `json:"type"` // Search type
|
||||
Query string `json:"query"` // Original query
|
||||
Items []*ResultItem `json:"items"` // Result items
|
||||
Total int `json:"total"` // Total matches
|
||||
Duration int64 `json:"duration_ms"` // Search duration in ms
|
||||
Error string `json:"error,omitempty"` // Error message if failed
|
||||
|
||||
// Graph associations (KB only, if enabled)
|
||||
GraphNodes []*GraphNode `json:"graph_nodes,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
### ResultItem
|
||||
|
||||
```go
|
||||
type ResultItem struct {
|
||||
// Citation
|
||||
CitationID string `json:"citation_id"` // Unique ID for LLM reference: "#ref:xxx"
|
||||
|
||||
// Common fields
|
||||
Title string `json:"title,omitempty"` // Title/headline
|
||||
Content string `json:"content"` // Main content/snippet
|
||||
URL string `json:"url,omitempty"` // Source URL
|
||||
Score float64 `json:"score,omitempty"` // Relevance score (0-1)
|
||||
|
||||
// KB specific
|
||||
DocumentID string `json:"document_id,omitempty"` // Source document ID
|
||||
Collection string `json:"collection,omitempty"` // Collection name
|
||||
|
||||
// DB specific
|
||||
Model string `json:"model,omitempty"` // Model ID
|
||||
RecordID interface{} `json:"record_id,omitempty"` // Record primary key
|
||||
Data map[string]interface{} `json:"data,omitempty"` // Full record data
|
||||
}
|
||||
```
|
||||
|
||||
### GraphNode
|
||||
|
||||
```go
|
||||
// GraphNode represents a related entity from knowledge graph
|
||||
type GraphNode struct {
|
||||
ID string `json:"id"`
|
||||
Type string `json:"type"` // Entity type
|
||||
Name string `json:"name"` // Entity name
|
||||
Description string `json:"description,omitempty"` // Entity description
|
||||
Relation string `json:"relation,omitempty"` // Relationship to query
|
||||
Score float64 `json:"score,omitempty"` // Relevance score
|
||||
Metadata map[string]interface{} `json:"metadata,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
## Citation System
|
||||
|
||||
Each search result has a unique `CitationID` for LLM reference.
|
||||
|
||||
### Citation Config
|
||||
|
||||
```go
|
||||
type CitationConfig struct {
|
||||
Format string `json:"format,omitempty"` // Default: "#ref:{id}"
|
||||
AutoInjectPrompt bool `json:"auto_inject_prompt,omitempty"` // Auto-add instructions to system prompt
|
||||
CustomPrompt string `json:"custom_prompt,omitempty"` // Override default prompt template
|
||||
}
|
||||
```
|
||||
|
||||
### Default Citation Prompt
|
||||
|
||||
When `AutoInjectPrompt` is enabled (default), the system prompt includes:
|
||||
|
||||
```
|
||||
When citing search results, use #ref:{id} format inline.
|
||||
Example: "According to studies #ref:a1b2, this is significant."
|
||||
|
||||
Available references:
|
||||
- #ref:a1b2 - Title of source 1
|
||||
- #ref:c3d4 - Title of source 2
|
||||
```
|
||||
|
||||
### Custom Prompt in Config
|
||||
|
||||
```yaml
|
||||
# assistants/my-assistant.yml
|
||||
search:
|
||||
citation:
|
||||
format: "[{id}]"
|
||||
auto_inject_prompt: true
|
||||
custom_prompt: "Cite using [{id}]. Sources: ..."
|
||||
```
|
||||
|
||||
## Trace Integration
|
||||
|
||||
Search operations create trace nodes to report execution details to users, providing transparency about what the agent is doing.
|
||||
|
||||
### Trace Node Structure
|
||||
|
||||
```
|
||||
search (type: "search")
|
||||
├── query // Original query
|
||||
├── search_type // "web", "kb", or "db"
|
||||
├── duration_ms
|
||||
├── status // "success", "failed"
|
||||
├── result_count
|
||||
└── children // Sub-operations
|
||||
├── embedding (kb only)
|
||||
├── vector_search (kb only)
|
||||
├── graph_search (kb, if enabled)
|
||||
├── dsl_build (db only)
|
||||
├── db_query (db only)
|
||||
└── rerank (if enabled)
|
||||
```
|
||||
|
||||
## Real-time Output
|
||||
|
||||
Search progress is streamed to the client via the output system.
|
||||
|
||||
### Output Message Types
|
||||
|
||||
```go
|
||||
const (
|
||||
TypeSearchStart = "search_start" // Search initiated
|
||||
TypeSearchResult = "search_result" // Result item (streamed)
|
||||
TypeSearchComplete = "search_complete" // Search completed
|
||||
)
|
||||
```
|
||||
|
||||
### Client Display Example
|
||||
|
||||
```
|
||||
🔍 Searching "latest AI developments"...
|
||||
|
||||
📄 Found 5 results:
|
||||
1. #ref:a1b2 - OpenAI Announces GPT-5
|
||||
2. #ref:c3d4 - Google's New AI Model
|
||||
...
|
||||
|
||||
✅ Search complete (1.2s)
|
||||
```
|
||||
|
||||
## JSAPI Integration
|
||||
|
||||
The Search module is exposed via `ctx.search` object in hook scripts.
|
||||
|
||||
### API Methods
|
||||
|
||||
```typescript
|
||||
// In hook scripts (index.ts)
|
||||
|
||||
// Web search
|
||||
ctx.search.Web(query: string, options?: WebOptions): Result
|
||||
|
||||
// Knowledge base search
|
||||
ctx.search.KB(query: string, options?: KBOptions): Result
|
||||
|
||||
// Database search (Yao Model/QueryDSL)
|
||||
ctx.search.DB(query: string, options?: DBOptions): Result
|
||||
|
||||
// Parallel search (multiple types)
|
||||
ctx.search.Parallel(requests: Request[]): Result[]
|
||||
```
|
||||
|
||||
### Options Types
|
||||
|
||||
```typescript
|
||||
interface WebOptions {
|
||||
limit?: number; // Max results (default: 10)
|
||||
sites?: string[]; // Restrict to sites
|
||||
timeRange?: string; // "day", "week", "month", "year"
|
||||
rerank?: RerankOptions;
|
||||
}
|
||||
|
||||
interface KBOptions {
|
||||
collections?: string[]; // Collection IDs
|
||||
threshold?: number; // Similarity threshold (0-1)
|
||||
limit?: number; // Max results
|
||||
graph?: boolean; // Enable graph association
|
||||
rerank?: RerankOptions;
|
||||
}
|
||||
|
||||
interface DBOptions {
|
||||
models?: string[]; // Model IDs (default: use assistant's db.models)
|
||||
wheres?: QueryWhere[]; // Pre-defined filters
|
||||
orders?: QueryOrder[]; // Sort orders
|
||||
select?: string[]; // Fields to return
|
||||
limit?: number; // Max results (default: 10)
|
||||
rerank?: RerankOptions;
|
||||
}
|
||||
|
||||
interface QueryWhere {
|
||||
field: string;
|
||||
op?: string; // "=", "like", ">", "<", "in", etc.
|
||||
value: any;
|
||||
}
|
||||
|
||||
interface QueryOrder {
|
||||
field: string;
|
||||
order?: string; // "asc" or "desc"
|
||||
}
|
||||
|
||||
interface RerankOptions {
|
||||
type?: string; // "score", "model", "agent", "mcp"
|
||||
model?: string; // Model ID (for type="model")
|
||||
agent?: string; // Agent ID (for type="agent")
|
||||
mcp?: string; // MCP server ID (for type="mcp")
|
||||
topK?: number; // Return top K
|
||||
}
|
||||
```
|
||||
|
||||
### Usage Examples
|
||||
|
||||
#### Example 1: Web Search
|
||||
|
||||
```typescript
|
||||
function Create(ctx, messages, options) {
|
||||
const query = messages[messages.length - 1].content;
|
||||
|
||||
const result = ctx.search.Web(query, {
|
||||
limit: 5,
|
||||
timeRange: "week",
|
||||
});
|
||||
|
||||
if (result.items.length > 0) {
|
||||
return {
|
||||
messages: [
|
||||
{
|
||||
role: "system",
|
||||
content: formatSearchContext(result),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
return { messages: [] };
|
||||
}
|
||||
```
|
||||
|
||||
#### Example 2: Knowledge Base Search with Graph
|
||||
|
||||
```typescript
|
||||
function Create(ctx, messages, options) {
|
||||
const query = messages[messages.length - 1].content;
|
||||
|
||||
const result = ctx.search.KB(query, {
|
||||
collections: ["docs", "faq"],
|
||||
threshold: 0.7,
|
||||
limit: 10,
|
||||
graph: true, // Enable graph association
|
||||
});
|
||||
|
||||
if (result.items.length > 0) {
|
||||
return {
|
||||
messages: [
|
||||
{
|
||||
role: "system",
|
||||
content: formatKBContext(result),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
return { messages: [] };
|
||||
}
|
||||
```
|
||||
|
||||
#### Example 3: Database Search
|
||||
|
||||
```typescript
|
||||
function Create(ctx, messages, options) {
|
||||
const query = messages[messages.length - 1].content;
|
||||
|
||||
// Search in assistant's models (uses db.models from assistant config)
|
||||
const result = ctx.search.DB(query, {
|
||||
models: ["product", "agents.mybot.order"], // Optional: override models
|
||||
wheres: [{ field: "status", value: "active" }], // Pre-filter
|
||||
limit: 20,
|
||||
});
|
||||
|
||||
if (result.items.length > 0) {
|
||||
return {
|
||||
messages: [
|
||||
{
|
||||
role: "system",
|
||||
content: formatDBContext(result),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
return { messages: [] };
|
||||
}
|
||||
```
|
||||
|
||||
#### Example 4: Parallel Web + KB + DB Search
|
||||
|
||||
```typescript
|
||||
function Create(ctx, messages, options) {
|
||||
const query = messages[messages.length - 1].content;
|
||||
|
||||
// Execute web, KB, and DB search in parallel
|
||||
const [webResult, kbResult, dbResult] = ctx.search.Parallel([
|
||||
{ type: "web", query: query, limit: 5 },
|
||||
{ type: "kb", query: query, collections: ["docs"], limit: 10 },
|
||||
{ type: "db", query: query, models: ["product"], limit: 10 },
|
||||
]);
|
||||
|
||||
// Merge results
|
||||
const context = mergeSearchResults(webResult, kbResult, dbResult);
|
||||
|
||||
return {
|
||||
messages: [
|
||||
{
|
||||
role: "system",
|
||||
content: context,
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
#### Example 5: Custom Citation Format
|
||||
|
||||
```typescript
|
||||
function Create(ctx, messages, options) {
|
||||
const query = messages[messages.length - 1].content;
|
||||
const result = ctx.search.Web(query, { limit: 5 });
|
||||
|
||||
// Build custom citation prompt
|
||||
const refs = result.items
|
||||
.map((item, i) => `[${i + 1}] ${item.title} - ${item.url}`)
|
||||
.join("\n");
|
||||
|
||||
return {
|
||||
messages: [
|
||||
{
|
||||
role: "system",
|
||||
content: `Use [N] to cite. References:\n${refs}`,
|
||||
},
|
||||
],
|
||||
// Override citation config
|
||||
citation: { autoInjectPrompt: false },
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Assistant Configuration
|
||||
|
||||
```yaml
|
||||
# assistants/my-assistant.yml
|
||||
assistant_id: my-assistant
|
||||
connector: openai
|
||||
|
||||
search:
|
||||
web_search: true
|
||||
knowledge: true
|
||||
database: true
|
||||
|
||||
web:
|
||||
provider: tavily # "tavily", "serper", "mcp:server-id"
|
||||
max_results: 5
|
||||
|
||||
kb:
|
||||
collections: [docs, faq]
|
||||
threshold: 0.7
|
||||
graph: true
|
||||
|
||||
db:
|
||||
models: [product, order] # Use assistant's db.models if not specified
|
||||
max_results: 20
|
||||
|
||||
rerank:
|
||||
type: score # "score", "model", "agent", "mcp"
|
||||
|
||||
citation:
|
||||
format: "#ref:{id}"
|
||||
auto_inject_prompt: true
|
||||
|
||||
# Knowledge base collections
|
||||
kb:
|
||||
collections: [docs, faq]
|
||||
|
||||
# Database models (also supports assistant-specific models in models/ directory)
|
||||
db:
|
||||
models: [product, order, customer]
|
||||
```
|
||||
|
||||
### Global Configuration
|
||||
|
||||
```yaml
|
||||
# config/search.yml
|
||||
search:
|
||||
web:
|
||||
provider: tavily
|
||||
api_key_env: TAVILY_API_KEY
|
||||
|
||||
rerank:
|
||||
type: score
|
||||
|
||||
citation:
|
||||
format: "#ref:{id}"
|
||||
auto_inject_prompt: true
|
||||
```
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Search Flow
|
||||
|
||||
## Execution Modes
|
||||
|
||||
### Stream() Execution with Search
|
||||
|
||||
```
|
||||
Stream(ctx, messages, options)
|
||||
│
|
||||
├── 1. Initialize
|
||||
│
|
||||
├── 2. Create Hook (optional)
|
||||
│ └── Can call ctx.search.* and return search results
|
||||
│
|
||||
├── 3. Auto Search Decision
|
||||
│ ├── IF Options.Search == false → SKIP
|
||||
│ ├── IF Create Hook returned search context → SKIP
|
||||
│ └── ELSE → Execute Auto Search
|
||||
│ ├── Read assistant's search config
|
||||
│ ├── Execute web/kb/db in parallel
|
||||
│ ├── Send search_start/search_result/search_complete to output
|
||||
│ ├── Rerank results
|
||||
│ ├── Generate citation IDs
|
||||
│ └── Inject search context + citation prompt to messages
|
||||
│
|
||||
├── 4. LLM Call (with search context if any)
|
||||
│
|
||||
├── 5. Next Hook (optional)
|
||||
│
|
||||
└── 6. Output (response may contain #ref:xxx citations)
|
||||
```
|
||||
|
||||
### Control Options
|
||||
|
||||
| Options.Search | Assistant Config | Behavior |
|
||||
| -------------- | ----------------- | ------------------------- |
|
||||
| `true` | any | Force enable auto search |
|
||||
| `false` | any | Force disable auto search |
|
||||
| `nil` | has search config | Enable auto search |
|
||||
| `nil` | no search config | Disable auto search |
|
||||
|
||||
**Go:**
|
||||
|
||||
```go
|
||||
// Force enable
|
||||
options := &context.Options{Search: boolPtr(true)}
|
||||
|
||||
// Force disable
|
||||
options := &context.Options{Search: boolPtr(false)}
|
||||
|
||||
// Follow assistant config (default)
|
||||
options := &context.Options{Search: nil}
|
||||
```
|
||||
|
||||
**API Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"messages": [...],
|
||||
"search": true
|
||||
}
|
||||
```
|
||||
|
||||
### Hook-Controlled Search
|
||||
|
||||
When you need custom search logic, handle it in Create Hook:
|
||||
|
||||
```typescript
|
||||
function Create(ctx, messages, options) {
|
||||
const query = messages[messages.length - 1].content;
|
||||
|
||||
// Custom logic: only search for certain queries
|
||||
if (needsSearch(query)) {
|
||||
const result = ctx.search.Web(query, { limit: 5 });
|
||||
return {
|
||||
messages: [{ role: "system", content: formatContext(result) }],
|
||||
// Returning messages signals: skip auto search
|
||||
};
|
||||
}
|
||||
|
||||
return { messages: [] };
|
||||
}
|
||||
```
|
||||
|
||||
## Search Flow
|
||||
|
||||
```
|
||||
Request → Trace Start → Query Process → Search → Rerank → Citations → Output → Return
|
||||
```
|
||||
|
||||
### Query Processing
|
||||
|
||||
| Type | Process |
|
||||
| ---- | ----------------------------------------------------- |
|
||||
| Web | Extract keywords → Build query |
|
||||
| KB | Get collection's embedding model → Generate embedding |
|
||||
| DB | Parse query → Build QueryDSL → Execute on models |
|
||||
|
||||
## Providers
|
||||
|
||||
### Web Search
|
||||
|
||||
| Provider | Type | Notes |
|
||||
| -------- | -------- | ------------------------------- |
|
||||
| Tavily | Built-in | Recommended for AI applications |
|
||||
| Serper | Built-in | Google search API |
|
||||
| MCP | External | Any MCP server with search tool |
|
||||
|
||||
### Knowledge Base
|
||||
|
||||
Integrates with Yao's GraphRAG system:
|
||||
|
||||
- Vector search with collection-specific embedding models
|
||||
- Graph-based association (optional)
|
||||
|
||||
### Database Search
|
||||
|
||||
Integrates with Yao's Model/QueryDSL system:
|
||||
|
||||
- Natural language → QueryDSL conversion (via LLM)
|
||||
- Model schema introspection for query building
|
||||
- Support for:
|
||||
- Global models (`models/*.mod.yao`)
|
||||
- Assistant-specific models (`assistants/{id}/models/*.mod.yao` → `agents.{id}.*`)
|
||||
- Permission-aware queries (respects `__yao_*` permission fields)
|
||||
|
||||
### Reranking
|
||||
|
||||
| Type | Notes |
|
||||
| ----- | ---------------------------------------- |
|
||||
| score | Simple score sorting (default) |
|
||||
| model | Cohere, BGE, Jina rerankers |
|
||||
| agent | Delegate to another assistant for rerank |
|
||||
| mcp | Call MCP server rerank tool |
|
||||
|
||||
## Error Handling
|
||||
|
||||
Search errors don't block the agent flow. Errors are returned in `Result.Error`:
|
||||
|
||||
```typescript
|
||||
const result = ctx.search.Web(query);
|
||||
if (result.error) {
|
||||
// Handle gracefully or fallback
|
||||
console.warn("Search failed:", result.error);
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration Priority
|
||||
|
||||
1. **Request-level**: `Options.Search` in Stream() call (highest)
|
||||
- `true`: Force enable auto search
|
||||
- `false`: Force disable auto search
|
||||
- `nil`: Follow assistant config
|
||||
2. **Hook-level**: Options in `ctx.search.*()` calls
|
||||
3. **Assistant-level**: `search` config in assistant.yml
|
||||
4. **Global-level**: `config/search.yml` defaults
|
||||
|
||||
## DB Search Details
|
||||
|
||||
### Query Processing Flow
|
||||
|
||||
```
|
||||
Natural Language Query
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ Get Model Schemas │ ← Introspect models from db.models config
|
||||
│ (fields, types, relations) │
|
||||
└─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ LLM: Generate QueryDSL │ ← Convert NL to Yao QueryDSL
|
||||
│ (select, wheres, orders) │
|
||||
└─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ Execute Query on Each Model │ ← model.Find() with QueryDSL
|
||||
└─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
Results
|
||||
```
|
||||
|
||||
### Model ID Formats
|
||||
|
||||
| Format | Example | Description |
|
||||
| ------ | -------------------- | --------------------------------------------------------------------- |
|
||||
| Global | `product` | Global model from `models/product.mod.yao` |
|
||||
| System | `__yao.user` | Yao system model |
|
||||
| Agent | `agents.mybot.order` | Assistant-specific model from `assistants/mybot/models/order.mod.yao` |
|
||||
|
||||
### QueryDSL Generation Prompt
|
||||
|
||||
The DB handler uses LLM to convert natural language to QueryDSL:
|
||||
|
||||
```
|
||||
Given the following model schemas:
|
||||
- product: { id, name, price, category, status, created_at }
|
||||
- order: { id, product_id, quantity, total, customer_id, status }
|
||||
|
||||
User query: "find all active products under $100 in electronics category"
|
||||
|
||||
Generate Yao QueryDSL:
|
||||
{
|
||||
"model": "product",
|
||||
"wheres": [
|
||||
{ "field": "status", "op": "=", "value": "active" },
|
||||
{ "field": "price", "op": "<", "value": 100 },
|
||||
{ "field": "category", "op": "=", "value": "electronics" }
|
||||
],
|
||||
"orders": [{ "field": "price", "order": "asc" }],
|
||||
"limit": 10
|
||||
}
|
||||
```
|
||||
|
||||
## Related Files
|
||||
|
||||
- `agent/context/jsapi.go` - JSAPI base implementation
|
||||
- `agent/context/types_llm.go` - Uses configuration (Search field)
|
||||
- `agent/assistant/types.go` - SearchOption definition
|
||||
- `agent/store/types/types.go` - KnowledgeBase, Database config
|
||||
- `agent/output/message/types.go` - Output message types
|
||||
- `agent/content/` - Content module (similar Handler + Registry pattern)
|
||||
- `model/model.go` - Yao Model loading (global, system, assistant models)
|
||||
|
||||
## See Also
|
||||
|
||||
- `agent/context/JSAPI.md` - Full JSAPI documentation
|
||||
- `agent/context/RESOURCE_MANAGEMENT.md` - Context lifecycle and resource management
|
||||
- `agent/output/README.md` - Output system documentation
|
||||
- `agent/store/CHAT_STORAGE_DESIGN.md` - Chat storage design
|
||||
Loading…
Add table
Reference in a new issue