JavaScript: Knowledge bases and agents
Add documents to a knowledge base and search them with citations, and talk to your project's agents from your app with @sovaria/sdk.
sovaria.knowledge puts documents in a knowledge base on your project's Postgres and returns passages with numbered citations; sovaria.agents talks to the project's agents, streaming the answer. Both act as the signed-in user, so each person only gets what they may read. Guides: Knowledge bases (RAG), Sovariq AI and agents in your app.
await sovaria.knowledge.addFile('support_docs', file)
const { results, citations } = await sovaria.knowledge.search('support_docs', 'refund window')
const reply = await sovaria.agents.run(agentId, { message: 'Can I return a gift card?', onEvent: (e) => render(e) })
await sovaria.agents.run(agentId, { message: 'And a damaged one?', threadId: reply.threadId })sovaria.knowledge
sovaria.knowledge.list
List.
sovaria.knowledge.list(): Promise<JsonObject>Returns
Promise<JsonObject>
- HTTP
GET KNOWLEDGE_PATH
sovaria.knowledge.create
Create.
sovaria.knowledge.create(
name: string,
options?: KnowledgeBaseOptions = {},
): Promise<JsonObject>Parameters
namestringrequiredoptionsKnowledgeBaseOptionsoptionaldefault{}
Returns
Promise<JsonObject>
- HTTP
POST KNOWLEDGE_PATH
sovaria.knowledge.addText
Add text.
sovaria.knowledge.addText(
name: string,
text: string,
options?: KnowledgeDocumentOptions & { format?: 'text' | 'markdown' | 'html' } = {},
): Promise<KnowledgeAddResult>Parameters
namestringrequiredtextstringrequiredoptionsKnowledgeDocumentOptions & { format?: 'text' | 'markdown' | 'html' }optionaldefault{}
Returns
Promise<KnowledgeAddResult>
- HTTP
POST {…}/{…}/documents
sovaria.knowledge.addUrl
Add url.
sovaria.knowledge.addUrl(
name: string,
url: string,
options?: KnowledgeDocumentOptions = {},
): Promise<KnowledgeAddResult>Parameters
namestringrequiredurlstringrequiredoptionsKnowledgeDocumentOptionsoptionaldefault{}
Returns
Promise<KnowledgeAddResult>
- HTTP
POST {…}/{…}/documents
sovaria.knowledge.addFile
A PDF, DOCX, HTML, Markdown, TXT, CSV or JSON file (up to 7 MB): a File/Blob, or bytes with filename.
sovaria.knowledge.addFile(
name: string,
file: Blob | Uint8Array | ArrayBuffer,
options?: KnowledgeDocumentOptions & { filename?: string } = {},
): Promise<KnowledgeAddResult>Parameters
namestringrequired- Knowledge base name.
fileBlob | Uint8Array | ArrayBufferrequired- A
File/Blob, or bytes withoptions.filename. optionsKnowledgeDocumentOptions & { filename?: string }optionaldefault{}filename,documentId(re-using it replaces the document),title,metadata.
Returns
Promise<KnowledgeAddResult>
- HTTP
POST {…}/{…}/documents
sovaria.knowledge.documents
Documents.
sovaria.knowledge.documents(
name: string,
options?: { limit?: number; offset?: number } = {},
): Promise<JsonObject>Parameters
namestringrequiredoptions{ limit?: number; offset?: number }optionaldefault{}
Returns
Promise<JsonObject>
- HTTP
GET {…}/{…}/documents
sovaria.knowledge.deleteDocument
Delete document.
sovaria.knowledge.deleteDocument(
name: string,
documentId: string,
): Promise<JsonObject>Parameters
namestringrequireddocumentIdstringrequired
Returns
Promise<JsonObject>
- HTTP
DELETE {…}/{…}/documents/{…}
sovaria.knowledge.search
Search.
sovaria.knowledge.search(
name: string,
query: string,
options?: { k?: number; mode?: 'vector' | 'keyword' | 'hybrid'; metadataFilter?: JsonObject } = {},
): Promise<KnowledgeSearchResult>Parameters
namestringrequired- Knowledge base name.
querystringrequired- The question.
options{ k?: number; mode?: 'vector' | 'keyword' | 'hybrid'; metadataFilter?: JsonObject }optionaldefault{}k(default 5),mode(hybrid,vector,keyword),metadataFilter.
Returns
Promise<KnowledgeSearchResult>
- HTTP
POST {…}/{…}/search
sovaria.agents
sovaria.agents.run
Send a message (a new thread, or threadId to continue one) and wait for the answer; onEvent streams it.
sovaria.agents.run(
agentId: string,
input: AgentRunInput,
): Promise<AgentRunResult>Parameters
agentIdstringrequired- The agent's id.
inputAgentRunInputrequiredmessage,threadIdto continue a conversation,onEventfor streamed events,signalto stop.
Returns
Promise<AgentRunResult> — { threadId, text, status, usage, events }.
sovaria.agents.stream
The same as run, as an async iterator of events (conversation, text_delta, text, tool_call, …, done).
sovaria.agents.stream(
agentId: string,
input: AgentRunInput,
): AsyncIterable<AgentEvent>Parameters
agentIdstringrequired- The agent's id.
inputAgentRunInputrequired- As for
run.
Returns
AsyncIterable<AgentEvent> — An async iterator of events: conversation, text_delta, tool_call, tool_result, text, done.
sovaria.agents.threads
The signed-in user's threads with this agent, newest first.
sovaria.agents.threads(agentId: string): Promise<JsonObject[]>Parameters
agentIdstringrequired
Returns
Promise<JsonObject[]>
- HTTP
GET /api/v1/sovariq/agents/{…}/runs
sovaria.agents.thread
One thread with its events (messages, tool calls, answers).
sovaria.agents.thread(threadId: string): Promise<JsonObject>Parameters
threadIdstringrequired
Returns
Promise<JsonObject>
- HTTP
GET /api/v1/sovariq/conversations/{…}
sovaria.agents.cancel
Stop the agent's current run in this thread.
sovaria.agents.cancel(threadId: string): Promise<JsonObject>Parameters
threadIdstringrequired
Returns
Promise<JsonObject>
- HTTP
POST /api/v1/sovariq/conversations/{…}/cancel