Conversation lessons provide an interactive, AI-powered experience where learners can have a guided dialogue with an agent to explore concepts, build models, or solve problems.
Structure
A conversation lesson requires:
-
A
lesson.adocfile with:type: conversation -
A
prompt.txtfile containing instructions for the AI agent -
Optional:
[.conversation-options]list to provide default starting points for users
The prompt.txt File
The prompt.txt file contains instructions that guide the AI agent’s behavior during the conversation.
Purpose:
-
Define the agent’s role and expertise
-
Specify how the agent should interact with users
-
Provide guidelines for question progression and response format
-
Set boundaries and best practices
Best Practices:
-
Use level 2 headings (##) to organize sections
-
Keep instructions clear and actionable
-
Specify response format expectations (e.g., no nested lists, use collapsible blocks)
-
Include examples of good responses
-
Define when and how to end conversations
-
Optimize for token efficiency while maintaining clarity
Example lesson from neo4j-fundamentals course:
= Build your own graph data model
:order: 4
:type: conversation
:optional: true
Now that you are thinking in graphs, let's take a look at the problem you are trying to solve and design a graph data model to solve it.
Tell me about the problem you are trying to solve, or the data that you are working with. You can describe the data in natural language, describe your database schema, or paste in a couple of lines from a CSV file.
I can help you to:
* Identify the **nodes** in the data by extracting the nouns.
* Identify the **relationship** that connect the nodes by identifying the verbs.
* Identify the **properties** that describe the nodes and relationships.
Where should we start?
[.conversation-options]
* Provide product recommendations based on customer purchase history
* Analyse how people are connected in a social network
* Detect fraud in a financial transaction networkExample prompt.txt structure:
**Role:** Help the user craft a graph data model for their use case. This is a teachable moment—the user is always learning. Your job is to make the modeling conversation educational, not just transactional.
**Task:** Orchestrate the conversation. Hand off to the modeling agent for any modeling questions.
Any vague or open-ended message is about data modeling. Formulate a coherent action to pass to the data modeling agent
(e.g. creating a new model from scratch, updating a model, deleting it, or running discovery).
**When the user is vague:** Do not assume they are only exploring. Many users who say things like "I'm not sure",
"help me get started", or "I have some data" want a concrete, tailored model. For vague or open-ended input, hand off
with an instruction that the user wants to build a real model and the modeling agent should start with discovery:
ask what data they have, what questions they need to answer, and what connections exist between entities. Let the
modeling agent ask clarifying questions one at a time; do not skip discovery in the hand-off.
The modeling agent has access to persisted data models, and will always have more context than you.
**Clarifying questions must reach the user.** When the modeling agent returns clarifying questions, pass them through to the user in full so they can answer. Do not drop, summarize, or absorb them into your own reply. The conversation is a loop: the agent asks → the user answers → the model is crafted, expanded, or redefined → the user applies what they've learned → and so on. If the agent's questions never appear, that loop breaks and the user cannot refine the model with you.
When the modeling agent returns clarifying questions, a model update, or the next step in discovery, present that to the user as the ongoing conversation. Do not summarize or "report on" what the subagent did.
**Respond in exactly three paragraphs.** Do not use numbered lists or labels ("What changed:", "Why it matters:", "Next step:") in the text the user sees.Conversation Options
The [.conversation-options] list provides suggested starting points for learners who may not know where to begin.
Purpose:
-
Lower the barrier to entry
-
Provide relevant examples
-
Guide users toward common use cases
-
Reduce cognitive load
Users can click an option to start the conversation, or type their own custom prompt.
When to Use Conversation Lessons
Conversation lessons work best for:
-
Open-ended exploration - Building data models, brainstorming architectures
-
Personalization - Adapting content to the learner’s specific domain or use case
-
Practice - Applying concepts learned in previous lessons to real scenarios
-
Discovery - Helping learners understand possibilities and ask better questions
Avoid conversation lessons when:
-
There’s a single correct answer
-
You need to verify specific technical knowledge
-
The content is purely informational
Tips for Effective Conversation Lessons
-
Start with context - Explain what the agent will help them accomplish
-
Provide examples - Use conversation-options to show possibilities
-
Guide progression - Structure the prompt to move through stages
-
Show value - Have the agent highlight insights that would be difficult without the tool
-
End gracefully - Direct users to the next lesson when they’re ready to move on
Summary
In this lesson, you learned about conversation lessons in GraphAcademy.
You now understand how prompt.txt guides the AI agent’s behavior, and how [.conversation-options] provides users with helpful starting points.
Next, you’ll see a demonstration of a conversation lesson in action.