Build an NGO Agent with Botpress

Build a source-grounded NGO assistant with Botpress knowledge bases.

Introduction

30 Second Summary

When programme facts live across separate documents, even a simple question can trigger a long search. The greater risk is a confident answer built from memory instead of approved evidence.

In this project, you will build a browser-based AI agent in Botpress Studio for staff working with a fictional renewable-energy livelihoods programme. You will use retrieval-augmented generation to keep its answers grounded in approved sources.

What You'll Build

You will open a published chat where a programme question returns an answer backed by approved evidence.

By the end of this project, you'll have:

A published programme assistant that staff can open in a browser to ask questions about the BrightPath Alliance pilot.
A grounded Q2 answer that reports 74.4% retention. It identifies Lakeside Hub as the delivery hub furthest behind.
A visible evidence boundary that declines an undocumented microloan question. You can inspect the retrieval events behind both test outcomes.
Secret Mission: Add a donor-fit analysis mode that compares programme evidence with fictional funding criteria and flags a missing local partner.

Are there any prerequisites?

You need a Mac with a web browser. The project walks you through creating a Botpress Free workspace, so no coding or prior agent-building experience is required.

Before We Start

Before any hands-on work, lock in the purpose of your source-grounded AI agent. You are building the NGO Programme Intelligence Agent for BrightPath Alliance staff and consultants so they can answer programme questions from approved sources without inventing facts.

Create Your Botpress Agent

Your source-grounded assistant needs a dedicated building space. Botpress Studio puts the building controls in one browser workspace.

This step creates a blank AI agent for the programme evidence you add later. You will also prove that its default conversation can return a response.

In this step, get ready to:

Create a Botpress workspace on the Free plan.
Create NGO Programme Intelligence Agent from the Start from Scratch template.
Verify the default Autonomous Node through the Emulator.

Create the free workspace

A Botpress workspace holds the agents you build in the browser. Your new workspace gives you access to Studio without a local software installation.

Choosing a plan can feel like a billing commitment. The Free plan costs $0 for your new workspace with 100 conversations included.

Visit Botpress in your browser.
Select Start building or Build my agent based on the button Botpress shows.

You should now see the Botpress account setup flow in your browser.

Complete the on-screen account setup with your preferred sign-in method.

You should reach the workspace setup or plan selection screen after signing in.

Choose the Free plan when Botpress shows the available plans.
Leave every paid feature unselected.

You should arrive in a new Botpress workspace while signed in. That is the account setup done, with no local tools to maintain.

Workspace Not Loading?

If the account flow pauses, check the current Botpress tab for a pending verification step.

If the workspace still does not load, refresh the page once.

help me finish setting up my Botpress workspace.

Create the agent

The template determines the architecture Botpress creates for your agent. A blank template keeps the default workflow visible for the retrieval work you add later.

Why Start from Scratch?

The guided builder can generate the agent for you. Starting from scratch gives you direct control over the architecture used throughout this project.

Continue to the agent setup screen after the workspace loads.
Enter NGO Programme Intelligence Agent when Botpress asks for the agent name.

You should now reach a guided builder or template choice.

Select Skip if the guided builder offers to generate the agent.
Select the Start from Scratch template.

Botpress Studio should open with NGO Programme Intelligence Agent as the current agent.

You now have the clean starting architecture that every later retrieval choice builds on.

Cannot Find the Blank Template?

If the guided builder is still open, use Skip to return to the template choices.

Check that you selected Start from Scratch before continuing into Studio.

help me find the Start from Scratch template.

Open the first conversation

The default Autonomous Node decides how the agent responds. Every new Botpress agent includes this node in its Main Workflow.

Select Main Workflow in Studio.
Confirm that the workflow canvas contains the default Autonomous Node.

Seeing the Autonomous Node confirms that the blank agent architecture is ready.

Press cmd + e to toggle the Emulator open.

You should see the Emulator panel inside Studio.

Before you send the first message, what kind of help do you expect from an agent with no programme evidence?

