Give Knowledge to Your Agent with ODC’s Built-in Semantic Search

Grounding is one of the most important concepts in building reliable AI agents. When an agent is grounded, it has access to specific, real data from your systems, giving it real context of your business. In OutSystems Developer Cloud’s (ODC) Agent Workbench, the Grounding Data step is when you run your queries, fetch the relevant records, and inject the results into the LLM’s context.

This approach works well for small, predictable datasets. But consider an AI assistant that supports users navigating the FAQs of an insurance claims platform, a knowledge base with entries spread across multiple claim types and categories. As that knowledge base grows, the Grounding approach starts to show its limits. What happens when it reaches hundreds of documents?

The Challenge with Traditional Approaches

Passing an entire knowledge base as context does not scale. If we fetch everything upfront, we risk hitting the LLM’s context window limit. Even if we don’t hit it, every token sent costs money and adds latency. Feeding irrelevant documents into the context also tends to degrade response quality, since the model has to sift through noise to find the signal.

The natural next step is to give the agent a search tool so it can query the database on demand, fetching only what it needs. But this runs into its own wall: LIKE filters require exact word matches. The agent has no way of knowing which exact keywords exist in the database. And if a user asks "how long does it take to process my claim?", a LIKE filter will never match an entry titled "Claim Processing Deadlines". The words are different, even though the intent is identical.

This is the core of the problem: the agent needs to search by meaning, not by words.

That is exactly what Semantic Search enables. But building it from scratch involves significant work. You need a full ingestion pipeline: extract your data, split it into chunks, generate vector embeddings using an embedding model, and store them in a vector database. On the retrieval side, you then need to embed the user’s query at runtime, run a similarity search against that database, and surface the most relevant results. Each step requires infrastructure decisions, specialist knowledge, and ongoing maintenance.

OutSystems looked at this problem and did what it usually does: abstracted the complexity. ODC’s built-in Semantic Search handles the entire pipeline for you. Embedding generation, chunking, indexing, and similarity retrieval are all managed by the platform. No external services, no custom pipelines, no specialist infrastructure required. You configure it in ODC Studio and call it through a native logic node. That is what this article walks through.

Semantic Search returns the chunks with the most similar meaning to your sentence.

How to Implement It

Part 1: Preparing the Data Layer with Semantic Indexing

The first step happens inside ODC Studio, at the data level. ODC lets you make text attributes of any entity “searchable” by right-clicking it in the Data tab and selecting “Select searchable attributes…”. At that point, you choose which attributes to index and how to chunk the content.

The FAQEntry entity in the FAQ app has five attributes: Id, LibraryId, Category, Question, and Answer. Only the Answer field is indexed for semantic search, and the reason is worth explaining.

In ODC’s implementation, each indexed field is treated as an independent document and chunked separately. If you index both Question and Answer, the search returns a mix of result chunks: some containing answer content, and some containing only the question text. A chunk with just the question title has no useful content for the agent to respond with, so it adds noise without value. Indexing only the Answer field ensures that every chunk returned contains actionable knowledge.

Chunking is the process of splitting large bodies of text into smaller segments. Each chunk is indexed independently and treated as an individual unit during retrieval. The search engine then scores and ranks chunks, not full documents. ODC offers five methods:

• Smart: The default. Analyzes your content structure and adapts chunk boundaries to preserve semantic cohesion. Best for most use cases, especially structured content like Q&A pairs.
• Fixed-size: Splits text into equal-length character blocks with configurable overlap between chunks. Predictable and consistent, but can cut sentences mid-way. Best for dense prose without clear structure.
• Sentence-based: Splits at sentence boundaries, preserving grammatical integrity. Works well for formal, well-structured text.
• Recursive: Uses a hierarchy of delimiters (paragraphs, then sentences) to build the largest possible chunks within the size limit. More context-aware than Fixed-size.
• None: Disables chunking. The entire attribute content is treated as a single chunk. Best for very short texts or when you want to control chunking manually.

For this use case, Smart Chunking is the right choice. FAQ entries have a natural Q&A structure, and Smart Chunking preserves that without requiring manual configuration.

Once configured, save and publish. ODC starts the indexing process asynchronously, generating vector embeddings for each chunk.

Semantic Search node Example. Filter by Library, and optionally by Category and FAQEntryId

