Assistants Reference Manual v1.3

Suggest edits

Assistants (Gen AI Builder, powered by Griptape) serve as the orchestration layer for intelligent applications, combining knowledge retrieval, behavioral governance, and tool execution into conversational interfaces. They transform static knowledge bases and tools into interactive, governed AI experiences that run inside Hybrid Manager.

Table of contents

Getting Started

Create an assistant: Create Assistant
Prepare data: Create Knowledge Base, Manage Knowledge Base
Control retrieval: Create Retriever
Define behavior: Create Ruleset
Add actions: Create Tool or Create Structure and expose it as a tool

Typical flow: Knowledge Base → Retriever → Ruleset → Tools/Structures → Assistant → Threads

Practical Scenarios

Enterprise knowledge assistant: Answer employee questions from trusted documentation with citations.
- Build steps: Create Knowledge Base → Create Retriever → Create Ruleset → Create Assistant
- Optional: add Tools for ticket creation or document lookup; review in Threads.
Customer support copilot: Guide agents with policy/FAQ grounding and CRM actions.
- Build steps: KB of policies/FAQs → Retriever tuned for recency → Ruleset guardrails → Assistant
- Actions: Create Tool for CRM/ticketing; enforce scope via Rulesets.
Workflow bot: Automate approvals and data enrichment with governed actions.
- Build steps: package business logic as a Structure and expose it as a Tool → attach to Assistant
- Logging: verify execution and outcomes in Threads.
RAG for analytics: Help users explore data with pgvector‑backed retrieval.
- Build steps: prepare embeddings with Pipelines or Data Lake + KB → Retriever → Assistant
- Tune: chunking/metadata, similarity thresholds, and rerank modules.

Configuration Checklist

Model/driver selection appropriate to task (see SDK drivers)
Knowledge: one or more Knowledge Bases and a tuned Retriever
Behavior: Rulesets with clear, non‑conflicting guidance
Actions: Tools and/or Structures with scoped credentials
Memory/Threads: enable auditing, observability, and review flows (Threads)

Architectural Role

Assistants function as the primary interface between users and the Gen AI Builder ecosystem, coordinating multiple components to deliver coherent AI-powered interactions. They integrate with other AI Factory components including Model Serving for inference capabilities, AI Accelerator Pipelines for data processing, and Vector Engine for semantic search operations.

System Integration

Gen AI Builder Components

Knowledge Bases: Provide factual grounding through retrieval-augmented generation patterns
Retrievers: Execute semantic search operations across organizational knowledge
Rulesets: Define behavioral parameters and operational boundaries
Tools: Enable external system integration and action execution
Threads: Maintain conversation state and interaction history

AI Factory Infrastructure

Model Serving: Supplies language model inference capabilities through governed endpoints
Hybrid Manager: Provides underlying orchestration and resource management
Vector Engine: Delivers high-performance semantic search within Postgres infrastructure

Core Architecture

Conversation Processing Pipeline

Assistant operation follows a structured processing sequence that ensures consistent behavior and comprehensive knowledge utilization:

Input Analysis: User queries undergo parsing and intent classification
Knowledge Retrieval: Relevant information extraction from connected knowledge bases
Behavioral Application: Ruleset guidelines applied to response generation parameters
Tool Execution: External actions performed when appropriate and authorized
Response Generation: Language model inference with retrieved context and behavioral constraints
Output Formatting: Response packaging with citations and source attribution

Component Orchestration

Knowledge Integration Assistants coordinate multiple knowledge bases through retriever configurations that optimize search strategies based on content types and organizational requirements. This architecture supports hybrid search approaches combining vector similarity with keyword matching.

Behavioral Governance Rulesets provide operational boundaries that ensure assistant responses align with organizational policies, compliance requirements, and brand standards. These guidelines apply consistently across all interactions while maintaining conversational flexibility.

Tool Integration External system connectivity enables assistants to perform actions beyond information retrieval, including data updates, workflow initiation, and third-party service integration. Tool execution maintains audit trails and access control enforcement. See Tools and Structures.

Operational Characteristics

Conversation Management

Memory Systems Assistants maintain conversation state across multi-turn interactions, preserving context while managing memory limitations imposed by language model constraints. Memory systems support both short-term conversation continuity and long-term preference learning.

Context Window Optimization Efficient context management ensures optimal utilization of language model context windows while preserving conversation coherence. This includes intelligent summarization of conversation history and dynamic context prioritization.

Performance Optimization

Response Generation Language model integration supports various inference strategies including streaming responses for improved user experience and batch processing for high-throughput scenarios. Response generation incorporates retrieved knowledge while maintaining source attribution.

Retrieval Efficiency Knowledge base queries optimize for both accuracy and latency through configurable retrieval strategies. These include similarity thresholds, result ranking algorithms, and caching mechanisms for frequently accessed information.

Scalability Framework

Concurrent Operations Assistants support concurrent user interactions while maintaining individual conversation state isolation. Resource allocation scales dynamically based on demand patterns and organizational capacity constraints.

Resource Management Integration with Hybrid Manager infrastructure enables efficient resource utilization across assistant instances, including GPU allocation for model inference and storage optimization for conversation data.

Configuration Framework

Assistant Definition

Core Configuration Assistant creation requires specification of language model endpoints, knowledge base associations, and behavioral parameters. Configuration supports both template-based initialization and custom parameter specification.

Component Binding Knowledge bases, retrievers, rulesets, and tools connect to assistants through declarative configuration that maintains operational flexibility while ensuring consistent behavior across deployments.

Behavioral Configuration

Ruleset Application Behavioral guidelines define response characteristics including tone, formality, domain expertise, and operational boundaries. Rulesets support both static configuration and dynamic adaptation based on conversation context.