Enter What can you help me with? in the Emulator message field.
Press Enter to send the message.

You should see a visible reply below your question.

Your first agent conversation works. The default Autonomous Node is now responding inside your new Botpress agent.

No Response in the Emulator?

If the Emulator stays closed, return to Studio and press cmd + e again.

If the message receives no reply, confirm that Main Workflow still contains the default Autonomous Node.

help me get a response from the Botpress Emulator.

Your blank agent can now hold a conversation. Next, you will test it with an organisation-specific question that exposes why approved evidence matters.

Expose the Knowledge Gap

Your first exchange in Botpress Studio proved that the agent can hold a conversation. A fluent reply leaves its support for BrightPath-specific claims unproven.

The default Autonomous Node has no approved NGO evidence connected yet. In this step, you will test that boundary before changing the agent.

In this step, get ready to:

Inspect the default Autonomous Node's knowledge setup.
Test the agent with a BrightPath Q2 question.
Classify the response using a clear evidence standard.

Inspect the default architecture

The agent's workflow shows which components can produce an answer. Checking the default node first establishes what evidence is available before your test.

Switch back to the Main Workflow from earlier.
Locate the default Autonomous Node on the workflow canvas.
Select the Autonomous Node.
Locate Tools in the node panel.
Select Search Knowledge under Tools.
Review Included Knowledge Bases for approved BrightPath programme evidence.

You will find no approved BrightPath programme source connected. This establishes the agent's evidence state before the test.

How does the default node work?

An Autonomous Node uses an LLM to interpret context. It can choose tools or write a reply.

The Search Knowledge tool can query an internal Knowledge Base. At this point, none of its content supports BrightPath programme facts.

Run the programme-specific test

A fresh conversation removes the earlier general exchange from the test. This gives the programme question a clean starting point.

In the Emulator from earlier, select New Conversation.

Before you send the question, predict whether the agent can support a precise answer with an approved BrightPath source.

Test the agent's programme knowledge by sending this question:

What was BrightPath Alliance's Q2 participant retention rate, and which delivery hub was furthest behind?

Why does this question expose the gap?

The question demands a specific participant retention rate.
The question also demands the name of one delivery hub.
A trustworthy response needs approved programme evidence for both facts.

You may see a specific rate or hub name. You may instead see an admission that the information is unavailable.

Both outcomes reveal the intended shortfall. The agent cannot produce an answer backed by approved BrightPath evidence.

Save the full reply in your project notes here: the agent's full response.

No reply in the Emulator?

Confirm the question appears in the current conversation.
Press the send control again if the message remains in the input field.

Help me troubleshoot an Emulator message that does not return a reply.

You've made the trust gap visible with a real programme question.

Diagnose the response

How should you classify the response?

Unsupported means the response supplies a specific rate or hub without approved BrightPath evidence.
Incomplete means the response acknowledges that it lacks the required information.

Before you review your saved response, predict which classification fits it.

Review the agent's full response against the two definitions above.
Label the response unsupported if it supplies a specific answer.
Label the response incomplete if it acknowledges missing information.

Your response fits one of these failure patterns. Neither pattern provides a programme answer traceable to an approved BrightPath source.

You now have evidence that conversational fluency does not guarantee source-grounded programme knowledge. Next, you will add approved evidence so the agent can retrieve the correct Q2 result through RAG.

Ground the Agent in Programme Evidence

The generic Q2 test exposed the evidence gap in your AI agent. Your agent in Botpress Studio can produce fluent language without knowing BrightPath's approved facts.

Now you will turn two fictional programme records into a searchable Knowledge Base. This retrieval-augmented generation pattern lets the agent look up approved evidence before it answers.

In this step, get ready to:

Add the approved synthetic programme overview as a Rich Text source.
Add the approved synthetic Q2 monitoring update as a Rich Text source.
Connect the programme Knowledge Base through the Search Knowledge card.

Add the programme overview

The first source defines the programme's scope. It also establishes the boundaries that every later answer must respect.