Part 2: Building the Search Tool

With the data indexed, the next step is wiring the search capability into the agent. This involves two actions across two apps, and the distinction matters.

In the FAQ app, create a Service Action that wraps the native Search Semantic logic node. The output of the semantic search is a list chunks ordered by relevance, each with a similarity score, the chunk content and the associated record that sourced the chunk.

In the Agent app, consume that Service Action and wrap it inside a Server Action named SearchFAQ. This extra step is required because Agent Workbench tools can only be Server Actions. Service Actions cannot be registered as tools directly.

The SearchFAQ Server Action exposes the parameters the agent needs to control its search:

• Query: the user’s question in natural language
• Category: an optional filter to narrow results to a answer category
• DocumentId: the identifier of a specific FAQ document; sending 0 means "search across all documents"
• StartIndex: the index of the first chunk to return, used for pagination
• MaxRecords: limits how many chunks come back, keeping context manageable

The DocumentId parameter in particular is what makes the two-stage search strategy possible. More on that in the next part.

In this app, the InFAQLibraryId is hardcoded for the Library we want our agent to access.

Part 3: Orchestrating the Agent in Agent Workbench

This is where the pieces come together. In the Agent Workbench, connect the SearchFAQ Server Action as a tool and then focus on what matters most in agentic systems: the system prompt.

Before defining the search strategy, it is worth revisiting the role of Grounding in an agentic flow. Earlier, we described Grounding as the step where context is loaded before the agent starts. That model works well for deterministic workflows where you know exactly what context the agent will need upfront. In a more agentic workflow, however, the agent itself decides what information it needs and when. Knowledge retrieval becomes a tool it calls on demand rather than a step you run before it, and out tool definition should allow our agent to explore the knowledge base. Grounding still has a role, but a lighter one: instead of loading documents, we use it to inject a small, structured set of metadata the agent needs to use the search tool correctly, such as in this case, available categories and document ids.

With that in mind, here is the three-part strategy to instruct the agent:

1. Start broad. Always begin with DocumentId: 0 for a full semantic search across the entire knowledge base. This acts as a discovery step: the agent finds which documents are most relevant to the user's question.
2. Go specific when needed. If the first search surfaces a highly relevant document but the user needs more depth, the agent calls the tool again, this time filtering by that specific DocumentId to surface more granular content from that document.
3. Provide the available values. The agent needs to know which Category and DocumentId values are valid before it can use them. Use the Grounding Data step to fetch the list of available categories and documents from the FAQ app and inject them into the system prompt. This prevents the agent from guessing or hallucinating values.

With this approach, the agent directs its own search. It decides when to go broad and when to drill down, based on what it finds. This is the real power of combining semantic retrieval with agent reasoning.

One practical note worth highlighting: the quality of this strategy depends heavily on the model you use. Newer, more capable models are significantly better at following multi-step tool-calling instructions and adhering to the nuances in the system prompt. If you find the agent ignoring your search strategy or calling tools inconsistently, the model is often the first thing to evaluate.

With the data indexed, the tool built, and the agent instructed, the agent is ready. From this point, you can expose it as a service and integrate it into any ODC application, giving your users a conversational interface backed by semantic retrieval.

Conclusion

ODC’s Semantic Search is a very useful addition, for more than just agentic applications. The ability to search by meaning, natively and without external vector databases or custom embedding pipelines, removes a barrier that used to require significant infrastructure before even writing the first line of business logic. For agent-based applications, where the quality of retrieval directly determines the quality of every response, this matters a lot.

That said, Semantic Search is only one piece of the retrieval puzzle. Getting good results also requires good indexing (choosing the right chunking strategy for your content structure) and, when your knowledge lives in unstructured documents like PDFs, quality text extraction before indexing. Each of those decisions has a direct impact on the quality of your results. Those are topics for future articles.

The implementation in three steps:

1. Enable Semantic Search on the target entity in ODC Studio, using Smart Chunking.
2. Build a SearchFAQ Tool using the Search Semantic node, exposing parameters that give the agent control over scope and depth.
3. Instruct the agent to direct its own searches: broad first, specific when warranted.

If you are building agents in ODC and have not yet explored Semantic Search, this is a good moment to try it. The setup is very simple, and the quality difference in retrieval is immediately noticeable.