knowledge-setup

Adding Knowledge to an Agent

Prerequisites

• An embedding model must be configured in the project before creating knowledge stores. Use setup_llm to create one first if the target project does not already have one (e.g., setup_llm { projectId, provider: "openAI", modelType: "<embedding model type>", apiKey }). To check: list_resources { resourceType: "llm_model", projectId } and inspect modelType. Use provider docs or an existing same-project model to identify the correct embedding-capable model type for the store index.
• Configure the project's Knowledge AI Settings before creating the store in normal AI-agent knowledge flows. Use manage_settings { operation: "set_knowledge_ai", projectId, knowledgeSearchModelId: "<llm referenceId>" }. If you use the Azure content parser, also set contentParser: "azure" and azureDIConnectionId.

Important Distinction

• The embedding model is for the knowledge store index itself.
• knowledgeSearchModelId is a separate project setting for Knowledge Search and must reference an llm_model from the same project.
• For normal AI-agent knowledge-store setups, answerExtractionModelId is usually not needed.
• The model you pick for the AI Agent itself is a separate decision. The agent response model should not be reused for knowledgeSearchModelId just because it is already available.
• The accepted model type for knowledgeSearchModelId is instance-dependent. Start with existing same-project candidates and rely on the API response.
• Model names shown in examples are not a whitelist for either role.

Steps

1. list_resources { resourceType: "llm_model", projectId }
   • For Knowledge Search, prefer list_resources { resourceType: "llm_model", projectId, useCase: "knowledgeSearch" } so the candidates match the Settings UI dropdown
   • Refresh this after any package import
   • Start with the source project's exact Knowledge Search model when reusing an existing setup
   • Import the full required source-project model set before the first manage_settings { operation: "set_knowledge_ai", ... } attempt
   • If multiple required models share one connection, import that connection once alongside all of those models
2. manage_settings { operation: "set_knowledge_ai", projectId, knowledgeSearchModelId, contentParser }
   • Do this before manage_knowledge { operation: "create_store", ... } in normal AI-agent knowledge flows
3. manage_knowledge { operation: "create_store", projectId, name }
4. manage_knowledge { operation: "create_source", knowledgeStoreId, type, ... }
   • type: "url" — scrape a web page. Provide url.
   • type: "manual" — store text directly. Provide text.
   • type: "file" — upload a local document. Provide filePath (absolute path, e.g. "/Users/me/docs/report.pdf").
   • IMPORTANT: URL and file ingestion is async. Content is NOT searchable immediately.
   • Wait 10-60 seconds before searching.
5. manage_knowledge { operation: "list_chunks", knowledgeStoreId }
   • Verify content was ingested correctly (optional sourceId — defaults to the first source — and filter to match chunk text; list_sources shows all sources in the store)
   • If no results right after create_source, wait and retry
6. Attach to agent as a TOOL (default approach):
   • During agent creation — create_ai_agent { projectId, name, knowledgeStoreReferenceId: storeReferenceId } This automatically creates a knowledge search tool on the agent's Job Node.
   • After agent creation — create_tool { aiAgentId, toolType: "knowledge", name: "Search KB", config: { knowledgeStoreId: storeReferenceId, toolId: "search_kb", description: "Search the knowledge base" } } This creates a dedicated search tool the agent can invoke to query the knowledge store.
   • IMPORTANT: Always use the tool-based approach unless the user explicitly asks to attach knowledge to the agent persona.