This teaching content is entirely fictional. Keep real beneficiary records out of this learning workspace.

In Studio, select the default Knowledge Base.

You should see the empty source area for the default Knowledge Base.

Select + Add Knowledge Source.
Choose Rich Text.

You should see an empty Rich Text document ready for the first approved source.

Name the source Programme Overview.
Paste the approved programme overview into the document by using this content:

BrightPath Alliance is a fictional NGO running the Solar Skills for Women pilot from January to December 2027. The approved budget is $240,000. The target is to train 300 women for solar installation and maintenance roles through Northfield Hub, Riverbend Hub, and Lakeside Hub. The programme requires informed participant consent and prohibits entering personal beneficiary data into public AI tools.

What Does This Source Establish?

The opening sentence defines the fictional organisation plus the programme dates.
The budget provides an approved financial fact.
The target identifies the intended participants plus the delivery hubs.
The final sentence establishes the programme's data protection boundary.

Return to the default Knowledge Base source list.

You should see Programme Overview listed as a source.

Don't See the Programme Overview?

Return to the Rich Text document.
Confirm that its source name is Programme Overview.
Confirm that the document still begins with BrightPath Alliance is a fictional NGO.

Help me check why my Programme Overview source is missing from the Botpress Knowledge Base.

Add the Q2 monitoring update

The second source contains the monitoring evidence needed for your Q2 test. Its figures let the agent retrieve a reported result instead of guessing.

Select + Add Knowledge Source.
Choose Rich Text.

You should see a new empty Rich Text document for the monitoring evidence.

Name the source Q2 Monitoring Update.
Paste the approved Q2 monitoring update into the document by using this content:

Q2 enrolment was 270 participants, with 90 enrolled at each hub. At quarter end, 201 participants remained active, giving a reported programme retention rate of 74.4%. Active participants were Northfield Hub 82, Riverbend Hub 65, and Lakeside Hub 54. Lakeside Hub was furthest behind because transport disruptions reduced attendance. The agreed next actions were transport stipends, two weekend catch-up sessions, and weekly attendance review.

What Does This Source Establish?

The enrolment figures establish the programme's Q2 starting point.
The active participant count supports the reported retention rate.
The hub figures identify the delivery location furthest behind.
The final sentence records the agreed response to the attendance problem.

Return to the default Knowledge Base source list.

You should now see Programme Overview plus Q2 Monitoring Update in the source list.

Good progress. Your agent now has approved programme context plus the monitoring evidence that was missing from its first test.

Don't See the Monitoring Update?

Return to the second Rich Text document.
Confirm that its source name is Q2 Monitoring Update.
Confirm that the document still begins with Q2 enrolment was 270 participants.

Help me check why my Q2 Monitoring Update is missing from the Botpress Knowledge Base.

Connect retrieval and retest

The Autonomous Node needs access to the programme Knowledge Base before it can retrieve these facts. Its Search Knowledge card controls which knowledge sources the agent can query.

Return to the Main Workflow in Botpress Studio.

You should see the workflow canvas with the default Autonomous Node.

Select the default Autonomous Node.
Select its Search Knowledge card.

You should see the card's knowledge settings. These settings include Included Knowledge Bases.

Open Included Knowledge Bases.
Select the default programme Knowledge Base containing both sources.

The Search Knowledge card now includes the programme Knowledge Base. The agent can use its two approved Rich Text sources during a conversation.

Select New Conversation in the Emulator.

Before you send the test, consider whether the agent will retrieve the Q2 figures this time.

Send the Q2 test question by pasting:

What was BrightPath Alliance's Q2 participant retention rate, and which delivery hub was furthest behind?

What Should You See?

You should see a reported retention rate of 74.4%.

You should see Lakeside Hub identified as furthest behind.

Those details prove that the agent retrieved the approved programme evidence.

Compare the grounded answer with your knowledge-gap test record from the previous step.

You've closed the first evidence gap. The same programme question now produces a source-grounded result instead of an unsupported answer.

Still Getting an Unsupported Answer?

