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:

{
  "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

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

{
  "success": true,
  "message": "Agent response",
  "chat_history_id": "abc-123",
  // ... additional fields
}

Error Response

{
  "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:

# 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:

-- 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: @skillful-ai/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 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