diff --git a/.goreleaser.yml b/.goreleaser.yml index 7936625..1ee3739 100644 --- a/.goreleaser.yml +++ b/.goreleaser.yml @@ -8,11 +8,11 @@ before: builds: - env: - CGO_ENABLED=0 - mod_timestamp: "{{ .CommitTimestamp }}" + mod_timestamp: '{{ .CommitTimestamp }}' flags: - -trimpath ldflags: - - "-s -w -X main.version={{.Version}}" + - '-s -w -X main.version={{.Version}}' goos: - freebsd - windows @@ -20,12 +20,12 @@ builds: - darwin goarch: - amd64 - - "386" + - '386' - arm - arm64 ignore: - goos: darwin - goarch: "386" + goarch: '386' - goos: windows goarch: arm - goos: windows @@ -34,38 +34,38 @@ builds: goarch: arm - goos: freebsd goarch: arm64 - binary: "{{ .ProjectName }}_v{{ .Version }}" + binary: '{{ .ProjectName }}_v{{ .Version }}' archives: - format: zip - name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}" + name_template: '{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}' checksum: - name_template: "{{ .ProjectName }}_{{ .Version }}_SHA256SUMS" + name_template: '{{ .ProjectName }}_{{ .Version }}_SHA256SUMS' algorithm: sha256 signs: - artifacts: checksum args: - - "--batch" - - "--local-user" - - "{{ .Env.GPG_FINGERPRINT }}" - - "--output" - - "${signature}" - - "--detach-sign" - - "${artifact}" + - '--batch' + - '--local-user' + - '{{ .Env.GPG_FINGERPRINT }}' + - '--output' + - '${signature}' + - '--detach-sign' + - '${artifact}' release: - draft: true - name_template: "v{{ .Version }}" + draft: false + name_template: 'v{{ .Version }}' changelog: sort: asc filters: exclude: - - "^docs:" - - "^test:" - - "^ci:" - - "^chore:" + - '^docs:' + - '^test:' + - '^ci:' + - '^chore:' - Merge pull request - Merge branch diff --git a/examples/README.md b/examples/README.md index cc433bf..0c1deeb 100644 --- a/examples/README.md +++ b/examples/README.md @@ -17,6 +17,10 @@ These examples demonstrate production-ready architectures based on ChatBotKit bl | Example | Description | Key Features | |---------|-------------|--------------| +| [dual-agent-programmable-workflows](./dual-agent-programmable-workflows/) | Two-agent architecture for workflow programming and execution | Multi-agent collaboration, Shared resources, Asymmetric access patterns, Scheduled triggers | +| [system-diagnostics-agent](./system-diagnostics-agent/) | Self-monitoring agent that reports on its own capabilities | Self-introspection, Blueprint resource discovery, Scheduled diagnostics, Automated reporting | +| [second-brain](./second-brain/) | Personal knowledge management system with Notion and Calendar | Persistent workspace, Notion integration, Google Calendar, Telegram bot, Dynamic skillsets | +| [workflow-orchestrator](./workflow-orchestrator/) | Multi-step workflow execution with comprehensive tracing | Dynamic skillset loading, Multiple specialized skillsets, State persistence, Execution tracing | | [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 | | [simple-self-improving-agent](./simple-self-improving-agent/) | Self-improving agent that learns from interactions | Backstory file management, Read/Write abilities, Continuous learning | @@ -91,6 +95,56 @@ Demonstrates a full-featured AI assistant with knowledge base and web capabiliti **Use when:** You need a comprehensive reference or want to build a feature-rich assistant. +### Dual-Agent Programmable Workflows Example +Two-agent architecture where a Workflow Architect programs custom scripts and a Task Runner executes them. + +**What you'll learn:** +- Multi-agent collaboration patterns +- Shared file and space resources +- Asymmetric access control (architect writes, runner reads) +- Scheduled workflow execution +- Separation of concerns in agent design + +**Use when:** Building systems where design and execution should be separate, or when you need maintainable automation frameworks. + +### System Diagnostics Agent Example +Self-monitoring agent that introspects its own capabilities and produces diagnostic reports. + +**What you'll learn:** +- Self-introspection using blueprint resource discovery +- Scheduled automated diagnostics +- Persistent diagnostic log storage +- Health monitoring patterns +- Agent self-documentation + +**Use when:** Building production AI systems that need continuous monitoring and health checks. + +### Second Brain Example +Personal knowledge management system integrating Notion, Google Calendar, and Telegram. + +**What you'll learn:** +- Personal knowledge management architecture +- Notion integration for notes and databases +- Google Calendar integration for time awareness +- Telegram bot for mobile access +- Template-based OAuth2 secrets +- Multi-skillset organization + +**Use when:** Building personal productivity assistants or knowledge management systems. + +### Workflow Orchestrator Example +Multi-step workflow execution engine with dynamic skillset loading and comprehensive tracing. + +**What you'll learn:** +- Complex multi-step workflow patterns +- Dynamic skillset loading for modular capabilities +- Workflow state persistence +- Comprehensive execution tracing +- Multiple specialized skillsets (Data, Control, Reporting) +- Audit trail generation + +**Use when:** Building sophisticated automation workflows that require state management and full traceability. + ### Skillset-based Dynamic Skill Example Shows how to build agents that can discover and activate skills on-demand. diff --git a/examples/dual-agent-programmable-workflows/main.tf b/examples/dual-agent-programmable-workflows/main.tf new file mode 100644 index 0000000..97bebca --- /dev/null +++ b/examples/dual-agent-programmable-workflows/main.tf @@ -0,0 +1,277 @@ +# Dual-Agent Programmable Workflows +# +# This example demonstrates a two-agent architecture where one agent (Workflow Architect) +# programs custom scripts and automations, while another agent (Task Runner) executes +# them on demand. This showcases separation of concerns in AI agent design. +# +# Architecture highlights: +# - Two specialized bots with distinct roles (architect and runner) +# - Shared automation playbook file for documentation +# - Shared script workspace for script storage and execution +# - Asymmetric access: architect has read/write, runner has read-only +# - Scheduled trigger for automated task execution +# +# 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 +} + +# ============================================================================ +# Shared Resources +# ============================================================================ +# Resources shared between both agents + +resource "chatbotkit_file" "automation_playbook" { + name = "Automation Playbook" + description = "Central documentation containing all programmed scripts and execution instructions" +} + +resource "chatbotkit_space" "script_workspace" { + name = "Script Workspace" + description = "Shared environment where scripts are created, stored, and executed" +} + +# ============================================================================ +# Workflow Architect Bot +# ============================================================================ +# The architect programs scripts and maintains documentation + +resource "chatbotkit_bot" "architect" { + name = "Workflow Architect" + description = "Programs custom scripts, automations, and maintains the playbook documentation" + model = "claude-4.5-opus" + + backstory = <<-EOT + You are the Workflow Architect, a specialized AI agent responsible for + designing, programming, and documenting automation workflows. Your role + is to create powerful, reusable scripts and maintain comprehensive + documentation that enables seamless execution by the Task Runner. + + YOUR RESPONSIBILITIES: + + 1. SCRIPT DEVELOPMENT + - Create bash scripts for automation tasks + - Design multi-step workflows with clear dependencies + - Test scripts in your architect workspace before publishing + - Optimize scripts for reliability and efficiency + + 2. PLAYBOOK MAINTENANCE + - Document every script with clear usage instructions + - Include parameter descriptions and expected outputs + - Provide troubleshooting guidance for common issues + - Organize the playbook with clear sections and navigation + + 3. QUALITY ASSURANCE + - Ensure all scripts have error handling + - Document prerequisites and dependencies + - Include example invocations for each script + - Version your scripts with dates and change notes + + PLAYBOOK FORMAT: + + When writing to the Automation Playbook, use this structure: + + # Automation Playbook + Last updated: [date] + + ## Available Scripts + + ### [Script Name] + **Purpose**: What this script does + **Usage**: How to run it + **Parameters**: Input requirements + **Output**: What to expect + **Example**: Sample invocation + **Troubleshooting**: Common issues and solutions + + --- + + Always write complete, production-ready scripts. The Task Runner + depends entirely on your documentation—be thorough and precise. + Never assume the runner knows anything beyond what's in the playbook. + + The current date is $${EARTH_DATE}. Include timestamps in all updates. + EOT + + skillset_id = chatbotkit_skillset.architect_toolkit.id +} + +# ============================================================================ +# Architect Skillset and Abilities +# ============================================================================ +# Tools for the architect to develop and document scripts + +resource "chatbotkit_skillset" "architect_toolkit" { + name = "Architect Toolkit" + description = "Tools for script development and playbook management" +} + +resource "chatbotkit_skillset_ability" "architect_playbook" { + skillset_id = chatbotkit_skillset.architect_toolkit.id + file_id = chatbotkit_file.automation_playbook.id + name = "Read/Write Playbook" + description = "Read or update the Automation Playbook with scripts and documentation" + instruction = <<-EOT + template: file/rw + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "architect_bash" { + skillset_id = chatbotkit_skillset.architect_toolkit.id + space_id = chatbotkit_space.script_workspace.id + name = "Bash" + description = "Execute bash commands in the script workspace" + instruction = <<-EOT + template: shell/exec + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "architect_script_rw" { + skillset_id = chatbotkit_skillset.architect_toolkit.id + space_id = chatbotkit_space.script_workspace.id + name = "Read/Write Script" + description = "Read or write script files in the shared workspace" + instruction = <<-EOT + template: shell/rw + parameters: {} + EOT +} + +# ============================================================================ +# Task Runner Bot +# ============================================================================ +# The runner executes scripts according to the playbook + +resource "chatbotkit_bot" "runner" { + name = "Task Runner" + description = "Executes programmed workflows by reading the playbook and running scripts" + model = "claude-4.5-sonnet" + + backstory = <<-EOT + You are the Task Runner, a specialized AI agent responsible for + executing automation workflows. Your role is to read the Automation + Playbook, understand available scripts, and execute them precisely + according to the documented instructions. + + YOUR RESPONSIBILITIES: + + 1. PLAYBOOK CONSULTATION + - Always read the Automation Playbook before executing tasks + - Understand the available scripts and their purposes + - Follow documented instructions exactly as written + - Check for any updates or new scripts regularly + + 2. TASK EXECUTION + - Run scripts in the Runtime Workspace + - Provide required parameters as documented + - Capture and report execution output + - Handle errors according to troubleshooting guidance + + 3. EXECUTION DISCIPLINE + - Never modify scripts—only execute them + - Follow the exact syntax and parameters specified + - Report any issues encountered during execution + - Log execution results for tracking + + EXECUTION WORKFLOW: + + 1. Receive a task request (user message or trigger) + 2. Read the Automation Playbook to find relevant scripts + 3. Identify the correct script and its parameters + 4. Execute the script in the Runtime Workspace + 5. Report the results back clearly + + IMPORTANT CONSTRAINTS: + + - You can ONLY READ the Automation Playbook, not modify it + - Always consult the playbook before executing—never guess + - If a script doesn't exist for a task, inform the user + - If documentation is unclear, report the issue rather than improvise + + The current date is $${EARTH_DATE}. Log all execution timestamps. + EOT + + skillset_id = chatbotkit_skillset.runner_toolkit.id +} + +# ============================================================================ +# Runner Skillset and Abilities +# ============================================================================ +# Tools for the runner to read playbook and execute scripts + +resource "chatbotkit_skillset" "runner_toolkit" { + name = "Runner Toolkit" + description = "Tools for playbook reading and script execution" +} + +resource "chatbotkit_skillset_ability" "runner_read_playbook" { + skillset_id = chatbotkit_skillset.runner_toolkit.id + file_id = chatbotkit_file.automation_playbook.id + name = "Read Playbook" + description = "Read the Automation Playbook to find scripts and execution instructions" + instruction = <<-EOT + template: file/read + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "runner_bash" { + skillset_id = chatbotkit_skillset.runner_toolkit.id + space_id = chatbotkit_space.script_workspace.id + name = "Bash" + description = "Execute bash commands in the shared workspace to run scripts" + instruction = <<-EOT + template: shell/exec + parameters: {} + EOT +} + +# ============================================================================ +# Trigger Integration +# ============================================================================ +# Automated trigger for scheduled workflow execution + +resource "chatbotkit_trigger_integration" "scheduled_trigger" { + bot_id = chatbotkit_bot.runner.id + name = "Scheduled Task Trigger" + description = "Automated trigger for scheduled workflow execution by the Task Runner" + authenticate = true + session_duration = 1800000 + trigger_schedule = "hourly" +} + +# ============================================================================ +# Outputs +# ============================================================================ + +output "architect_bot_id" { + description = "The ID of the Workflow Architect bot" + value = chatbotkit_bot.architect.id +} + +output "runner_bot_id" { + description = "The ID of the Task Runner bot" + value = chatbotkit_bot.runner.id +} + +output "automation_playbook_id" { + description = "The ID of the shared Automation Playbook file" + value = chatbotkit_file.automation_playbook.id +} + +output "script_workspace_id" { + description = "The ID of the shared Script Workspace" + value = chatbotkit_space.script_workspace.id +} diff --git a/examples/second-brain/main.tf b/examples/second-brain/main.tf new file mode 100644 index 0000000..1eaccef --- /dev/null +++ b/examples/second-brain/main.tf @@ -0,0 +1,306 @@ +# Second Brain +# +# This example demonstrates an AI-powered personal knowledge management and +# productivity system inspired by Tiago Forte's "Building a Second Brain" +# methodology. The system integrates with Notion and Google Calendar. +# +# Architecture highlights: +# - Bot with persistent workspace for storing knowledge +# - Shell execution for managing workspace files +# - Dynamic skillset discovery and loading +# - Notion integration for knowledge management +# - Google Calendar integration for time awareness +# - Telegram integration for mobile access +# +# Prerequisites: +# - Set the CHATBOTKIT_API_KEY environment variable +# - Configure Notion OAuth2 (platform secret: notion) +# - Configure Google Calendar OAuth2 (platform secret: google/calendar) +# - Configure Telegram bot token for the integration + +terraform { + required_providers { + chatbotkit = { + source = "chatbotkit/chatbotkit" + } + } +} + +provider "chatbotkit" { + # api_key = "..." # Or set CHATBOTKIT_API_KEY env var +} + +# ============================================================================ +# Workspace +# ============================================================================ +# Persistent workspace for the second brain + +resource "chatbotkit_space" "mind" { + name = "Mind" + description = "The persistent workspace for the second brain" +} + +# ============================================================================ +# Secrets +# ============================================================================ +# OAuth2 secrets for Notion and Google Calendar + +resource "chatbotkit_secret" "notion" { + name = "Notion API Key" + description = "The API key for accessing Notion." + type = "template" + kind = "personal" + + config = jsonencode({ + template = "platform/notion" + }) +} + +resource "chatbotkit_secret" "google_calendar" { + name = "Google Calendar" + description = "Connect to Google Calendar to manage your events and schedules." + type = "template" + kind = "personal" + + config = jsonencode({ + template = "platform/google/calendar" + }) +} + +# ============================================================================ +# Core Skillset +# ============================================================================ +# Core second brain capabilities + +resource "chatbotkit_skillset" "core_skills" { + name = "Core Skills" + description = "Core second brain capabilities including shell access and skillset management" +} + +resource "chatbotkit_skillset_ability" "shell_exec" { + skillset_id = chatbotkit_skillset.core_skills.id + space_id = chatbotkit_space.mind.id + name = "Execute Shell Command" + description = "Execute shell commands to list and read skills from the brain workspace" + instruction = <<-EOT + template: shell/exec + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "list_skillsets" { + skillset_id = chatbotkit_skillset.core_skills.id + name = "List Available Skillsets" + description = "Discover all available skillsets that can be installed" + instruction = <<-EOT + template: blueprint/resource/list + parameters: + type: skillset + EOT +} + +resource "chatbotkit_skillset_ability" "install_skillset" { + skillset_id = chatbotkit_skillset.core_skills.id + name = "Install Skillset" + description = "Bring a skillset into context by its ID to access its abilities" + instruction = <<-EOT + template: conversation/skillset/install[by-id] + parameters: {} + EOT +} + +# ============================================================================ +# Knowledge Management Skillset +# ============================================================================ +# Notion integration for knowledge management + +resource "chatbotkit_skillset" "knowledge_management" { + name = "Knowledge Management" + description = "Notion integration for capturing and organizing knowledge" +} + +resource "chatbotkit_skillset_ability" "notion_search" { + skillset_id = chatbotkit_skillset.knowledge_management.id + secret_id = chatbotkit_secret.notion.id + name = "Search Notion" + description = "Search all of Notion for specific keywords" + instruction = <<-EOT + template: notion/search + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "notion_list_pages" { + skillset_id = chatbotkit_skillset.knowledge_management.id + secret_id = chatbotkit_secret.notion.id + name = "List Notion Pages" + description = "List all accessible pages in Notion" + instruction = <<-EOT + template: notion/page/list + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "notion_fetch_page" { + skillset_id = chatbotkit_skillset.knowledge_management.id + secret_id = chatbotkit_secret.notion.id + name = "Fetch Notion Page" + description = "Fetch the content of a specific Notion page" + instruction = <<-EOT + template: notion/page/fetch + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "notion_create_item" { + skillset_id = chatbotkit_skillset.knowledge_management.id + secret_id = chatbotkit_secret.notion.id + name = "Create Notion Database Item" + description = "Create a new item in a Notion database" + instruction = <<-EOT + template: notion/database/item/create + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "notion_update_item" { + skillset_id = chatbotkit_skillset.knowledge_management.id + secret_id = chatbotkit_secret.notion.id + name = "Update Notion Database Item" + description = "Update an existing item in a Notion database" + instruction = <<-EOT + template: notion/database/item/update + parameters: {} + EOT +} + +# ============================================================================ +# Time Management Skillset +# ============================================================================ +# Google Calendar integration for time awareness + +resource "chatbotkit_skillset" "time_management" { + name = "Time Management" + description = "Google Calendar integration for time awareness and scheduling" +} + +resource "chatbotkit_skillset_ability" "calendar_list" { + skillset_id = chatbotkit_skillset.time_management.id + secret_id = chatbotkit_secret.google_calendar.id + name = "List Google Calendars" + description = "List all available Google Calendars" + instruction = <<-EOT + template: google/calendar/list + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "calendar_events" { + skillset_id = chatbotkit_skillset.time_management.id + secret_id = chatbotkit_secret.google_calendar.id + name = "List Calendar Events" + description = "List upcoming events from a specific Google Calendar" + instruction = <<-EOT + template: google/calendar/event/list + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "calendar_availability" { + skillset_id = chatbotkit_skillset.time_management.id + secret_id = chatbotkit_secret.google_calendar.id + name = "Check Availability" + description = "Check availability in Google Calendar" + instruction = <<-EOT + template: google/calendar/availability/list + parameters: {} + EOT +} + +# ============================================================================ +# Second Brain Bot +# ============================================================================ +# The main AI-powered personal knowledge management system + +resource "chatbotkit_bot" "second_brain" { + name = "Second Brain" + description = "Your AI-powered personal knowledge management system" + model = "claude-4.5-sonnet" + + backstory = <<-EOT + You are a Second Brain—an AI-powered personal knowledge management + system designed to help your user capture, organize, and surface + knowledge effectively. Your role is to function as an external + cognitive extension that enhances thinking, memory, and productivity. + + You have access to a persistent workspace (your "brain") where you + can store skills, notes, and learned patterns. Use the shell ability + to manage files in your workspace and build your own library of + reusable knowledge. + + You integrate with Notion for knowledge management and Google Calendar + for time awareness. Help your user organize information, make + connections between ideas, and surface relevant knowledge when needed. + + Your communication style should be helpful, insightful, and proactive. + Suggest connections, offer to organize information, and help your user + think more clearly by offloading cognitive load to you. + EOT + + skillset_id = chatbotkit_skillset.core_skills.id +} + +# ============================================================================ +# Telegram Integration +# ============================================================================ +# Enable mobile access via Telegram + +resource "chatbotkit_telegram_integration" "second_brain_bot" { + bot_id = chatbotkit_bot.second_brain.id + name = "Second Brain Bot" + description = "Access your second brain from Telegram" + bot_token = var.telegram_bot_token + contact_collection = false + session_duration = 0 + attachments = false +} + +# ============================================================================ +# Variables +# ============================================================================ + +variable "telegram_bot_token" { + description = "The Telegram bot token for the integration" + type = string + sensitive = true + default = "" +} + +# ============================================================================ +# Outputs +# ============================================================================ + +output "bot_id" { + description = "The ID of the second brain bot" + value = chatbotkit_bot.second_brain.id +} + +output "core_skillset_id" { + description = "The ID of the core skillset" + value = chatbotkit_skillset.core_skills.id +} + +output "knowledge_skillset_id" { + description = "The ID of the knowledge management skillset" + value = chatbotkit_skillset.knowledge_management.id +} + +output "time_skillset_id" { + description = "The ID of the time management skillset" + value = chatbotkit_skillset.time_management.id +} + +output "workspace_id" { + description = "The ID of the mind workspace" + value = chatbotkit_space.mind.id +} diff --git a/examples/system-diagnostics-agent/main.tf b/examples/system-diagnostics-agent/main.tf new file mode 100644 index 0000000..c11c424 --- /dev/null +++ b/examples/system-diagnostics-agent/main.tf @@ -0,0 +1,169 @@ +# System Diagnostics Agent +# +# This example demonstrates a self-monitoring AI agent that tests and reports on +# its own capabilities, producing diagnostic logs about available skillsets, +# abilities, and system health. +# +# Architecture highlights: +# - Bot with self-introspection capabilities +# - Blueprint resource list ability for discovering skillsets +# - Space for persistent diagnostic log storage +# - Shell execution abilities for file operations +# - Scheduled trigger for automated diagnostics +# +# 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 +} + +# ============================================================================ +# Diagnostic Workspace +# ============================================================================ +# Persistent storage for diagnostic reports and logs + +resource "chatbotkit_space" "diagnostic_workspace" { + name = "Diagnostic Workspace" + description = "Persistent storage for diagnostic reports and logs" +} + +# ============================================================================ +# Diagnostics Skillset +# ============================================================================ +# Core diagnostic abilities for system introspection and reporting + +resource "chatbotkit_skillset" "diagnostics_core" { + name = "Diagnostics Core" + description = "Core diagnostic abilities for system introspection and reporting" +} + +# ============================================================================ +# Diagnostic Abilities +# ============================================================================ +# Abilities that enable the agent to introspect and report on itself + +resource "chatbotkit_skillset_ability" "list_skillsets" { + skillset_id = chatbotkit_skillset.diagnostics_core.id + name = "List Available Skillsets" + description = "Discover all available skillsets in this blueprint to catalog capabilities" + instruction = <<-EOT + template: blueprint/resource/list + parameters: + type: skillset + EOT +} + +resource "chatbotkit_skillset_ability" "shell_exec" { + skillset_id = chatbotkit_skillset.diagnostics_core.id + space_id = chatbotkit_space.diagnostic_workspace.id + name = "Execute Shell Command" + description = "Execute shell commands in the diagnostic workspace for file operations and system checks" + instruction = <<-EOT + template: shell/exec + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "shell_read" { + skillset_id = chatbotkit_skillset.diagnostics_core.id + space_id = chatbotkit_space.diagnostic_workspace.id + name = "Read File from Workspace" + description = "Read diagnostic reports or logs from the workspace" + instruction = <<-EOT + template: shell/read + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "shell_write" { + skillset_id = chatbotkit_skillset.diagnostics_core.id + space_id = chatbotkit_space.diagnostic_workspace.id + name = "Write File to Workspace" + description = "Write diagnostic reports and logs to the workspace" + instruction = <<-EOT + template: shell/write + parameters: {} + EOT +} + +# ============================================================================ +# System Diagnostics Agent Bot +# ============================================================================ +# The self-monitoring agent that produces diagnostic reports + +resource "chatbotkit_bot" "diagnostics_agent" { + name = "System Diagnostics Agent" + description = "A self-monitoring AI agent that tests and reports on its own capabilities" + model = "claude-4.5-sonnet" + + backstory = <<-EOT + You are a System Diagnostics Agent responsible for monitoring and + validating your own capabilities. Your role is to systematically test + your available skillsets and abilities, and produce detailed diagnostic + reports. + + DIAGNOSTIC WORKFLOW: + + 1. List all available skillsets using the blueprint resource discovery ability + 2. For each skillset, document its name, description, and purpose + 3. Identify any missing or unexpected skillsets + 4. Document the total count of abilities and their categories + 5. Write a comprehensive diagnostic report to your workspace + + Your diagnostic reports should be structured, timestamped, and include: + - Executive summary of system health + - Complete inventory of skillsets and abilities + - Any warnings or recommendations + - Timestamp and execution metadata + + Store all diagnostic reports in your workspace using the shell execution + ability. Create timestamped files in the format: diagnostics-YYYY-MM-DD-HH-MM.md + + The current date is $${EARTH_DATE}. Each diagnostic run should be thorough + and produce actionable insights about system configuration and health. + EOT + + skillset_id = chatbotkit_skillset.diagnostics_core.id +} + +# ============================================================================ +# Trigger Integration +# ============================================================================ +# Automated trigger for periodic system diagnostics + +resource "chatbotkit_trigger_integration" "diagnostic_schedule" { + bot_id = chatbotkit_bot.diagnostics_agent.id + name = "Diagnostic Schedule" + description = "Automated trigger for periodic system diagnostics and health checks" + authenticate = true + session_duration = 1800000 + trigger_schedule = "daily" +} + +# ============================================================================ +# Outputs +# ============================================================================ + +output "bot_id" { + description = "The ID of the system diagnostics agent" + value = chatbotkit_bot.diagnostics_agent.id +} + +output "skillset_id" { + description = "The ID of the diagnostics skillset" + value = chatbotkit_skillset.diagnostics_core.id +} + +output "workspace_id" { + description = "The ID of the diagnostic workspace" + value = chatbotkit_space.diagnostic_workspace.id +} diff --git a/examples/workflow-orchestrator/main.tf b/examples/workflow-orchestrator/main.tf new file mode 100644 index 0000000..20f451a --- /dev/null +++ b/examples/workflow-orchestrator/main.tf @@ -0,0 +1,314 @@ +# Workflow Orchestrator Agent +# +# This example demonstrates a sophisticated architecture for building complex, +# multi-step automation workflows with dynamic skillset loading, workflow state +# persistence, and comprehensive execution tracing. +# +# Architecture highlights: +# - Main bot with orchestration capabilities +# - Dynamic skillset discovery and installation +# - Three specialized workflow skillsets (Data, Control, Reporting) +# - Space for persistent workflow state and traces +# - Trigger integration for workflow execution +# +# 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 +} + +# ============================================================================ +# Workflow Workspace +# ============================================================================ +# Persistent storage for workflow state, traces, and execution artifacts + +resource "chatbotkit_space" "workflow_workspace" { + name = "Workflow Workspace" + description = "Persistent storage for workflow state, traces, and execution artifacts" +} + +# ============================================================================ +# Orchestration Core Skillset +# ============================================================================ +# Core orchestration capabilities including dynamic skillset loading + +resource "chatbotkit_skillset" "orchestration_core" { + name = "Orchestration Core" + description = "Core orchestration capabilities including dynamic skillset loading" +} + +resource "chatbotkit_skillset_ability" "list_skillsets" { + skillset_id = chatbotkit_skillset.orchestration_core.id + name = "List Available Skillsets" + description = "Discover all workflow skillsets available in this blueprint" + instruction = <<-EOT + template: blueprint/resource/list + parameters: + type: skillset + EOT +} + +resource "chatbotkit_skillset_ability" "install_skillset" { + skillset_id = chatbotkit_skillset.orchestration_core.id + name = "Install Skillset" + description = "Dynamically load a workflow skillset by its ID to access its capabilities" + instruction = <<-EOT + template: conversation/skillset/install[by-id] + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "shell_exec" { + skillset_id = chatbotkit_skillset.orchestration_core.id + space_id = chatbotkit_space.workflow_workspace.id + name = "Execute Workflow Command" + description = "Execute shell commands in the workflow workspace for state management and logging" + instruction = <<-EOT + template: shell/exec + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "shell_read" { + skillset_id = chatbotkit_skillset.orchestration_core.id + space_id = chatbotkit_space.workflow_workspace.id + name = "Read Workflow File" + description = "Read workflow state, logs, or configuration files from the workspace" + instruction = <<-EOT + template: shell/read + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "shell_write" { + skillset_id = chatbotkit_skillset.orchestration_core.id + space_id = chatbotkit_space.workflow_workspace.id + name = "Write Workflow File" + description = "Write workflow state, traces, or results to the workspace" + instruction = <<-EOT + template: shell/write + parameters: {} + EOT +} + +# ============================================================================ +# Data Processing Skillset +# ============================================================================ +# Workflow abilities for data transformation, validation, and quality checks + +resource "chatbotkit_skillset" "data_processing" { + name = "Data Processing" + description = "Workflow abilities for data transformation, validation, and quality checks" +} + +resource "chatbotkit_skillset_ability" "fetch_web_data" { + skillset_id = chatbotkit_skillset.data_processing.id + name = "Fetch Web Data" + description = "Retrieve data from web sources for workflow processing" + instruction = <<-EOT + template: fetch/text/get + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "search_web" { + skillset_id = chatbotkit_skillset.data_processing.id + name = "Search Web for Information" + description = "Search the web to gather data required by the workflow" + instruction = <<-EOT + template: search/web + parameters: {} + EOT +} + +# ============================================================================ +# Execution Control Skillset +# ============================================================================ +# Workflow abilities for state management, error handling, and flow control + +resource "chatbotkit_skillset" "execution_control" { + name = "Execution Control" + description = "Workflow abilities for state management, error handling, and flow control" +} + +resource "chatbotkit_skillset_ability" "control_script" { + skillset_id = chatbotkit_skillset.execution_control.id + space_id = chatbotkit_space.workflow_workspace.id + name = "Execute Control Script" + description = "Run workflow control scripts for state transitions and flow management" + instruction = <<-EOT + template: shell/exec + parameters: {} + EOT +} + +# ============================================================================ +# Reporting & Audit Skillset +# ============================================================================ +# Workflow abilities for generating reports, logs, and audit trails + +resource "chatbotkit_skillset" "reporting_audit" { + name = "Reporting & Audit" + description = "Workflow abilities for generating reports, logs, and audit trails" +} + +resource "chatbotkit_skillset_ability" "generate_report" { + skillset_id = chatbotkit_skillset.reporting_audit.id + space_id = chatbotkit_space.workflow_workspace.id + name = "Generate Execution Report" + description = "Create detailed execution reports and audit logs" + instruction = <<-EOT + template: shell/exec + parameters: {} + EOT +} + +resource "chatbotkit_skillset_ability" "send_email" { + skillset_id = chatbotkit_skillset.reporting_audit.id + name = "Send Workflow Summary Email" + description = "Email workflow execution summaries to stakeholders" + instruction = <<-EOT + template: email/send + parameters: {} + EOT +} + +# ============================================================================ +# Workflow Orchestrator Bot +# ============================================================================ +# The main orchestrator bot that executes multi-step workflows + +resource "chatbotkit_bot" "orchestrator" { + name = "Workflow Orchestrator" + description = "Multi-step workflow execution engine with dynamic capability loading and comprehensive tracing" + model = "claude-4.5-sonnet" + + backstory = <<-EOT + You are a Workflow Orchestrator Agent responsible for executing complex + multi-step workflows with precision and comprehensive logging. Your role + is to coordinate specialized workflow capabilities, manage execution + state, and produce detailed traces of all operations. + + ORCHESTRATION PRINCIPLES: + + 1. Dynamic Capability Loading + - Discover available workflow skillsets at runtime + - Load only the skillsets needed for the current workflow + - Understand each skillset's purpose before using its abilities + + 2. Workflow Execution + - Execute workflow steps in the correct sequence + - Validate inputs and outputs at each step + - Handle errors gracefully with appropriate retry logic + - Maintain idempotency where possible + + 3. State Management + - Write workflow state to persistent storage after each step + - Store complete context to enable pause/resume + - Track execution history for audit trails + - Use clear, consistent state file naming conventions + + 4. Comprehensive Tracing + - Log every workflow step with timestamp and details + - Document decision points and the reasoning behind choices + - Capture both successful operations and errors + - Generate execution summaries for human review + + WORKFLOW STRUCTURE: + + Your workflows should follow this pattern: + - Initialization: Load required skillsets and validate inputs + - Execution: Process each workflow step with state persistence + - Validation: Verify outputs meet requirements + - Completion: Generate execution report and clean up resources + + TRACING FORMAT: + + Create trace logs in your workspace with this structure: + ``` + # Workflow Execution Trace + Workflow: [workflow name] + Started: [timestamp] + Status: [in_progress|completed|failed] + + ## Step 1: [Step Name] + - Time: [timestamp] + - Action: [description] + - Input: [input data] + - Output: [output data] + - Status: [success|failed] + - Notes: [any relevant observations] + + ## Summary + - Total Steps: [number] + - Successful: [number] + - Failed: [number] + - Duration: [time] + ``` + + Store all traces in your workspace using timestamped filenames like: + workflow-trace-[workflow-name]-[YYYY-MM-DD-HH-MM-SS].md + + The current date is $${EARTH_DATE}. Execute workflows methodically, + document everything, and ensure complete traceability of all operations. + EOT + + skillset_id = chatbotkit_skillset.orchestration_core.id +} + +# ============================================================================ +# Trigger Integration +# ============================================================================ +# Manual or scheduled trigger for workflow execution + +resource "chatbotkit_trigger_integration" "workflow_trigger" { + bot_id = chatbotkit_bot.orchestrator.id + name = "Workflow Execution Trigger" + description = "Manual or scheduled trigger for workflow execution" + authenticate = true + session_duration = 3600000 + trigger_schedule = "never" +} + +# ============================================================================ +# Outputs +# ============================================================================ + +output "bot_id" { + description = "The ID of the workflow orchestrator bot" + value = chatbotkit_bot.orchestrator.id +} + +output "orchestration_skillset_id" { + description = "The ID of the orchestration core skillset" + value = chatbotkit_skillset.orchestration_core.id +} + +output "data_processing_skillset_id" { + description = "The ID of the data processing skillset" + value = chatbotkit_skillset.data_processing.id +} + +output "execution_control_skillset_id" { + description = "The ID of the execution control skillset" + value = chatbotkit_skillset.execution_control.id +} + +output "reporting_audit_skillset_id" { + description = "The ID of the reporting & audit skillset" + value = chatbotkit_skillset.reporting_audit.id +} + +output "workspace_id" { + description = "The ID of the workflow workspace" + value = chatbotkit_space.workflow_workspace.id +} diff --git a/types/types.go b/types/types.go index 3c593f1..3a2981a 100644 --- a/types/types.go +++ b/types/types.go @@ -959,6 +959,8 @@ type ExtractIntegration struct { ID *string `json:"id,omitempty"` // The metadata associated with the extract integration Meta map[string]interface{} `json:"meta,omitempty"` + // The LLM model to use for the extract integration + Model *string `json:"model,omitempty"` // The name of the extract integration Name *string `json:"name,omitempty"` // The date and time when the extract integration was last updated @@ -975,6 +977,8 @@ type ExtractIntegrationCreateRequest struct { Description *string `json:"description,omitempty"` // Additional metadata for the integration Meta map[string]interface{} `json:"meta,omitempty"` + // The LLM model to use for the extract integration + Model *string `json:"model,omitempty"` // The name of the integration Name *string `json:"name,omitempty"` // The webhook URL to send extracted data to @@ -1005,6 +1009,8 @@ type ExtractIntegrationUpdateRequest struct { Description *string `json:"description,omitempty"` // Additional metadata for the integration Meta map[string]interface{} `json:"meta,omitempty"` + // The LLM model to use for the extract integration + Model *string `json:"model,omitempty"` // The name of the integration Name *string `json:"name,omitempty"` // The webhook URL to send extracted data to @@ -1128,6 +1134,87 @@ type IncludeOwnSkillsetsInput struct { Visibility []SkillsetVisibility `json:"visibility,omitempty"` } +type InstagramIntegration struct { + // The blueprint associated with the instagram integration + Blueprint *Blueprint `json:"blueprint,omitempty"` + // The bot associated with the instagram integration + Bot *Bot `json:"bot,omitempty"` + // The date and time when the instagram integration was created + CreatedAt *string `json:"createdAt,omitempty"` + // The description of the instagram integration + Description *string `json:"description,omitempty"` + // The unique identifier of the instagram integration + ID *string `json:"id,omitempty"` + // The metadata associated with the instagram integration + Meta map[string]interface{} `json:"meta,omitempty"` + // The name of the instagram integration + Name *string `json:"name,omitempty"` + // The date and time when the instagram integration was last updated + UpdatedAt *string `json:"updatedAt,omitempty"` +} + +// InstagramIntegrationCreateRequest Input parameters for creating a new Instagram integration +type InstagramIntegrationCreateRequest struct { + // The Instagram access token + AccessToken *string `json:"accessToken,omitempty"` + // Whether to enable file attachments + Attachments *bool `json:"attachments,omitempty"` + // The ID of the blueprint to use + BlueprintId *string `json:"blueprintId,omitempty"` + // The ID of the bot to connect + BotId *string `json:"botId,omitempty"` + // Whether to collect contact information + ContactCollection *bool `json:"contactCollection,omitempty"` + // The description of the integration + Description *string `json:"description,omitempty"` + // Additional metadata for the integration + Meta map[string]interface{} `json:"meta,omitempty"` + // The name of the integration + Name *string `json:"name,omitempty"` + // The duration of the session in milliseconds + SessionDuration *int64 `json:"sessionDuration,omitempty"` +} + +// InstagramIntegrationCreateResponse Response containing the ID of a newly created Instagram integration +type InstagramIntegrationCreateResponse struct { + // The unique identifier of the created Instagram integration + ID *string `json:"id,omitempty"` +} + +// InstagramIntegrationDeleteResponse Response containing the ID of a deleted Instagram integration +type InstagramIntegrationDeleteResponse struct { + // The unique identifier of the deleted Instagram integration + ID *string `json:"id,omitempty"` +} + +// InstagramIntegrationUpdateRequest Input parameters for updating an existing Instagram integration +type InstagramIntegrationUpdateRequest struct { + // The Instagram access token + AccessToken *string `json:"accessToken,omitempty"` + // Whether to enable file attachments + Attachments *bool `json:"attachments,omitempty"` + // The ID of the blueprint to use + BlueprintId *string `json:"blueprintId,omitempty"` + // The ID of the bot to connect + BotId *string `json:"botId,omitempty"` + // Whether to collect contact information + ContactCollection *bool `json:"contactCollection,omitempty"` + // The description of the integration + Description *string `json:"description,omitempty"` + // Additional metadata for the integration + Meta map[string]interface{} `json:"meta,omitempty"` + // The name of the integration + Name *string `json:"name,omitempty"` + // The duration of the session in milliseconds + SessionDuration *int64 `json:"sessionDuration,omitempty"` +} + +// InstagramIntegrationUpdateResponse Response containing the ID of an updated Instagram integration +type InstagramIntegrationUpdateResponse struct { + // The unique identifier of the updated Instagram integration + ID *string `json:"id,omitempty"` +} + type McpserverIntegration struct { // The blueprint associated with the MCP server integration Blueprint *Blueprint `json:"blueprint,omitempty"` @@ -1321,6 +1408,7 @@ type Mutation struct { CreateEmailIntegration *EmailIntegrationCreateResponse `json:"createEmailIntegration,omitempty"` CreateExtractIntegration *ExtractIntegrationCreateResponse `json:"createExtractIntegration,omitempty"` CreateFile *FileCreateResponse `json:"createFile,omitempty"` + CreateInstagramIntegration *InstagramIntegrationCreateResponse `json:"createInstagramIntegration,omitempty"` CreateMcpserverIntegration *McpserverIntegrationCreateResponse `json:"createMcpserverIntegration,omitempty"` CreateMessengerIntegration *MessengerIntegrationCreateResponse `json:"createMessengerIntegration,omitempty"` CreateNotionIntegration *NotionIntegrationCreateResponse `json:"createNotionIntegration,omitempty"` @@ -1341,6 +1429,7 @@ type Mutation struct { DeleteEmailIntegration *EmailIntegrationDeleteResponse `json:"deleteEmailIntegration,omitempty"` DeleteExtractIntegration *ExtractIntegrationDeleteResponse `json:"deleteExtractIntegration,omitempty"` DeleteFile *FileDeleteResponse `json:"deleteFile,omitempty"` + DeleteInstagramIntegration *InstagramIntegrationDeleteResponse `json:"deleteInstagramIntegration,omitempty"` DeleteMcpserverIntegration *McpserverIntegrationDeleteResponse `json:"deleteMcpserverIntegration,omitempty"` DeleteMessengerIntegration *MessengerIntegrationDeleteResponse `json:"deleteMessengerIntegration,omitempty"` DeleteNotionIntegration *NotionIntegrationDeleteResponse `json:"deleteNotionIntegration,omitempty"` @@ -1362,6 +1451,7 @@ type Mutation struct { UpdateEmailIntegration *EmailIntegrationUpdateResponse `json:"updateEmailIntegration,omitempty"` UpdateExtractIntegration *ExtractIntegrationUpdateResponse `json:"updateExtractIntegration,omitempty"` UpdateFile *FileUpdateResponse `json:"updateFile,omitempty"` + UpdateInstagramIntegration *InstagramIntegrationUpdateResponse `json:"updateInstagramIntegration,omitempty"` UpdateMcpserverIntegration *McpserverIntegrationUpdateResponse `json:"updateMcpserverIntegration,omitempty"` UpdateMessengerIntegration *MessengerIntegrationUpdateResponse `json:"updateMessengerIntegration,omitempty"` UpdateNotionIntegration *NotionIntegrationUpdateResponse `json:"updateNotionIntegration,omitempty"`