Response Parameters Language model parameters including temperature, token limits, and sampling strategies configure response generation characteristics. These parameters balance creativity with consistency based on application requirements.

Integration Configuration

Knowledge Base Connectivity Multiple knowledge bases connect to individual assistants through retriever configurations that specify search strategies, content filtering, and result ranking approaches. This architecture supports specialized knowledge domains and access control requirements.

Tool Authorization External system integration requires explicit authorization configuration that defines permitted operations, data access boundaries, and audit logging requirements. Tool configuration maintains security isolation while enabling necessary functionality.

Implementation Patterns

Enterprise Knowledge Systems

Departmental Expertise Assistants serve as subject matter expert interfaces for specific organizational domains, combining deep knowledge bases with appropriate behavioral characteristics for different user communities.

Cross-Functional Support Multi-domain assistants integrate knowledge from diverse organizational sources while maintaining appropriate access controls and information routing based on user permissions and query characteristics.

Customer-Facing Applications

Support Automation Customer service assistants combine product documentation, policy information, and troubleshooting knowledge to provide consistent support experiences while maintaining escalation pathways for complex issues.

Self-Service Portals Interactive knowledge access through conversational interfaces reduces support burden while providing comprehensive information discovery capabilities for customer self-service scenarios.

Internal Productivity Tools

Research Assistance Knowledge workers benefit from assistants that aggregate information across diverse internal sources, providing rapid access to organizational knowledge while maintaining appropriate attribution and source verification.

Decision Support Complex decision-making scenarios leverage assistants that combine quantitative data analysis with qualitative knowledge synthesis to support informed organizational choices.

Quality Assurance

Response Validation

Accuracy Verification Systematic evaluation procedures ensure assistant responses align with source knowledge while maintaining factual correctness. This includes both automated validation and human review processes for critical applications.

Citation Integrity Source attribution accuracy supports organizational transparency and enables users to verify information independently. Citation systems maintain detailed provenance tracking from original sources through response generation.

Performance Monitoring

Conversation Analytics Comprehensive metrics track assistant effectiveness including user satisfaction, query resolution rates, and escalation patterns. Analytics support continuous improvement and optimization strategies.

System Performance Technical performance monitoring includes response latency, resource utilization, and system availability metrics that ensure consistent user experiences across varying load conditions.

Operational Considerations

Deployment Strategies

Development Workflows Assistant development follows systematic procedures including knowledge base validation, behavioral testing, and integration verification before production deployment. Development environments support iterative refinement and testing. See Create Assistant and SDK references.

Production Management Live assistant management includes performance monitoring, content updates, and behavioral adjustments based on operational feedback and changing organizational requirements.

Maintenance Procedures

Knowledge Base Updates Content synchronization ensures assistants access current organizational information while maintaining response consistency during transition periods. Update procedures support both incremental changes and comprehensive content refreshes.

Behavioral Refinement Ruleset modifications enable assistant behavior adaptation based on user feedback, organizational policy changes, and operational experience. Behavioral changes maintain consistency while supporting organizational evolution.

Security Framework

Access Control

User Authentication Assistant access integrates with organizational identity management systems while supporting both authenticated users and anonymous interactions based on deployment requirements and security policies.

Information Governance Knowledge base access respects organizational data classification and user permission frameworks, ensuring appropriate information exposure while maintaining comprehensive knowledge accessibility.

Audit Capabilities

Interaction Logging Detailed conversation logs support compliance requirements, operational analysis, and security monitoring while respecting privacy considerations and data retention policies.

Decision Traceability Response generation processes maintain comprehensive audit trails that enable verification of information sources, reasoning pathways, and decision factors for accountability and improvement purposes.

Integration Ecosystem

AI Factory Components

Assistants operate within the broader AI Factory ecosystem, leveraging capabilities from:

Model Serving: Provides governed language model inference
AI Accelerator Pipelines: Enables knowledge base content processing
Vector Engine: Delivers semantic search infrastructure

Development Resources

Implementation Guides

Create Assistant: Step‑by‑step assistant configuration
Knowledge Base Integration: Comprehensive knowledge management
Tool Development: External system integration patterns

Use Cases

Enterprise knowledge assistants: KB + Retriever + Assistant + Tools (e.g., ticketing/CRM)
Customer support copilots: policy/FAQ KBs + routing + guardrails via Rulesets
Workflow bots: Structures + Tools for approvals, enrichment, reporting
RAG for analytics: pgvector + Pipelines + Assistant for guided exploration

SDK Quick Links

SDK overview: Gen AI Builder SDK
Drivers: Assistant/Prompt, Conversation Memory
Structures: Agents, Tasks, Workflows
Observability: Structures/observability

FAQ

How do I wire an Assistant to multiple Knowledge Bases?
- Create a Retriever targeting multiple KBs; assign it in Create Assistant. Use metadata filters per source.
How do I let an Assistant call my internal APIs?
- Package a Tool (or promote a Structure) with scoped credentials; attach it to the Assistant; enforce usage via Rulesets.
How do I test and debug?
- Use the test chat and Threads. Validate retrieval sets, check Ruleset revisions, and re‑run with stored inputs. Export traces where needed.
How do I choose models/drivers?
- Start with general models; route task‑specific prompts to cheaper/faster drivers; for private endpoints, integrate via Model Serving.

Assistants provide the foundational interface for intelligent applications within Gen AI Builder, orchestrating knowledge, behavior, and capabilities into coherent conversational experiences that operate within organizational governance frameworks.

↑ Up

Gen AI Builder

Knowledge Bases Reference Manual