Assistants Reference Manual
===========================

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 :ref:`Knowledge Bases Reference Manual <Knowledge Bases Reference Manual>`  and :ref:`Tools Reference Manual <Tools Reference Manual>`  into
interactive, governed AI experiences that run inside :ref:`EDB’s vision for AI with Postgres and Hybrid Manager <EDB’s vision for AI with Postgres and Hybrid Manager>`  .

Table of contents

- :ref:`Getting Started - AI Factory 101 <Getting Started - AI Factory 101>` 

- :ref:`Practical Scenarios <Practical Scenarios>` 

- :ref:`Configuration Checklist <Configuration Checklist>` 

- :ref:`Architectural Role <Architectural Role>` 

- :ref:`Core Architecture <Core Architecture>` 

- :ref:`Operational Characteristics <Operational Characteristics>` 

- :ref:`Integration Ecosystem <Integration Ecosystem>` 

- :ref:`Use cases <Use cases>` 

- :ref:`SDK Quick Links <SDK Quick Links>` 

- :ref:`FAQ <FAQ>` 

Getting Started
---------------

- Create an assistant: :ref:`Create an Assistant in Gen AI Builder <Create an Assistant in Gen AI Builder>` 

- Prepare data: :ref:`Create a Knowledge Base in Gen AI Builder <Create a Knowledge Base in Gen AI Builder>`  , :ref:`Manage Knowledge Bases in Gen AI Builder <Manage Knowledge Bases in Gen AI Builder>` 

- Control retrieval: :ref:`Create a Retriever in Gen AI Builder <Create a Retriever in Gen AI Builder>` 

- Define behavior: :ref:`Create a Ruleset in Gen AI Builder <Create a Ruleset in Gen AI Builder>` 

- Add actions: :ref:`Create a Tool in Gen AI Builder <Create a Tool in Gen AI Builder>`  or :ref:`Create a Structure in Gen AI Builder <Create a Structure in Gen AI Builder>`  and expose it as a tool

Typical flow: Knowledge Base → Retriever → Ruleset → Tools/Structures →
Assistant → :ref:`Threads Reference Manual <Threads Reference Manual>` 

Practical Scenarios
-------------------

- Enterprise knowledge assistant: Answer employee questions from trusted
  documentation with citations.

- Build steps: :ref:`Create a Knowledge Base in Gen AI Builder <Create a Knowledge Base in Gen AI Builder>`  → :ref:`Create a Retriever in Gen AI Builder <Create a Retriever in Gen AI Builder>`  → :ref:`Create a Ruleset in Gen AI Builder <Create a Ruleset in Gen AI Builder>`  →
  :ref:`Create an Assistant in Gen AI Builder <Create an Assistant in Gen AI Builder>` 

- Optional: add :ref:`Tools Reference Manual <Tools Reference Manual>`  for ticket creation or document lookup;
  review in :ref:`Threads Reference Manual <Threads Reference Manual>`  .

- Customer support copilot: Guide agents with policy/FAQ grounding and
  CRM actions.

- Build steps: KB of policies/FAQs → :ref:`Retrievers Reference Manual <Retrievers Reference Manual>`  tuned for recency →
  :ref:`Rulesets Manual <Rulesets Manual>`  guardrails → :ref:`Create an Assistant in Gen AI Builder <Create an Assistant in Gen AI Builder>` 

- Actions: :ref:`Create a Tool in Gen AI Builder <Create a Tool in Gen AI Builder>`  for CRM/ticketing; enforce scope via Rulesets.

- Workflow bot: Automate approvals and data enrichment with governed
  actions.

- Build steps: package business logic as a :ref:`Create a Structure in Gen AI Builder <Create a Structure in Gen AI Builder>`  and expose it
  as a Tool → attach to :ref:`Create an Assistant in Gen AI Builder <Create an Assistant in Gen AI Builder>` 

- Logging: verify execution and outcomes in :ref:`Threads Reference Manual <Threads Reference Manual>`  .

- RAG for analytics: Help users explore data with pgvector‑backed
  retrieval.

- Build steps: prepare embeddings with :ref:`Pipelines and data preparation <Pipelines and data preparation>`  or :ref:`Configure the Data Lake in Gen AI Builder <Configure the Data Lake in Gen AI Builder>` 
  + KB → :ref:`Retrievers Reference Manual <Retrievers Reference Manual>`  → :ref:`Create an Assistant in Gen AI Builder <Create an Assistant in Gen AI Builder>` 

- Tune: chunking/metadata, similarity thresholds, and rerank modules.

