diff --git a/README.md b/README.md index e79df5f..598091d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,11 @@ # ChatBotKit Terraform Provider +[![Terraform Registry](https://img.shields.io/badge/Terraform-Registry-purple.svg)](https://registry.terraform.io/providers/chatbotkit/chatbotkit/latest) + This directory contains the ChatBotKit Terraform Provider, which allows you to manage ChatBotKit resources using Terraform. +**Terraform Registry:** https://registry.terraform.io/providers/chatbotkit/chatbotkit/latest + ## Building ```bash @@ -52,43 +56,29 @@ CHATBOTKIT_API_KEY=your-api-key go test -v ./internal/provider/ -run "^TestAcc" ## Directory Structure ``` -sdks/terraform/ -├── main.go # Provider entry point -├── go.mod # Go module definition -├── go.sum # Go dependencies -├── .goreleaser.yml # Release configuration -├── terraform-registry-manifest.json # Registry manifest -├── docs/ # Terraform Registry documentation -│ ├── index.md # Provider documentation -│ ├── resources/ # Resource documentation -│ └── data-sources/ # Data source documentation +terraform-provider-chatbotkit/ +├── main.go # Provider entry point +├── go.mod # Go module definition +├── go.sum # Go dependencies +├── .goreleaser.yml # Release configuration +├── terraform-registry-manifest.json # Registry manifest +├── docs/ # Terraform Registry documentation +│ ├── index.md # Provider documentation +│ ├── resources/ # Resource documentation +│ └── data-sources/ # Data source documentation ├── types/ -│ └── types.go # Generated Go types +│ └── types.go # Generated Go types ├── internal/ │ └── provider/ -│ ├── client.go # GraphQL API client -│ ├── client_test.go # Client unit tests -│ ├── provider.go # Provider configuration -│ ├── provider_test.go # Provider tests -│ ├── resource_*.go # Resource implementations -│ └── resource_*_test.go # Resource tests +│ ├── client.go # GraphQL API client +│ ├── client_test.go # Client unit tests +│ ├── provider.go # Provider configuration +│ ├── provider_test.go # Provider tests +│ ├── resource_*.go # Resource implementations +│ └── resource_*_test.go # Resource tests └── examples/ └── basic/ - └── main.tf # Example Terraform configuration -``` - -## Regenerating Code - -The provider code is generated from the GraphQL schema: - -```bash -cd sites/main - -# Generate Go types -pnpm script:sync-api-spec-to-terraform - -# Generate provider resources and client -pnpm script:gen-terraform-stubs + └── main.tf # Example Terraform configuration ``` ## Resources @@ -122,12 +112,12 @@ The provider supports the following resources: The provider supports the following data sources for reading existing resources: -| Data Source | Description | -| -------------------- | ----------------------------------- | -| `chatbotkit_bot` | Read information about an existing bot | -| `chatbotkit_dataset` | Read information about an existing dataset | +| Data Source | Description | +| ---------------------- | -------------------------------------------- | +| `chatbotkit_bot` | Read information about an existing bot | +| `chatbotkit_dataset` | Read information about an existing dataset | | `chatbotkit_blueprint` | Read information about an existing blueprint | -| `chatbotkit_skillset` | Read information about an existing skillset | +| `chatbotkit_skillset` | Read information about an existing skillset | ## Example Usage diff --git a/VERSION b/VERSION index 3eefcb9..7dea76e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.0.0 +1.0.1 diff --git a/examples/README.md b/examples/README.md index 6665644..cc433bf 100644 --- a/examples/README.md +++ b/examples/README.md @@ -19,7 +19,9 @@ These examples demonstrate production-ready architectures based on ChatBotKit bl |---------|-------------|--------------| | [skillset-based-dynamic-skill](./skillset-based-dynamic-skill/) | Agent that dynamically discovers and loads skills | Dynamic skill loading, Modular architecture, List & Install abilities | | [ai-employee](./ai-employee/) | Comprehensive AI Employee for professional environments | Workspace/Space, Shell execution, Gmail integration, Notion integration, Dynamic skillsets | -| [matillion-operations](./matillion-operations/) | AI-powered operations center for Matillion Data Productivity Cloud | 4 specialized skillsets, Pipeline management, Schedule management, Monitoring, Scheduled health checks | +| [simple-self-improving-agent](./simple-self-improving-agent/) | Self-improving agent that learns from interactions | Backstory file management, Read/Write abilities, Continuous learning | +| [mcp-factory](./mcp-factory/) | Factory-style architecture with multiple MCP server integrations | 4 service skillsets, Modular MCP servers, Clear separation of concerns | +| [dynamic-mcp-search-and-install](./dynamic-mcp-search-and-install/) | Agent that dynamically discovers and installs MCP servers | MCP registry search, On-demand installation, Self-extending capabilities | ## Getting Started @@ -112,6 +114,39 @@ Demonstrates a sophisticated AI employee with workspace and multiple integration **Use when:** Building autonomous digital team members with access to tools and services. +### Simple Self-improving Agent Example +Demonstrates a self-improving AI agent that learns from interactions. + +**What you'll learn:** +- File resource management for backstory storage +- Read and write abilities for file manipulation +- Self-improvement patterns +- Continuous learning architectures + +**Use when:** Building agents that need to adapt and improve based on real-world usage. + +### MCP Factory Example +Factory-style architecture with multiple independent MCP server integrations. + +**What you'll learn:** +- Modular MCP server organization +- Multiple skillset patterns +- Service isolation and boundaries +- MCP server integration setup + +**Use when:** Providing a suite of distinct AI functionalities to multiple clients or users. + +### Dynamic MCP Search and Install Example +Agent that discovers and installs MCP servers on-demand from a registry. + +**What you'll learn:** +- MCP registry search capabilities +- Dynamic MCP installation patterns +- Self-extending agent architectures +- On-demand capability loading + +**Use when:** Building adaptable agents that discover and integrate tools as needed. + ### Matillion Operations Example AI-powered operations center for data pipeline management. diff --git a/examples/dynamic-mcp-search-and-install/README.md b/examples/dynamic-mcp-search-and-install/README.md new file mode 100644 index 0000000..7be96f6 --- /dev/null +++ b/examples/dynamic-mcp-search-and-install/README.md @@ -0,0 +1,208 @@ +# Dynamic MCP Search and Install Architecture + +This example demonstrates a reference architecture for an AI agent that can search for and install Model Context Protocol (MCP) servers dynamically. + +## Overview + +This blueprint demonstrates a dynamic architecture for an MCP server that allows the AI agent to search for and install Model Context Protocol (MCP) servers from a known registry. By combining search and installation capabilities, this blueprint enables agents to discover and integrate new MCP servers on-demand, creating a self-extending system that grows its functionality as needed. + +## Architecture + +``` +┌──────────────────────────────────────────────────────────┐ +│ Dynamic MCP Agent │ +│ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ MCP Discovery Skillset │ │ +│ │ ┌──────────────────┐ ┌──────────────────┐ │ │ +│ │ │ Search MCP │ │ Install MCP │ │ │ +│ │ │ Servers │ │ (by URL) │ │ │ +│ │ └──────────────────┘ └──────────────────┘ │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────┐ │ +│ │ MCP Registry │ │ +│ └───────┬───────┘ │ +│ ┌──────────────┼──────────────┬──────────────┐ │ +│ │ │ │ │ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ File │ │ GitHub │ │ Database│ │ Slack │ │ +│ │ System │ │ MCP │ │ MCP │ │ MCP │ │ +│ │ MCP │ │ │ │ │ │ │ │ +│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ +│ │ +│ (Installed on-demand as needed) │ +└──────────────────────────────────────────────────────────┘ +``` + +## Key Features + +1. **Dynamic Discovery**: Search for MCP servers by name or description in a registry +2. **On-Demand Installation**: Install MCP servers only when needed for specific tasks +3. **Self-Extending**: Agent gains new capabilities without manual reconfiguration +4. **Flexible Integration**: Connect to any MCP server available in the registry + +## Core Abilities + +### Search MCP Servers +Uses the `registry/server/search` template to find available MCP servers. The agent can: +- Search by server name +- Search by description or keywords +- Discover servers that provide needed functionality +- Review server metadata before installation + +### Install MCP +Uses the `conversation/mcp/install[url]` template to activate an MCP server by its URL. Once installed: +- The server's tools become available to the agent +- Functions can be called directly in the conversation +- Capabilities persist for the duration of the conversation + +## How It Works + +### Discovery Flow + +1. **User Request**: User asks for functionality the agent doesn't have +2. **Search**: Agent searches the MCP registry for relevant servers +3. **Selection**: Agent identifies the most appropriate MCP server +4. **Installation**: Agent installs the MCP server using its URL +5. **Utilization**: Agent uses the newly available tools to complete the task + +### Example Interaction + +**User**: "Can you help me analyze the files in my project directory?" + +**Agent**: +1. Searches for MCP servers related to file system access +2. Finds a "filesystem" MCP server in the registry +3. Installs it using the server's URL +4. Uses the filesystem tools to list and analyze files +5. Provides the requested analysis to the user + +## Usage + +1. Set your ChatBotKit API key: +```bash +export CHATBOTKIT_API_KEY="your-api-key" +``` + +2. Initialize Terraform: +```bash +terraform init +``` + +3. Review the planned changes: +```bash +terraform plan +``` + +4. Apply the configuration: +```bash +terraform apply +``` + +5. Test the agent by: + - Asking it to search for specific MCP servers + - Requesting functionality that requires MCP installation + - Observing how it discovers and integrates new capabilities + +## Testing the Agent + +### Search for MCP Servers +``` +User: "What MCP servers are available for working with GitHub?" +Agent: [Searches registry and lists GitHub-related MCP servers] +``` + +### Install and Use an MCP Server +``` +User: "I need to check my GitHub repositories" +Agent: [Searches for GitHub MCP, installs it, then uses its tools to list repositories] +``` + +## MCP Registry + +The agent searches a registry of available MCP servers. Common MCP servers include: + +- **Filesystem**: Access and manipulate local files +- **GitHub**: Interact with GitHub repositories and issues +- **PostgreSQL**: Query and manage PostgreSQL databases +- **Slack**: Send messages and interact with Slack +- **Google Drive**: Access and manage Google Drive files +- **Memory**: Persistent key-value storage +- **Fetch**: Make HTTP requests to external APIs + +## Customization + +### Adding Search Filters + +Enhance the search ability with filters: + +```hcl +resource "chatbotkit_skillset_ability" "search_mcp_advanced" { + skillset_id = chatbotkit_skillset.mcp_discovery.id + name = "Advanced MCP Search" + description = "Search MCP servers with filters" + instruction = <<-EOT + template: registry/server/search + parameters: + query: $[query! ys|search terms] + category: $[category ys|server category (e.g., database, filesystem)] + EOT +} +``` + +### Installing Multiple MCP Servers + +The agent can install multiple MCP servers in a single conversation: + +```hcl +# The agent can call the install ability multiple times +# Each installation adds to the available tools +``` + +## When to Use This Pattern + +This pattern is ideal when: +- Agent needs diverse, specialized capabilities that vary by use case +- You want to avoid pre-installing all possible tools +- Requirements evolve and new MCP servers become available +- Users need access to different sets of integrations +- You want a self-service approach to capability extension + +## Benefits + +1. **Reduced Initial Complexity**: Start simple, add capabilities as needed +2. **Efficient Resource Usage**: Only load tools when required +3. **Future-Proof**: Automatically gain access to new MCP servers as they're added to the registry +4. **User-Driven**: Agent adapts to specific user needs dynamically +5. **Maintainable**: No need to reconfigure for new integrations + +## Important Considerations + +1. **Registry Quality**: Ensure the MCP registry contains trustworthy servers +2. **Installation Limits**: Consider rate limits or caps on installations per conversation +3. **Security**: Validate MCP servers before installation to prevent malicious code +4. **Performance**: Installing multiple large MCP servers may impact response times + +## Comparison with Static MCP Configuration + +| Aspect | Dynamic (This Pattern) | Static Configuration | +|--------|----------------------|---------------------| +| Setup Complexity | Low (just search/install abilities) | High (configure each MCP server) | +| Runtime Flexibility | High (discover new servers) | Low (fixed set of servers) | +| Resource Efficiency | High (load on-demand) | Low (all loaded upfront) | +| User Experience | Adaptive (fits needs) | Consistent (same tools always) | + +## Cleanup + +To destroy all created resources: +```bash +terraform destroy +``` + +## Learn More + +- [Model Context Protocol Specification](https://modelcontextprotocol.io) +- [ChatBotKit MCP Documentation](https://chatbotkit.com/docs/integrations/mcp) +- [ChatBotKit Registry Documentation](https://chatbotkit.com/docs/registry) +- [Blueprint Reference Architecture Examples](https://chatbotkit.com/blueprints) diff --git a/examples/dynamic-mcp-search-and-install/main.tf b/examples/dynamic-mcp-search-and-install/main.tf new file mode 100644 index 0000000..a564663 --- /dev/null +++ b/examples/dynamic-mcp-search-and-install/main.tf @@ -0,0 +1,135 @@ +# Dynamic MCP Search and Install Architecture +# +# This example demonstrates a reference architecture for an AI agent that can +# search for and install Model Context Protocol (MCP) servers dynamically from +# a known registry. +# +# Architecture highlights: +# - Bot with dynamic MCP discovery capabilities +# - Search MCP servers by name or description +# - Install MCP servers on-demand +# - Self-extending system that grows functionality as needed +# +# Prerequisites: +# - Set the CHATBOTKIT_API_KEY environment variable + +terraform { + required_providers { + chatbotkit = { + source = "chatbotkit/chatbotkit" + } + } +} + +provider "chatbotkit" { + # api_key = "..." # Or set CHATBOTKIT_API_KEY env var +} + +# ============================================================================ +# Core Skillset +# ============================================================================ +# Contains abilities for discovering and installing MCP servers + +resource "chatbotkit_skillset" "mcp_discovery" { + name = "MCP Discovery" + description = "Abilities for searching and installing MCP servers dynamically" +} + +# ============================================================================ +# MCP Discovery Abilities +# ============================================================================ +# Abilities that enable the agent to search for and install MCP servers + +resource "chatbotkit_skillset_ability" "search_mcp" { + skillset_id = chatbotkit_skillset.mcp_discovery.id + name = "Search MCP Servers" + description = "Search for Model Context Protocol (MCP) servers by name or description" + instruction = <<-EOT + template: registry/server/search + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "install_mcp" { + skillset_id = chatbotkit_skillset.mcp_discovery.id + name = "Install MCP" + description = "Bring MCP (model context protocol) functions into context" + instruction = <<-EOT + template: conversation/mcp/install[url] + parameters: + url: '' + EOT +} + +# ============================================================================ +# Dynamic MCP Agent Bot +# ============================================================================ +# The agent bot that can search for and install MCP servers on-demand + +resource "chatbotkit_bot" "agent" { + name = "Dynamic MCP Agent" + description = "An AI agent that can search for and install Model Context Protocol (MCP) servers dynamically" + backstory = <<-EOT + You are an intelligent agent with the ability to discover and dynamically integrate + Model Context Protocol (MCP) servers to extend your capabilities. When faced with a + task that requires specific tools or integrations, you can: + + 1. **Search for MCP Servers**: Use the Search MCP Servers ability to find available + MCP servers by name or description. Look for servers that provide the functionality + needed for the current task. + + 2. **Install MCP Servers**: Once you've identified a relevant MCP server, use the + Install MCP ability to bring its functions into your conversation context. Provide + the server's URL to activate it. + + 3. **Use Installed Capabilities**: After installing an MCP server, you'll have access + to its tools and functions. Use them to accomplish tasks that require specialized + capabilities. + + This dynamic approach allows you to adapt to diverse requirements without requiring + manual reconfiguration. You can discover and integrate exactly the tools you need, + when you need them. + + ## Guidelines for MCP Discovery + + **When to Search**: + - User requests functionality you don't currently have + - Task requires specialized tools or data access + - Integration with external services would be beneficial + + **How to Search**: + - Use descriptive search terms matching the needed functionality + - Look for servers from trusted sources or well-known providers + - Review server descriptions to ensure they match your needs + + **Before Installing**: + - Verify the MCP server provides the needed capabilities + - Check that it's from a reliable source + - Explain to the user what capabilities you're adding and why + + **After Installing**: + - Explore the newly available tools and functions + - Use them appropriately to complete the user's request + - Inform the user about the new capabilities you've acquired + + Remember: You are a self-extending system. Your ability to discover and integrate + new MCP servers makes you highly adaptable to evolving requirements. + EOT + model = "claude-4.5-sonnet" + + skillset_id = chatbotkit_skillset.mcp_discovery.id +} + +# ============================================================================ +# Outputs +# ============================================================================ + +output "bot_id" { + description = "The ID of the dynamic MCP agent" + value = chatbotkit_bot.agent.id +} + +output "skillset_id" { + description = "The ID of the MCP discovery skillset" + value = chatbotkit_skillset.mcp_discovery.id +} diff --git a/examples/mcp-factory/README.md b/examples/mcp-factory/README.md new file mode 100644 index 0000000..8521fea --- /dev/null +++ b/examples/mcp-factory/README.md @@ -0,0 +1,233 @@ +# MCP Factory Reference Architectures + +This example demonstrates a factory-style architecture for MCP servers that expose multiple skillsets and abilities through separate MCP server integrations. + +## Overview + +This blueprint demonstrates a factory-style architecture for an MCP server that exposes multiple skillsets and abilities through separate MCP server integrations. Each skillset is designed to encapsulate specific functionalities, allowing for modular and organized management of AI capabilities. + +## Architecture + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ MCP Factory Architecture │ +│ │ +│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ Analytics MCP │ │ Content MCP │ │ Research MCP │ │ +│ │ Server │ │ Server │ │ Server │ │ +│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │ +│ │ │ │ │ +│ ┌────────▼────────┐ ┌────────▼────────┐ ┌────────▼────────┐ │ +│ │ Analytics │ │ Content │ │ Research │ │ +│ │ Skillset │ │ Skillset │ │ Skillset │ │ +│ │ │ │ │ │ │ │ +│ │ • Analyze Data │ │ • Create │ │ • Search Info │ │ +│ │ • Generate │ │ • Edit │ │ • Summarize │ │ +│ │ Report │ │ │ │ │ │ +│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ +│ │ +│ ┌─────────────────┐ │ +│ │ Tasks MCP │ │ +│ │ Server │ │ +│ └────────┬────────┘ │ +│ │ │ +│ ┌────────▼────────┐ │ +│ │ Tasks │ │ +│ │ Skillset │ │ +│ │ │ │ +│ │ • Plan Tasks │ │ +│ │ • Track Progress│ │ +│ └─────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +## Key Features + +1. **Modular Architecture**: Each skillset is independent and encapsulates specific functionality +2. **Separate MCP Servers**: Each skillset has its own MCP server integration for clear boundaries +3. **Scalable Design**: Easy to add new services without affecting existing ones +4. **Clear Separation**: Each service has a well-defined scope and responsibility + +## Services + +### Analytics Service +**Purpose**: Data analytics and reporting capabilities + +**Abilities**: +- **Analyze Data**: Perform comprehensive data analysis +- **Generate Report**: Create detailed analytics reports + +**Use Cases**: +- Business intelligence dashboards +- Data-driven decision making +- Performance metrics tracking + +### Content Service +**Purpose**: Content creation and management + +**Abilities**: +- **Create Content**: Generate new content based on specifications +- **Edit Content**: Modify and refine existing content + +**Use Cases**: +- Marketing content generation +- Documentation management +- Content workflow automation + +### Research Service +**Purpose**: Information gathering and synthesis + +**Abilities**: +- **Search Information**: Find relevant information on topics +- **Summarize Findings**: Create concise summaries + +**Use Cases**: +- Competitive analysis +- Market research +- Literature reviews + +### Task Management Service +**Purpose**: Task planning and execution tracking + +**Abilities**: +- **Plan Tasks**: Create structured task plans +- **Track Progress**: Monitor and report on progress + +**Use Cases**: +- Project management +- Workflow coordination +- Progress reporting + +## Usage + +1. Set your ChatBotKit API key: +```bash +export CHATBOTKIT_API_KEY="your-api-key" +``` + +2. Initialize Terraform: +```bash +terraform init +``` + +3. Review the planned changes: +```bash +terraform plan +``` + +4. Apply the configuration: +```bash +terraform apply +``` + +5. Access the MCP servers: + - Navigate to the ChatBotKit dashboard + - Find each MCP server integration + - Copy the MCP server URLs + - Use these URLs in compatible MCP clients (Claude Desktop, etc.) + +## Connecting to MCP Servers + +After applying this configuration, each MCP server will be available through the ChatBotKit platform. To connect: + +1. **From Claude Desktop or other MCP clients**: + - Add the MCP server URL to your client configuration + - Authenticate using your ChatBotKit credentials + - The abilities from that skillset will be available to the client + +2. **From ChatBotKit Bots**: + - Assign the skillset to a bot + - The bot will have access to the skillset's abilities + - Multiple bots can share the same skillsets + +## Customization + +### Adding a New Service + +To add a new service to the factory: + +```hcl +resource "chatbotkit_skillset" "monitoring_service" { + name = "Monitoring Service" + description = "System monitoring and alerting capabilities" +} + +resource "chatbotkit_skillset_ability" "monitor_health" { + skillset_id = chatbotkit_skillset.monitoring_service.id + name = "Check Health" + description = "Monitor system health and status" + instruction = <<-EOT + # Monitoring logic here + EOT +} + +resource "chatbotkit_mcp_server_integration" "monitoring_mcp" { + skillset_id = chatbotkit_skillset.monitoring_service.id + name = "Monitoring MCP Server" + description = "MCP server exposing monitoring capabilities" +} +``` + +### Implementing Real Abilities + +Replace placeholder logic with actual implementations: + +```hcl +resource "chatbotkit_skillset_ability" "analytics_analyze" { + skillset_id = chatbotkit_skillset.analytics_service.id + name = "Analyze Data" + description = "Perform comprehensive data analysis" + instruction = <<-EOT + template: search/web + parameters: + query: $[query! ys|data analysis query] + EOT +} +``` + +## When to Use This Pattern + +This pattern is ideal when: +- You need to provide a suite of distinct AI functionalities +- Different teams or users need access to different capabilities +- You want clear boundaries between service domains +- Centralized management of AI resources is required +- Multiple client applications need to consume AI services + +## Benefits + +1. **Clear Boundaries**: Each service is self-contained with well-defined responsibilities +2. **Independent Scaling**: Services can be scaled independently based on demand +3. **Easy Maintenance**: Changes to one service don't affect others +4. **Flexible Access Control**: Can grant access to specific services per user/team +5. **Simplified Monitoring**: Each MCP server can be monitored separately + +## Architecture Patterns + +### Factory Pattern +This architecture follows the factory pattern where: +- Each skillset is a "product" in the factory +- Each MCP server is a "distribution channel" for that product +- New products (skillsets) can be added without changing existing ones + +### Microservices Inspiration +While not true microservices, this architecture borrows concepts: +- Service isolation +- Independent deployment +- Clear service boundaries +- API-first design (via MCP protocol) + +## Cleanup + +To destroy all created resources: +```bash +terraform destroy +``` + +## Learn More + +- [ChatBotKit MCP Documentation](https://chatbotkit.com/docs/integrations/mcp) +- [Model Context Protocol](https://modelcontextprotocol.io) +- [ChatBotKit Skillsets Documentation](https://chatbotkit.com/docs/resources/skillsets) +- [Blueprint Reference Architecture Examples](https://chatbotkit.com/blueprints) diff --git a/examples/mcp-factory/main.tf b/examples/mcp-factory/main.tf new file mode 100644 index 0000000..fc11ee6 --- /dev/null +++ b/examples/mcp-factory/main.tf @@ -0,0 +1,195 @@ +# MCP Factory Reference Architectures +# +# This example demonstrates a factory-style architecture for MCP servers that +# expose multiple skillsets and abilities through separate MCP server integrations. +# Each skillset is designed to encapsulate specific functionalities, allowing for +# modular and organized management of AI capabilities. +# +# Architecture highlights: +# - Multiple skillsets, each with dedicated abilities +# - Separate MCP server integration for each skillset +# - Modular, factory-style organization +# - Clear separation of concerns +# +# Prerequisites: +# - Set the CHATBOTKIT_API_KEY environment variable + +terraform { + required_providers { + chatbotkit = { + source = "chatbotkit/chatbotkit" + } + } +} + +provider "chatbotkit" { + # api_key = "..." # Or set CHATBOTKIT_API_KEY env var +} + +# ============================================================================ +# Service 1: Data Analytics +# ============================================================================ +# First skillset with data analytics capabilities + +resource "chatbotkit_skillset" "analytics_service" { + name = "Analytics Service" + description = "Data analytics and reporting capabilities" +} + +resource "chatbotkit_skillset_ability" "analytics_analyze" { + skillset_id = chatbotkit_skillset.analytics_service.id + name = "Analyze Data" + description = "Perform comprehensive data analysis" + instruction = <<-EOT + # Analytics logic here + # This is a placeholder for actual analytics implementation + EOT +} + +resource "chatbotkit_skillset_ability" "analytics_report" { + skillset_id = chatbotkit_skillset.analytics_service.id + name = "Generate Report" + description = "Create detailed analytics reports" + instruction = <<-EOT + # Report generation logic here + # This is a placeholder for actual reporting implementation + EOT +} + +resource "chatbotkit_mcp_server_integration" "analytics_mcp" { + skillset_id = chatbotkit_skillset.analytics_service.id + name = "Analytics MCP Server" + description = "MCP server exposing analytics capabilities" +} + +# ============================================================================ +# Service 2: Content Management +# ============================================================================ +# Second skillset with content management capabilities + +resource "chatbotkit_skillset" "content_service" { + name = "Content Service" + description = "Content creation and management capabilities" +} + +resource "chatbotkit_skillset_ability" "content_create" { + skillset_id = chatbotkit_skillset.content_service.id + name = "Create Content" + description = "Generate new content based on specifications" + instruction = <<-EOT + # Content creation logic here + # This is a placeholder for actual content creation implementation + EOT +} + +resource "chatbotkit_skillset_ability" "content_edit" { + skillset_id = chatbotkit_skillset.content_service.id + name = "Edit Content" + description = "Modify and refine existing content" + instruction = <<-EOT + # Content editing logic here + # This is a placeholder for actual editing implementation + EOT +} + +resource "chatbotkit_mcp_server_integration" "content_mcp" { + skillset_id = chatbotkit_skillset.content_service.id + name = "Content MCP Server" + description = "MCP server exposing content management capabilities" +} + +# ============================================================================ +# Service 3: Research +# ============================================================================ +# Third skillset with research capabilities + +resource "chatbotkit_skillset" "research_service" { + name = "Research Service" + description = "Research and information gathering capabilities" +} + +resource "chatbotkit_skillset_ability" "research_search" { + skillset_id = chatbotkit_skillset.research_service.id + name = "Search Information" + description = "Search for relevant information on topics" + instruction = <<-EOT + # Research search logic here + # This is a placeholder for actual search implementation + EOT +} + +resource "chatbotkit_skillset_ability" "research_summarize" { + skillset_id = chatbotkit_skillset.research_service.id + name = "Summarize Findings" + description = "Create concise summaries of research findings" + instruction = <<-EOT + # Summarization logic here + # This is a placeholder for actual summarization implementation + EOT +} + +resource "chatbotkit_mcp_server_integration" "research_mcp" { + skillset_id = chatbotkit_skillset.research_service.id + name = "Research MCP Server" + description = "MCP server exposing research capabilities" +} + +# ============================================================================ +# Service 4: Task Management +# ============================================================================ +# Fourth skillset with task management capabilities + +resource "chatbotkit_skillset" "tasks_service" { + name = "Task Management Service" + description = "Task planning and execution capabilities" +} + +resource "chatbotkit_skillset_ability" "tasks_plan" { + skillset_id = chatbotkit_skillset.tasks_service.id + name = "Plan Tasks" + description = "Create structured task plans" + instruction = <<-EOT + # Task planning logic here + # This is a placeholder for actual planning implementation + EOT +} + +resource "chatbotkit_skillset_ability" "tasks_track" { + skillset_id = chatbotkit_skillset.tasks_service.id + name = "Track Progress" + description = "Monitor and report on task progress" + instruction = <<-EOT + # Progress tracking logic here + # This is a placeholder for actual tracking implementation + EOT +} + +resource "chatbotkit_mcp_server_integration" "tasks_mcp" { + skillset_id = chatbotkit_skillset.tasks_service.id + name = "Tasks MCP Server" + description = "MCP server exposing task management capabilities" +} + +# ============================================================================ +# Outputs +# ============================================================================ + +output "mcp_server_urls" { + description = "URLs for all MCP server integrations" + value = { + analytics = "Use the MCP server URL from the ChatBotKit dashboard for: ${chatbotkit_mcp_server_integration.analytics_mcp.name}" + content = "Use the MCP server URL from the ChatBotKit dashboard for: ${chatbotkit_mcp_server_integration.content_mcp.name}" + research = "Use the MCP server URL from the ChatBotKit dashboard for: ${chatbotkit_mcp_server_integration.research_mcp.name}" + tasks = "Use the MCP server URL from the ChatBotKit dashboard for: ${chatbotkit_mcp_server_integration.tasks_mcp.name}" + } +} + +output "skillset_ids" { + description = "IDs of all skillsets" + value = { + analytics = chatbotkit_skillset.analytics_service.id + content = chatbotkit_skillset.content_service.id + research = chatbotkit_skillset.research_service.id + tasks = chatbotkit_skillset.tasks_service.id + } +} diff --git a/examples/simple-self-improving-agent/README.md b/examples/simple-self-improving-agent/README.md new file mode 100644 index 0000000..c5450a7 --- /dev/null +++ b/examples/simple-self-improving-agent/README.md @@ -0,0 +1,172 @@ +# Simple Self-improving Agent Reference Architecture + +This example demonstrates a reference architecture for a self-improving AI agent that continuously learns from its interactions and experiences. + +## Overview + +This blueprint outlines a reference architecture for a self-improving AI agent designed to continuously learn from its interactions and experiences. By leveraging a combination of file-based resources and specialized abilities, the agent is equipped to read and update its backstory dynamically, allowing it to evolve over time based on new insights and lessons learned. + +## Architecture + +``` +┌──────────────────────────────────────────────────────────┐ +│ Self-improving Agent │ +│ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ Self-improvement Skillset │ │ +│ │ ┌──────────────────┐ ┌──────────────────┐ │ │ +│ │ │ Read Backstory │ │ Write Backstory │ │ │ +│ │ └────────┬─────────┘ └────────┬─────────┘ │ │ +│ └───────────┼─────────────────────┼──────────────────┘ │ +│ │ │ │ +│ └─────────┬───────────┘ │ +│ │ │ +│ ┌───────▼──────┐ │ +│ │ Backstory │ │ +│ │ File Resource│ │ +│ └──────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────┘ +``` + +## Key Features + +1. **Dynamic Backstory Management**: The agent can read its current backstory to understand its identity and guidelines +2. **Self-Modification**: The agent can update its own backstory based on learned experiences +3. **Continuous Learning**: File-based storage allows for persistent improvements across conversations +4. **Structured Identity**: Backstory follows a clear framework defining identity, capabilities, and behavioral guidelines + +## Core Abilities + +### Read Backstory +Reads and displays the complete contents of the current backstory. This allows the agent to: +- Understand its current identity and guidelines +- Review learned lessons and improvements +- Ensure consistency with its defined behavior + +### Write Backstory +Replaces the current backstory with updated content. This enables the agent to: +- Incorporate new insights and lessons learned +- Adapt to evolving requirements +- Improve performance based on feedback + +## Backstory Structure + +The backstory file follows a comprehensive framework: + +1. **Primary Identity Section**: Defines the agent's role, communication style, and core objectives +2. **Capability Sections**: Documents tool usage, content creation standards, and research protocols +3. **Behavioral Guidelines**: Outlines user interaction patterns and safety compliance +4. **Quality Checklist**: Ensures consistent response quality + +## Usage + +1. Set your ChatBotKit API key: +```bash +export CHATBOTKIT_API_KEY="your-api-key" +``` + +2. Initialize Terraform: +```bash +terraform init +``` + +3. Review the planned changes: +```bash +terraform plan +``` + +4. Apply the configuration: +```bash +terraform apply +``` + +5. Test the agent by asking it to: + - Read its current backstory + - Reflect on interactions and identify improvements + - Update its backstory with learned insights + +## How Self-Improvement Works + +The self-improvement cycle follows this pattern: + +1. **Interaction**: The agent interacts with users and encounters new scenarios +2. **Reflection**: The agent reviews its performance and identifies areas for improvement +3. **Learning**: The agent reads its current backstory to understand its baseline +4. **Adaptation**: The agent updates its backstory with new insights, lessons, or refined guidelines +5. **Evolution**: Future interactions benefit from the improved backstory + +## Example Self-Improvement Scenario + +**User Request**: "Help me with a complex data analysis task" + +**Agent Actions**: +1. Attempts the task with current capabilities +2. Identifies gaps or challenges in approach +3. Reads current backstory to review data analysis guidelines +4. Updates backstory with improved data analysis protocols +5. Applies enhanced approach to future data analysis requests + +## Customization + +### Extending the Backstory Framework + +Add new sections to the backstory to cover specific domains: + +``` +## Domain-Specific Expertise + +### Data Analysis +- Statistical methods and best practices +- Data visualization techniques +- Common pitfalls and how to avoid them + +### Technical Writing +- Documentation standards +- Code example formatting +- API documentation patterns +``` + +### Adding Reflection Abilities + +Create additional abilities for structured reflection: + +```hcl +resource "chatbotkit_skillset_ability" "reflect_on_interaction" { + skillset_id = chatbotkit_skillset.self_improvement.id + name = "Reflect on Interaction" + description = "Analyze recent interactions and identify improvement opportunities" + instruction = <<-EOT + # Custom reflection logic here + EOT +} +``` + +## When to Use This Pattern + +This pattern is ideal when: +- You want agents that continuously improve from experience +- Domain knowledge needs to evolve based on real-world usage +- You need persistent learning across conversation sessions +- Adaptability and continuous refinement are priorities + +## Important Considerations + +1. **Validation**: Implement safeguards to ensure backstory updates maintain quality standards +2. **Versioning**: Consider tracking backstory versions for rollback if needed +3. **Review**: Periodically review backstory changes to ensure they align with intended behavior +4. **Safety**: Ensure self-modifications don't violate safety or ethical guidelines + +## Cleanup + +To destroy all created resources: +```bash +terraform destroy +``` + +## Learn More + +- [ChatBotKit Files Documentation](https://chatbotkit.com/docs/resources/files) +- [ChatBotKit Skillsets Documentation](https://chatbotkit.com/docs/resources/skillsets) +- [ChatBotKit Abilities Documentation](https://chatbotkit.com/docs/resources/abilities) +- [Blueprint Reference Architecture Examples](https://chatbotkit.com/blueprints) diff --git a/examples/simple-self-improving-agent/main.tf b/examples/simple-self-improving-agent/main.tf new file mode 100644 index 0000000..cf1c328 --- /dev/null +++ b/examples/simple-self-improving-agent/main.tf @@ -0,0 +1,198 @@ +# Simple Self-improving Agent Reference Architecture +# +# This example demonstrates a reference architecture for a self-improving AI agent +# that continuously learns from its interactions and experiences by reading and +# updating its own backstory file. +# +# Architecture highlights: +# - Bot with self-improvement capabilities +# - Backstory stored in a file resource +# - Read and write abilities for backstory management +# - Continuous learning and adaptation +# +# Prerequisites: +# - Set the CHATBOTKIT_API_KEY environment variable + +terraform { + required_providers { + chatbotkit = { + source = "chatbotkit/chatbotkit" + } + } +} + +provider "chatbotkit" { + # api_key = "..." # Or set CHATBOTKIT_API_KEY env var +} + +# ============================================================================ +# Backstory File +# ============================================================================ +# Stores the agent's backstory which can be read and updated dynamically + +resource "chatbotkit_file" "backstory" { + name = "Backstory" + description = "Incorporates narrative backstory elements that enrich the overall context." +} + +# ============================================================================ +# Self-improvement Skillset +# ============================================================================ +# Contains abilities for reading and updating the agent's backstory + +resource "chatbotkit_skillset" "self_improvement" { + name = "Self-improvement Skills" + description = <<-EOT + A collection of essential skills designed to foster continuous AI self-improvement. + + Use the available functions to retrieve and record lessons learned and other important + information that could be contextually relevant for this conversation. + EOT +} + +# ============================================================================ +# Self-improvement Abilities +# ============================================================================ +# Abilities that enable the agent to read and update its own backstory + +resource "chatbotkit_skillset_ability" "read_backstory" { + skillset_id = chatbotkit_skillset.self_improvement.id + file_id = chatbotkit_file.backstory.id + name = "Read Backstory" + description = "Reads and displays the complete contents of the current backstory." + instruction = <<-EOT + template: file/read + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "write_backstory" { + skillset_id = chatbotkit_skillset.self_improvement.id + file_id = chatbotkit_file.backstory.id + name = "Write Backstory" + description = "A function to replace the current backstory with updated content." + instruction = <<-EOT + template: file/write + parameters: {} + EOT +} + +# ============================================================================ +# Self-improving Agent Bot +# ============================================================================ +# The agent bot that can read and update its own backstory to continuously improve + +resource "chatbotkit_bot" "agent" { + name = "Self-improving Agent" + description = "A self-improving AI agent that continuously learns from interactions to enhance its performance." + backstory = <<-EOT + # PRIMARY IDENTITY SECTION + + You are a versatile AI assistant designed to help users accomplish a wide variety of tasks + through natural conversation. Your role is to be a knowledgeable, helpful, and reliable + companion that can adapt to different user needs while maintaining consistent quality and + safety standards. + + **Communication Style**: Maintain a friendly, professional, and approachable tone. Be clear + and concise while providing comprehensive assistance. Adapt your communication level to match + the user's expertise and preferences. + + **Primary Objectives**: + - Provide accurate, helpful, and timely assistance across diverse topics and tasks + - Ensure user safety and maintain ethical standards in all interactions + - Deliver well-formatted, easy-to-understand responses using markdown formatting + - Continuously learn from context to provide increasingly relevant assistance + + **Core Constraints**: Always prioritize user safety, respect privacy, maintain accuracy, and + operate within ethical boundaries while being maximally helpful. + + # CAPABILITY SECTIONS + + ## Tool Usage Guidelines + + You have access to various tools and capabilities that enable you to provide comprehensive + assistance including search and information retrieval, data processing, content creation, + and problem-solving. + + **Usage Conditions**: + - Use tools proactively when they will improve response quality or accuracy + - Always verify information from multiple sources when possible + - Prioritize authoritative and recent sources + - Clearly indicate when information is uncertain or requires verification + + ## Content Creation Standards + + **Document Formatting**: Use standard markdown formatting exclusively including headers, + bold and italic text, lists, tables, links, and code formatting. + + **Citation Requirements**: Always cite sources using footnotes, inline references, or + reference lists. Include publication dates and author information when available. + + **Quality Standards**: Ensure all content is accurate, relevant, and up-to-date. Structure + information logically with clear headings and sections. + + ## Search and Research Protocols + + **When to Search**: Current events, recent developments, specific facts, technical + specifications, or verification of potentially outdated information. + + **Information Validation**: Cross-reference information across multiple reliable sources. + Prioritize authoritative sources and verify publication dates. + + # BEHAVIORAL GUIDELINES + + ## User Interaction + + **Response Patterns**: Begin with clear acknowledgment, provide structured information, + include relevant context, and end with actionable next steps when appropriate. + + **Question Handling**: Ask clarifying questions when requests are ambiguous, break down + complex requests, and provide comprehensive answers that anticipate related questions. + + **Conversation Management**: Maintain context throughout the conversation, reference + previous interactions appropriately, and adapt based on user feedback. + + ## Safety and Compliance + + **Content Restrictions**: Never provide information that could cause harm, illegal activity, + or dangerous behavior. Refuse requests for personal information about individuals. + + **Privacy Protection**: Never request or store personal identifying information. Respect + user privacy and confidentiality in all interactions. + + **Ethical Guidelines**: Maintain objectivity, acknowledge limitations, and respect + intellectual property rights. + + # QUALITY CHECKLIST + + Before providing any response, verify: + - [ ] Response directly addresses the user's request + - [ ] Information is accurate and properly researched + - [ ] All sources are properly cited + - [ ] Content uses proper markdown formatting + - [ ] Safety and ethical guidelines are followed + - [ ] Content is well-structured and organized + EOT + model = "claude-4.5-sonnet" + + skillset_id = chatbotkit_skillset.self_improvement.id +} + +# ============================================================================ +# Outputs +# ============================================================================ + +output "bot_id" { + description = "The ID of the self-improving agent" + value = chatbotkit_bot.agent.id +} + +output "skillset_id" { + description = "The ID of the self-improvement skillset" + value = chatbotkit_skillset.self_improvement.id +} + +output "backstory_file_id" { + description = "The ID of the backstory file" + value = chatbotkit_file.backstory.id +}