Working with Scribes
Scribes are assistants that operate on your data in Obelisk. To function effectively, scribes need two essential components: tomes (access to data) and abilities (permissions to act).
Understanding Sessions
Every interaction with a scribe happens within a session. A session represents a single conversation or workflow, and it's how Obelisk keeps track of what's been discussed, what actions have been taken, and what still needs to happen.
Where Sessions Come From
Sessions can be created in several ways:
- Chat Widget: When someone opens the chat on your website and starts a conversation
- Direct Chat: When you interact with a scribe directly through Obelisk
- API: When your application creates a session programmatically
- Scheduled Tasks: When a scribe runs automatically on a schedule
One-Off vs. Ongoing Conversations
Sessions can represent different types of interactions:
Some sessions are designed to complete a single task and then finish. For example, a scribe that processes a form submission, creates an entry, and sends a confirmation email. Once the task is done, the session completes automatically.
Other sessions involve back-and-forth conversation that might span multiple messages. A customer support scribe or data collection scribe typically works this way, gathering information through natural conversation over time.
How Sessions Complete
Sessions can end in several ways:
- Automatic Completion: When the scribe successfully completes its task, it marks the session as complete
- Inactivity Timeout: If a conversation goes quiet for about 3 minutes after the scribe's last message, Obelisk automatically completes or abandons the session depending on whether the scribe's work is done
- Abandonment: If a session can't be completed (for example, if a user stops responding mid-conversation), it's marked as abandoned
- Error State: If something goes wrong during execution, the session enters an error state
Example:
Imagine a scribe designed to collect event registrations through chat. Someone starts filling out their information but gets distracted and stops responding. After 3 minutes of silence, Obelisk recognizes the conversation has stalled and marks the session as abandoned. The partial data is preserved, but the session is closed.
Later, if they return and start a new conversation, that creates a fresh session with no memory of the previous incomplete interaction.
Understanding Tomes
Tomes give scribes access to your data and reference materials. Think of them as the scribe's source of truth—they define what data the scribe can see and work with. Without the right tomes, a scribe cannot operate on your data.
Example:
If you want a scribe to answer "How many customers signed up this month?", you need an Entry Type Tome pointing to your "Customers" data with All Entries scope. Without this tome, the scribe has no access to customer data and cannot fulfill the request.
Understanding Abilities
Abilities define what actions a scribe can perform on your data. While tomes give access to data, abilities grant permission to act. Without the appropriate ability, a scribe cannot take action even if it has access to the relevant data.
Procedural vs. Generative Abilities
Abilities fall into two categories:
Fixed actions that execute the same way every time. These are system-executed and predictable, ideal for reliable, repeatable workflows.
Actions executed at the scribe's discretion. These allow the scribe to reason about when and how to act based on context, enabling flexible and adaptive workflows.
Lifecycles
Each ability is configured with a lifecycle that determines when it can be triggered:
- On Session Start: Automatically executed when a new session begins
- Anytime: Available for the scribe to use at its discretion during a session
- On New Message: Triggered when the scribe receives a message
- On Session Completion: Executed when a conversation ends
Putting It Together
The key to an effective scribe is ensuring it has access to the right data (tomes) and permission to perform the right actions (abilities) for its intended purpose.
Example: Customer Support Scribe
Tomes needed:
- Entry Type Tome for "Customers" (All Entries scope)
- Entry Type Tome for "Support Tickets" (All Entries scope)
- Text Tome with company policies and FAQs
Abilities needed:
- Generate Chat Message (Anytime) - to respond to users
- Update Entries (Session scope) - to update support tickets
Example: Weekly Reporting Scribe
Tomes needed:
- Entry Type Tome for "Sales Orders" (All Entries scope)
- Script Tome calculating monthly revenue trends
- Script Tome showing top customers by revenue
Abilities needed:
- Send Static Email (On Session Start) - to send weekly reports
Common Patterns
Data Collection
When creating a scribe to collect data through conversation, assign it the Data Gatherer role during creation. This automatically configures the scribe to gather structured data through natural conversation and save it to your specified entry types.
Data Retrieval & Analysis
For scribes that answer questions about your data, add Entry Type Tomes with All Entries scope. This enables the scribe to query and aggregate across your entire dataset. Combine with generative abilities like Generate Chat Message to provide conversational responses about your data.
Workflow Automation
Scribes that automate workflows should have tomes providing context about your data and abilities to act on it. Use lifecycle triggers strategically: On Session Start for initial setup, Anytime for flexible actions, and On Session Completion for follow-up tasks.
Scribe Self-Improvement
One of the most powerful features of scribes is their ability to learn and improve over time. When a scribe session doesn't go as expected, you can provide feedback about what went wrong. The scribe will analyze this feedback and generate a change proposal suggesting improvements to its tomes.
How It Works:
- During or after a session, if something goes wrong, you can provide feedback explaining the issue
- The scribe analyzes your feedback along with the session context and generates a proposal to update or create new tomes to address the issue
- You review the proposal and can either apply it (updating the scribe's knowledge) or reject it
- Over time, your scribe becomes more effective as it learns from real-world interactions
This self-improvement loop means your scribes get smarter with use. Instead of requiring manual updates to documentation and knowledge bases, scribes can propose their own improvements based on actual performance gaps.
Troubleshooting
If your scribe responds with "The request is not possible to complete given the tomes and abilities available to this scribe," it's missing either access to data or permission to act:
- Check tomes: Does the scribe have access to the data it needs? If the request involves specific entry types, ensure you've added Entry Type Tomes with appropriate scopes.
- Check abilities: Does the scribe have permission to perform the requested action? Add abilities that match what you're asking the scribe to do.
- Check scope: Are your tomes scoped appropriately? A Session-scoped Entry Type Tome won't help answer questions about all your data—you need All Entries scope.