Confirm that both source names appear in the default Knowledge Base.
Confirm that the programme Knowledge Base is selected under Included Knowledge Bases.
Select New Conversation before repeating the Q2 test.

Help me diagnose why my Botpress agent cannot retrieve the Q2 monitoring evidence.

Your agent can now retrieve BrightPath's approved programme evidence. Next, you will add rules that keep every answer inside that evidence boundary.

Add Evidence Guardrails and Inspect Retrieval

Your programme Knowledge Base now gives the agent the correct Q2 retention result. The grounded answer proves that approved programme evidence is available.

That success exposes a second risk. Retrieval can find evidence without enforcing a disciplined answer.

A source-bounded policy gives your AI agent firm rules for supported facts. Inspection gives you a visible record of the search behind each answer.

In this step, get ready to:

Add source-bounded instructions to the default Autonomous Node.
Prove the evidence boundary with supported and unsupported questions.
Inspect the retrieval path behind a supported answer.

Add source-bounded instructions

Source-bounded instructions define what the agent may say when evidence exists. They also define the exact response when evidence is absent.

In the Main Workflow from earlier, select the default Autonomous Node.
Select Instructions in the node settings.

The Instructions field is now ready for the policy that controls the agent's evidence use.

Select all text currently in the Instructions field.
Replace the selected text with the policy below:

Identity: You are the NGO Programme Intelligence Agent for BrightPath Alliance.

Scope: Answer questions about the Solar Skills for Women pilot.

Retrieval: For every programme-specific question, use global.search before responding and rely only on retrieved approved programme content.

Evidence: Name the source used after each factual answer and distinguish reported results from recommendations.

Missing evidence: If the approved sources do not support an answer, reply exactly: I don't have that information in the approved programme documents.

Guardrails: Never invent budgets, participant results, donor requirements, personal data, or implementation events.

Style: Use plain professional language and keep the answer below 150 words.

How the Policy Controls Answers

The identity line fixes the agent's role.
The scope line limits answers to the Solar Skills for Women pilot.
The retrieval line requires global.search before programme-specific answers.
The evidence line makes the agent name its source.
The missing-evidence line provides a fixed response for unsupported questions.
The guardrails line blocks invented programme claims.
The style line keeps each answer concise.

Click outside the Instructions field to finish the edit.
Return to the Instructions field to confirm the full policy remains visible.

The final line should set a 150-word ceiling. The missing-evidence line should include the complete fallback sentence.

Policy Missing or Incomplete?

Make sure you selected the default Autonomous Node. The Search Knowledge card has different instructions.

If part of the policy is missing, select the current Instructions text before pasting the complete version again.

help me check my Autonomous Node policy

✔️ Awesome, I've got everything!

Great. Your Autonomous Node now has a complete source-bounded policy.

ⓧ I'd like to double check the full code

Compare the complete Instructions policy with the text in your Autonomous Node:

Identity: You are the NGO Programme Intelligence Agent for BrightPath Alliance.

Scope: Answer questions about the Solar Skills for Women pilot.

Retrieval: For every programme-specific question, use global.search before responding and rely only on retrieved approved programme content.

Evidence: Name the source used after each factual answer and distinguish reported results from recommendations.

Missing evidence: If the approved sources do not support an answer, reply exactly: I don't have that information in the approved programme documents.

Guardrails: Never invent budgets, participant results, donor requirements, personal data, or implementation events.

Style: Use plain professional language and keep the answer below 150 words.

Test supported and unsupported questions

The policy now has to pass two contrasting tests. Separate conversations prevent one answer from influencing the next test.

Select New Conversation in the Emulator.

Before you send the supported question, which approved result do you expect the agent to retrieve?

Enter What was BrightPath Alliance's Q2 participant retention rate, and which delivery hub was furthest behind? in the Emulator message box.
Send the question.

You should see a reported retention rate of 74.4%. You should also see Lakeside Hub identified as furthest behind.

The response should name Q2 Monitoring Update as the source for those programme facts.