Configuration Checklist
-----------------------

- Model/driver selection appropriate to task (see SDK :ref:`Which models/drivers are supported? <Which models/drivers are supported?>`  )

- Knowledge: one or more :ref:`Knowledge Bases Reference Manual <Knowledge Bases Reference Manual>`  and a tuned :ref:`Retrievers Reference Manual <Retrievers Reference Manual>` 

- Behavior: :ref:`Rulesets Manual <Rulesets Manual>`  with clear, non‑conflicting guidance

- Actions: :ref:`Tools Reference Manual <Tools Reference Manual>`  and/or :ref:`Structures Reference Manual <Structures Reference Manual>`  with scoped credentials

- Memory/Threads: enable auditing, observability, and review flows (
  :ref:`Threads Reference Manual <Threads Reference Manual>`  )

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 :ref:`Model serving and inference <Model serving and inference>`  for inference capabilities,
:ref:`AI Accelerator Pipelines <AI Accelerator Pipelines>`  for data processing, and :ref:`Vector Engine (PGvector) <Vector Engine (PGvector)>`  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:

1. **Input Analysis**: User queries undergo parsing and intent
   classification

2. **Knowledge Retrieval**: Relevant information extraction from
   connected knowledge bases

3. **Behavioral Application**: Ruleset guidelines applied to response
   generation parameters

4. **Tool Execution**: External actions performed when appropriate and
   authorized

5. **Response Generation**: Language model inference with retrieved
   context and behavioral constraints

6. **Output Formatting**: Response packaging with citations and source
   attribution

Component Orchestration
^^^^^^^^^^^^^^^^^^^^^^^

**Knowledge Integration** Assistants coordinate multiple knowledge bases
through :ref:`Retrievers Reference Manual <Retrievers Reference Manual>`  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
:ref:`Tools Reference Manual <Tools Reference Manual>`  and :ref:`Structures Reference Manual <Structures Reference Manual>`  .

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
:ref:`Create an Assistant in Gen AI Builder <Create an Assistant in Gen AI Builder>`  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:

- \*\* :ref:`Model serving and inference <Model serving and inference>`  \*\*: Provides governed language model inference

- \*\* :ref:`AI Accelerator Pipelines <AI Accelerator Pipelines>`  \*\*: Enables knowledge base content processing

- \*\* :ref:`Vector Engine (PGvector) <Vector Engine (PGvector)>`  \*\*: Delivers semantic search infrastructure

Development Resources
^^^^^^^^^^^^^^^^^^^^^

**Implementation Guides**

- :ref:`Create an Assistant in Gen AI Builder <Create an Assistant in Gen AI Builder>`  : Step‑by‑step assistant configuration

- :ref:`Knowledge Bases Reference Manual <Knowledge Bases Reference Manual>`  : Comprehensive knowledge management

- :ref:`Tools Reference Manual <Tools Reference Manual>`  : 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: :ref:`Gen AI Builder SDK </edb-postgres-ai/1.3/ai-factory/gen-ai/reference/sdk/>` 

- Drivers: :ref:`Assistant/Prompt <Concepts>`  , :ref:`Conversation Memory <reference/sdk/drivers/conversation-memory-drivers.mdx>` 

- Structures: :ref:`Agents <Concepts>`  , :ref:`Tasks <Structures Reference Manual>`  , :ref:`Structures (workflows and building blocks) <Structures (workflows and building blocks)>` 

- Observability: :ref:`Structures/observability <Structures Reference Manual>` 

FAQ
---

- How do I wire an Assistant to multiple Knowledge Bases? - Create a
  :ref:`Create a Retriever in Gen AI Builder <Create a Retriever in Gen AI Builder>`  targeting multiple KBs; assign it in :ref:`Create an Assistant in Gen AI Builder <Create an Assistant in Gen AI Builder>`  .
  Use metadata filters per source.

- How do I let an Assistant call my internal APIs? - Package a
  :ref:`Create a Tool in Gen AI Builder <Create a Tool in Gen AI Builder>`  (or promote a :ref:`Create a Structure in Gen AI Builder <Create a Structure in Gen AI Builder>`  ) with scoped credentials;
  attach it to the Assistant; enforce usage via :ref:`Create a Ruleset in Gen AI Builder <Create a Ruleset in Gen AI Builder>`  .

- How do I test and debug? - Use the test chat and :ref:`Threads Reference Manual <Threads Reference Manual>`  .
  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 :ref:`Model serving and inference <Model serving and inference>`  .

--------------

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.