@skillful-ai/piece-skillful-agents 0.0.1

package/.eslintrc.json

@@ -0,0 +1,18 @@
+{
+  "extends": ["../../../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,173 @@
+# Skillful Agents Piece
+
+Interact with Skillful AI agents for advanced conversational AI and task automation. This piece provides seamless integration with the SKAI Agents platform through Activepieces, allowing you to send messages to your Skillful agents directly from your workflows.
+
+## 🎯 Features
+
+- **Send Messages to Agents**: Send messages to Skillful agents and receive intelligent responses
+- **Agent Selection**: Choose from your available Skillful agents via dropdown
+- **Test Mode**: Test agents without consuming your usage allowance  
+- **Server-side Authentication**: Secure API key management handled by Activepieces
+- **Flow Builder Integration**: Skillful agents appear directly in the Activepieces agents view
+
+## 🚀 Actions
+
+### Send Message to Skillful Agent
+
+The primary action for interacting with Skillful agents. Always starts a new conversation.
+
+**Properties:**
+- **Skillful Agent** (required): Select from your available Skillful agents
+- **Message** (required): The message to send to the agent
+- **Test Mode** (optional): Enable to avoid consuming your usage allowance
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Agent's response text",
+  "chat_history_id": "conversation-id-123",
+  "agent_id": "agent-456", 
+  "user_message": "Your original message",
+  "test_mode": false
+}
+```
+
+## 🔧 Authentication & Setup
+
+### Server-Side Authentication
+This piece uses **server-side authentication** - no piece-level configuration required. Your SKAI API key is securely stored and managed by the Activepieces server.
+
+### Setting Up SKAI API Key
+1. Obtain your SKAI API key from your Skillful account
+2. Configure it in your Activepieces user settings (stored as `skaiApiKey` in user profile)
+3. The piece automatically uses your configured API key for all requests
+
+### Agent Access Integration
+Skillful agents are integrated directly into Activepieces:
+- **Agents View**: Skillful agents appear in the flow builder's agents section
+- **Unified Experience**: Same interface as internal Activepieces agents
+- **Dynamic Loading**: Agent list updates automatically based on your SKAI account
+
+## 📖 Usage Examples
+
+### Basic Message Sending
+1. Add "Send Message to Skillful Agent" action to your flow
+2. Select an agent from the dropdown (populated from your SKAI account)
+3. Enter your message
+4. Run the flow to get the agent's response
+
+### In a Workflow Context
+```yaml
+Flow Example:
+1. Trigger: New email received
+2. Action: Send Message to Skillful Agent
+   - Agent: "Customer Support Agent"  
+   - Message: "Analyze this email: {{trigger.email_body}}"
+3. Action: Send response email with agent's analysis
+```
+
+### Testing Mode
+Enable "Test Mode" to:
+- Verify agent responses without consuming allowance
+- Test different message formats
+- Debug agent behavior during development
+
+## ⚠️ Error Handling
+
+The action returns structured error information for troubleshooting:
+
+### Success Response
+```json
+{
+  "success": true,
+  "message": "Agent response",
+  "chat_history_id": "abc-123",
+  // ... additional fields
+}
+```
+
+### Error Response  
+```json
+{
+  "success": false,
+  "error": "Error description",
+  "agent_id": "agent-456",
+  "user_message": "Your message"
+}
+```
+
+### Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| No agents in dropdown | Missing SKAI API key | Configure API key in user settings |
+| "Agent not found" error | Invalid agent selection | Verify agent is accessible to your account |
+| Authentication errors | Invalid/expired API key | Update API key in user settings |
+| Network timeouts | SKAI API connectivity | Check network and API status |
+
+## 🧪 Local Development & Testing
+
+### Adding to Development Environment
+Add the piece to your local development:
+
+```bash
+# 1. Add to development pieces in packages/server/api/.env
+AP_DEV_PIECES="google-sheets,store,skillful-agents"
+
+# 2. Build the piece
+npx nx build pieces-skillful-agents
+
+# 3. Start development server  
+npm run dev
+```
+
+### Database Setup (SQLite)
+For local testing with SQLite, add SKAI API key to user:
+
+```sql
+-- Update user with SKAI API key
+UPDATE user SET skaiApiKey = 'your-skai-api-key-here' WHERE id = 'USER_ID';
+```
+
+### Testing Integration
+1. **Agents View**: Navigate to agents in flow builder - should show Skillful agents
+2. **Piece Available**: "Skillful Agents" should appear in pieces list
+3. **Agent Dropdown**: Should populate with your agents when creating flows
+4. **End-to-End**: Send test message and verify response
+
+## 🔗 Architecture
+
+### System Integration
+- **Bridge Service**: `/v1/skai-agents` API endpoints handle SKAI communication
+- **Agents Service**: Modified to return Skillful agents in place of internal agents
+- **Piece Framework**: Standard Activepieces piece using dropdown properties
+- **Authentication**: Server-side user context extraction with API key management
+
+### API Endpoints Used
+- `GET /v1/skai-agents` - List user's agents (used by dropdown)
+- `POST /v1/skai-agents/chat/new` - Send new message (used by action)
+
+## 📋 Technical Details
+
+- **Package Name**: `@activepieces/piece-skillful-agents`
+- **Piece Name**: `skillful-agents`
+- **Category**: Universal AI
+- **Minimum Release**: 0.66.0
+- **Authentication**: Server-side (PieceAuth.None)
+
+## 🆘 Support
+
+### For Piece Issues
+1. Check SKAI API key is configured in user settings
+2. Verify selected agents are accessible to your account
+3. Check Activepieces server logs for detailed error messages
+4. Ensure piece is built and loaded in development environment
+
+### For Skillful Platform Issues
+Visit [https://skillful.ai](https://skillful.ai) for Skillful Agents platform support.
+
+### Development Support
+- Check `AP_DEV_PIECES` environment variable includes `skillful-agents`
+- Verify piece builds successfully: `npx nx build pieces-skillful-agents`
+- Monitor server logs during piece loading and execution

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@skillful-ai/piece-skillful-agents",
+  "version": "0.0.1",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
+}

package/project.json

@@ -0,0 +1,46 @@
+{
+  "name": "pieces-skillful-agents",
+  "$schema": "../../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/pieces/custom/skillful-agents/src",
+  "projectType": "library",
+  "release": {
+    "version": {
+      "manifestRootsToUpdate": ["dist/{projectRoot}"],
+      "currentVersionResolver": "git-tag",
+      "fallbackCurrentVersionResolver": "disk"
+    }
+  },
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/packages/pieces/custom/skillful-agents",
+        "tsConfig": "packages/pieces/custom/skillful-agents/tsconfig.lib.json",
+        "packageJson": "packages/pieces/custom/skillful-agents/package.json",
+        "main": "packages/pieces/custom/skillful-agents/src/index.ts",
+        "assets": [
+          "packages/pieces/custom/skillful-agents/*.md",
+          {
+            "input": "packages/pieces/custom/skillful-agents/src/i18n",
+            "output": "./src/i18n",
+            "glob": "**/!(i18n.json)"
+          }
+        ],
+        "buildableProjectDepsInPackageJsonType": "dependencies",
+        "updateBuildableProjectDepsInPackageJson": true
+      },
+      "dependsOn": ["^build"]
+    },
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "dist/{projectRoot}"
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": ["{options.outputFile}"]
+    }
+  }
+}

package/src/i18n/translation.json

@@ -0,0 +1,24 @@
+{
+  "List Skillful Agents": "List Skillful Agents",
+  "Chat with Skillful Agent": "Chat with Skillful Agent", 
+  "Start New Chat with Agent": "Start New Chat with Agent",
+  "Continue Chat with Agent": "Continue Chat with Agent",
+  "Skillful Agent": "Skillful Agent",
+  "Message": "Message",
+  "Initial Message": "Initial Message",
+  "Chat History ID": "Chat History ID",
+  "Test Mode": "Test Mode",
+  "Retrieve all available Skillful agents for the authenticated user": "Retrieve all available Skillful agents for the authenticated user",
+  "Send a message to a Skillful agent and receive a response. Can be used for new conversations or to continue existing ones.": "Send a message to a Skillful agent and receive a response. Can be used for new conversations or to continue existing ones.",
+  "Start a new conversation with a Skillful agent. This will always create a new chat history.": "Start a new conversation with a Skillful agent. This will always create a new chat history.",
+  "Continue an existing conversation with a Skillful agent using a chat history ID.": "Continue an existing conversation with a Skillful agent using a chat history ID.",
+  "Select the Skillful agent to chat with": "Select the Skillful agent to chat with",
+  "Select the Skillful agent to start chatting with": "Select the Skillful agent to start chatting with",
+  "Select the Skillful agent you were chatting with": "Select the Skillful agent you were chatting with",
+  "The message to send to the agent": "The message to send to the agent",
+  "The first message to send to start the conversation": "The first message to send to start the conversation",
+  "The message to send in the existing conversation": "The message to send in the existing conversation",
+  "Optional: Provide to continue an existing conversation. Leave empty to start a new chat.": "Optional: Provide to continue an existing conversation. Leave empty to start a new chat.",
+  "The chat history ID from a previous conversation (obtained from \"Start Chat\" or previous \"Continue Chat\")": "The chat history ID from a previous conversation (obtained from \"Start Chat\" or previous \"Continue Chat\")",
+  "Enable test mode - messages won't consume your usage allowance": "Enable test mode - messages won't consume your usage allowance"
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+import { createPiece, PieceAuth } from "@activepieces/pieces-framework";
+import { PieceCategory } from "@activepieces/shared";
+import { runAgent } from "./lib/actions/run-agent";
+
+export const skillfulAgents = createPiece({
+  displayName: "Skillful Agents",
+  auth: PieceAuth.None(),
+  minimumSupportedRelease: '0.66.0',
+  logoUrl: "https://app.skillfulai.io/images/logo.png",
+  authors: ['skillful-ai'],
+  description: "Interact with Skillful AI agents for advanced conversational AI and task automation",
+  actions: [
+    runAgent
+  ],
+  triggers: [],
+  categories: [PieceCategory.UNIVERSAL_AI],
+});

package/src/lib/actions/run-agent.ts

@@ -0,0 +1,114 @@
+import { createAction, Property } from '@activepieces/pieces-framework'
+import { skillfulAgentsCommon } from '../common'
+import { SkillfulAgent, SkillfulChatResponse, AgentDropdownOption } from '../types'
+
+export const runAgent = createAction({
+  name: 'run_agent',
+  displayName: 'Run Agent',
+  description: 'Execute a Skillful agent with a message and receive a response.',
+  props: {
+    agentId: Property.Dropdown({
+      displayName: 'Skillful Agent',
+      description: 'Select the Skillful agent to run',
+      required: true,
+      refreshers: [],
+      options: async (_auth, ctx) => {
+        if (!ctx?.server?.token) {
+          return {
+            disabled: true,
+            options: [],
+            placeholder: 'Server token required'
+          }
+        }
+
+        try {
+          const response = await skillfulAgentsCommon.listAgents({
+            serverUrl: ctx.server.publicUrl,
+            token: ctx.server.token
+          })
+
+          if (response.status === 200) {
+            const agents: SkillfulAgent[] = response.body
+            const options: AgentDropdownOption[] = agents.map((agent) => ({
+              label: `${agent.name}${agent.description ? ` - ${agent.description}` : ''}`,
+              value: agent.id
+            }))
+
+            return {
+              disabled: false,
+              options: options
+            }
+          } else {
+            return {
+              disabled: true,
+              options: [],
+              placeholder: `Failed to load agents: ${response.status}`
+            }
+          }
+        } catch (error) {
+          return {
+            disabled: true,
+            options: [],
+            placeholder: 'Error loading agents'
+          }
+        }
+      },
+    }),
+    message: Property.LongText({
+      displayName: 'Message',
+      description: 'The input message or prompt for the agent',
+      required: true,
+    }),
+    testMode: Property.Checkbox({
+      displayName: 'Test Mode',
+      description: 'Enable test mode - agent execution won\'t consume your usage allowance',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  async run(context) {
+    const { agentId, message, testMode } = context.propsValue
+    const serverUrl = context.server.publicUrl
+    const token = context.server.token
+
+    if (!agentId || !message) {
+      return {
+        success: false,
+        error: 'Agent ID and message are required'
+      }
+    }
+
+    try {
+      // Use single chat endpoint (no chatHistoryId = new chat)
+      const response = await skillfulAgentsCommon.chatWithAgent({
+        serverUrl,
+        token,
+        agentId,
+        message,
+        isTestMode: testMode || false
+      })
+
+      if (response.status === 200) {
+        const chatResponse: SkillfulChatResponse = response.body
+        
+        return {
+          success: true,
+          message: chatResponse.message,
+          chatHistoryId: chatResponse.chatHistoryId,
+          agentId: agentId,
+          userMessage: message,
+          testMode: testMode || false
+        }
+      } else {
+        throw new Error(`Message send failed: ${response.status} ${response.body?.message || 'Unknown error'}`)
+      }
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred',
+        agentId: agentId,
+        userMessage: message
+      }
+    }
+  },
+})

package/src/lib/common.ts

@@ -0,0 +1,70 @@
+import { httpClient, HttpMethod, AuthenticationType } from '@activepieces/pieces-common'
+
+/**
+ * Common utilities for Skillful Agents piece
+ * Handles communication with the SKAI Agents bridge service
+ */
+
+export const skillfulAgentsCommon = {
+  /**
+   * Base URL for SKAI agents bridge service endpoints
+   */
+  getBaseUrl: (serverUrl: string) => `${serverUrl}v1/skai-agents`,
+
+  /**
+   * List all available agents for the authenticated user
+   */
+  async listAgents(params: { serverUrl: string, token: string }) {
+    return await httpClient.sendRequest({
+      method: HttpMethod.GET,
+      url: `${skillfulAgentsCommon.getBaseUrl(params.serverUrl)}`,
+      authentication: {
+        type: AuthenticationType.BEARER_TOKEN,
+        token: params.token,
+      },
+    })
+  },
+
+  /**
+   * Get a specific agent by ID
+   */
+  async getAgent(params: { serverUrl: string, token: string, agentId: string }) {
+    return await httpClient.sendRequest({
+      method: HttpMethod.GET,
+      url: `${skillfulAgentsCommon.getBaseUrl(params.serverUrl)}/${params.agentId}`,
+      authentication: {
+        type: AuthenticationType.BEARER_TOKEN,
+        token: params.token,
+      },
+    })
+  },
+
+  /**
+   * Chat with an agent (handles both new and existing conversations)
+   * If chatHistoryId is provided, continues existing conversation
+   * If chatHistoryId is omitted, starts new conversation
+   */
+  async chatWithAgent(params: {
+    serverUrl: string,
+    token: string,
+    agentId: string,
+    message: string,
+    chatHistoryId?: string,
+    isTestMode?: boolean
+  }) {
+    return await httpClient.sendRequest({
+      method: HttpMethod.POST,
+      url: `${skillfulAgentsCommon.getBaseUrl(params.serverUrl)}/chat`,
+      authentication: {
+        type: AuthenticationType.BEARER_TOKEN,
+        token: params.token,
+      },
+      body: {
+        agentId: params.agentId,
+        message: params.message,
+        chatHistoryId: params.chatHistoryId,
+        isTestMode: params.isTestMode || false
+      },
+    })
+  }
+}

package/src/lib/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Type definitions for Skillful Agents piece
+ * These types match the SKAI API response formats
+ */
+
+export interface SkillfulAgent {
+  id: string
+  name: string
+  description: string
+  logoUrl: string
+  isDraft?: boolean
+  isMinted?: boolean
+  type: string
+  ownerUserId?: string
+  config?: any
+}
+
+export interface SkillfulChatResponse {
+  message: string
+  chatHistoryId: string
+}
+
+export interface AgentDropdownOption {
+  label: string
+  value: string
+}
+
+/**
+ * Context passed to actions from piece execution
+ */
+export interface ActionContext {
+  server: {
+    publicUrl: string
+    token: string
+  }
+  propsValue: Record<string, any>
+}
+
+/**
+ * Base parameters for all agent operations
+ */
+export interface BaseAgentParams {
+  serverUrl: string
+  token: string
+}
+
+/**
+ * Parameters for chat operations
+ */
+export interface ChatParams extends BaseAgentParams {
+  agentId: string
+  message: string
+  chatHistoryId?: string
+  isTestMode?: boolean
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "importHelpers": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../../../dist/out-tsc",
+    "declaration": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}