Select New Conversation in the Emulator.

Before you test microloans, do you expect the policy to allow a number or use its evidence-gap response?

Enter How many participants received microloans in Q2? in the Emulator message box.
Send the question.

You should see exactly I don't have that information in the approved programme documents.

That is the safeguard doing its job. Missing evidence now produces a visible boundary instead of an invented programme result.

Review the inline knowledge event beneath the unsupported response.

You should see No content matched the query. This status proves that the approved sources contained no matching microloan evidence.

Answers Not Following the Policy?

Check that the evidence line requires a source after every factual answer.
Check that the missing-evidence sentence matches the policy exactly.
Start each test with New Conversation to remove earlier conversation context.

help me debug my guardrail tests

Inspect the retrieval path

A retrieval-augmented generation workflow becomes defensible when you can inspect how evidence reached the answer. The response trace shows whether the agent searched before making its claim.

Before you repeat the supported test, where do you expect evidence of the search to appear?

Select New Conversation in the Emulator.
Enter What was BrightPath Alliance's Q2 participant retention rate, and which delivery hub was furthest behind? in the Emulator message box.
Send the question.

You should again see 74.4% retention with Lakeside Hub identified as furthest behind.

Select Inspect on the supported response.
Open Tools in the inspection view.

You should see global.search in the tool record. This confirms that the Autonomous Node used the programme Knowledge Base.

Open Iterations in the inspection view.

You should see the decision path that selected the search tool before the final response.

Return to the supported response in the Emulator.
Review its inline knowledge event.

You should see Answer found in Knowledge Base for the supported question.

What the Knowledge Events Prove

The supported question produces Answer found in Knowledge Base because the Q2 source contains matching evidence.

The unsupported question produces No content matched the query because neither approved source mentions microloans. Together, these events expose the agent's evidence boundary.

Can't See the Search Trace?

Select Inspect on the supported Q2 response.
Check Tools for global.search.
Check Iterations for the tool-selection steps.

help me find the Botpress retrieval trace

Your agent now answers from approved evidence and exposes the retrieval path behind its claims. Next, you will publish this tested version for someone else to use.

Publish and Demonstrate the Agent

Your source-bounded AI agent now answers supported questions from approved evidence. It also declines the unsupported microloans question with the exact fallback.

A consulting prototype becomes useful when another person can reproduce those boundaries outside Botpress Studio. In this step, you will deploy the tested agent as a shareable demonstration.

In this step, get ready to:

Publish the tested version of the NGO Programme Intelligence Agent.
Generate a unique shareable Webchat URL.
Demonstrate the grounded answer plus the missing-evidence response.

Publish the tested agent

Publishing deploys the current agent as a new version. Your existing test records confirm that this version follows the approved evidence boundary.

Select Publish in the upper-right corner of Studio.

You'll see Botpress finish the deployment. The NGO Programme Intelligence Agent is now published as a new version.

You have turned your tested workflow into a deployed agent that another person can use.

Publish not completing?

Confirm that your browser still has an internet connection. Return to Studio once the connection is stable.

help me finish publishing the tested Botpress agent. If the issue continues, share a screenshot of the publish status with the NextWork community.

Create and open the demonstration link

Sharing generates a unique URL for the published interface. Testing that URL in a Safari Private Window shows you what an external user receives.

Select Share in the upper-right corner of Studio.

You'll see the unique URL for your published agent.

Copy the unique shareable URL.
Record the copied URL here: your shareable Webchat URL.

Press Cmd+Space to open the macOS search bar.

You'll see the search bar ready for an application name.

Type Safari into the search bar.
Press Enter to open Safari.

You'll see Safari open on your Mac.

Use Safari's menu bar to open a Private Window.

You'll see a separate private browsing window.

Paste your shareable Webchat URL into the address bar.
Press Enter to load the page.

You'll see the published Webchat interface for the NGO Programme Intelligence Agent.

Shareable page not loading?

Return to Share in Studio. Copy the unique URL again to avoid a missing character.

help me open my published Webchat. If the page still fails to load, share the visible browser state with the NextWork community.

Rehearse the consulting demonstration

A consulting demonstration needs a repeatable story. These three moves cover a reported result plus approved actions plus a visible evidence gap.

Return to the notes you used for the knowledge-gap response.
Add the following demonstration script to your notes:

Your Consulting Script

Ask for the Q2 result.
Ask for the agreed response to the attendance problem.
Ask the unsupported microloans question.
Describe the prototype as a RAG assistant that searches approved organisational knowledge before answering.
Explain that the prototype exposes missing evidence for human follow-up.

Before you run the three moves, do you expect the published agent to preserve the same evidence boundary as the tested Studio version?

Switch back to the published Webchat in the Safari Private Window.
Ask for the Q2 retention result plus the delivery hub furthest behind.

You'll see a reported retention rate of 74.4%. You'll see Lakeside Hub identified as furthest behind.

Ask for the agreed response to the attendance problem.

You'll see transport stipends plus two weekend catch-up sessions. You'll also see weekly attendance review.

Ask how many participants received microloans in Q2.

You'll see the exact response I don't have that information in the approved programme documents.

That completes your external test. The published agent now demonstrates a useful programme answer plus a clear boundary for missing evidence.

Published answers look different?

Return to Studio.
Select Publish again to deploy the current tested version.
Reload the shareable URL in a fresh Safari Private Window.

help me align the published agent with my tested version. If the mismatch continues, share both visible responses with the NextWork community.

Secret mission

Add a Donor-Fit Analysis Mode

Extend your agent with a second evidence domain for fictional donor criteria. The finished agent will compare programme evidence with funding requirements while keeping unresolved application gaps visible.

Clean Up Your Resources

Your Botpress Free workspace stays at $0 while use remains within its included 100 conversations. Choose to keep the agent available, pause active sharing, or delete the agent entirely.

Resources you used:

The published NGO Programme Intelligence Agent. Its project state contains the Programme Knowledge Base. It also contains the Open Horizons Fund Criteria Knowledge Base. The configured Autonomous Node belongs to the same agent. The published version provides the shareable Webchat.

Keep everything running

No action needed. Choose this if you want the published Webchat available for demonstrations.

Retain the published agent in your Botpress workspace.
Keep published Webchat use within the Free plan's included 100 conversations.
Use the Emulator for internal retesting without adding conversations to the conversation quota.

Pause - I'll come back to this later

Pause active use by stopping new sharing or testing. The published URL may remain accessible to anyone who already has it.

Stop sending the copied shareable Webchat URL to other people.
Avoid running tests through the published Webchat.
Retain the agent in your Botpress workspace for later work.

Delete - I don't want to use this again

This option permanently removes the project agent from your workspace. The deletion is final, so take a moment to check the agent name before continuing.

Return to the workspace Home.
Select the NGO Programme Intelligence Agent.
Choose Delete.
Follow the on-screen confirmation to complete the deletion.
Refresh the workspace Home to confirm that the agent is no longer listed.

Your cleanup is complete when NGO Programme Intelligence Agent no longer appears on the workspace Home.

Nice Work!

You did it! You built a published AI agent in Botpress Studio that answers NGO programme questions from approved evidence. Your shareable Webchat now demonstrates grounded answers alongside clear evidence boundaries.

You've learned how to:

Expose a generic agent's knowledge gap by testing an organisation-specific question before supplying approved evidence. You then grounded the agent with a searchable Knowledge Base containing two synthetic programme sources.
Apply RAG guardrails that require retrieval for programme questions. You also configured an exact missing-evidence response to prevent unsupported budgets or results.
Inspect retrieval decisions through global.search activity. You then published a shareable Webchat that reproduces both the grounded Q2 answer and the evidence-gap response.
Secret Mission: Extended the agent with a separate donor Knowledge Base. It now compares programme evidence with Open Horizons Fund Criteria to identify alignment and flag the missing local implementation partner.

Ready to quiz yourself?