←back to manuals

Agent SDK

The ChatBotKit Agent SDK provides a powerful framework for building autonomous AI agents that can execute complex tasks using custom tools while leveraging the full capabilities of the ChatBotKit platform. This comprehensive guide covers tool creation, execution modes, integration patterns, and best practices for building intelligent agents.

Why ChatBotKit for Agent Development

Building AI agents with ChatBotKit offers significant advantages over traditional agent frameworks, making it the ideal choice for both rapid prototyping and production deployments.

Lightweight and Portable

Unlike heavyweight agent frameworks that require substantial system resources, the ChatBotKit Agent SDK is exceptionally lightweight and can be deployed anywhere:

  • Minimal Footprint: Add agent capabilities to any application with minimal overhead
  • Frontend & Backend: Works seamlessly in browser environments, Node.js servers, and serverless functions
  • Edge Computing: Runs efficiently on small embedded devices and edge infrastructure
  • No Heavy Dependencies: Streamlined architecture means faster cold starts and lower memory usage
  • Universal Compatibility: Deploy the same agent code across multiple platforms without modification

This portability means you can build once and deploy everywhere - from IoT devices to enterprise cloud infrastructure.

Managed Complexity

ChatBotKit handles the intricate details of building production-grade AI agents, allowing you to focus on your application logic:

  • Model Management: Automatic handling of model selection, fallbacks, and version updates
  • Integration Layer: Pre-built connectors to popular services and APIs
  • Context Management: Sophisticated conversation context and memory handling
  • Rate Limiting & Retries: Built-in resilience and error recovery
  • Security & Compliance: Enterprise-grade security measures and data handling
  • Quality Assurance: Optimized prompts and behaviors refined through extensive testing

You get enterprise-level capabilities without building and maintaining complex infrastructure.

Built-in Monitoring and Auditing

Production AI agents require comprehensive observability. ChatBotKit provides this out of the box:

  • Real-time Monitoring: Track agent performance, token usage, and execution metrics
  • Conversation Logs: Complete audit trail of all agent interactions and decisions
  • Tool Execution Tracking: Detailed logs of which tools were called, when, and with what results
  • Error Reporting: Automatic capture and categorization of failures and issues
  • Usage Analytics: Understand how agents are being used and optimize accordingly
  • Compliance Ready: Audit logs suitable for regulatory and security requirements

No need to build custom logging infrastructure or integrate third-party monitoring solutions.

ChatBotKit Dashboard as Management Plane

The ChatBotKit dashboard serves as a complete backend for your agents, eliminating the need for custom admin interfaces:

  • Team Collaboration: Invite team members with role-based access control
  • Agent Configuration: Manage agent settings, prompts, and behaviors through an intuitive UI
  • Direct Testing: Test and interact with agents directly from the dashboard
  • Built-in Components: Use pre-built UI components to embed agents in your applications
  • API Key Management: Generate and manage keys for different environments and teams
  • Usage Monitoring: View detailed analytics and usage patterns across all agents
  • Version Control: Track changes and roll back configurations when needed

This means faster time-to-market since you don't need to build dedicated dashboards, user management systems, or admin panels. Your team can start managing and deploying agents immediately.

Key Features

  • Custom tool integration with type-safe schemas
  • Dual execution modes (complete and execute)
  • Built-in task planning and progress tracking
  • Full ChatBotKit platform integration
  • Parallel tool execution
  • Streaming events and real-time feedback
  • Error handling and recovery

Getting Started

Installation

Prerequisites

  • Node.js 20.x or higher
  • A ChatBotKit API key
  • Basic understanding of async/await patterns
  • Familiarity with Zod schema validation

Authentication

Authentication is handled through the ChatBotKit SDK client, which should be initialized with your API key.

Best practices for API key management:

  • Store API keys in environment variables
  • Never commit API keys to version control
  • Use different keys for development and production
  • Rotate keys periodically for security

Tool Creation

Basic Tool Definition

Tools are the building blocks of agent capabilities. Each tool includes a description, input schema, and handler function.

Tool components:

  • description: Clear explanation of what the tool does (used by AI to decide when to use it)
  • input: Zod schema defining expected parameters
  • handler: Async function that executes the tool logic

Advanced Tool Examples

Execution Modes

Complete Mode

Complete mode provides streaming agent responses with tool execution for conversational AI that can take actions.

Event types in complete mode:

  • token: Streaming text tokens from the AI response
  • toolCallStart: Tool execution begins
  • toolCallEnd: Tool execution completes successfully
  • toolCallError: Tool execution failed

Execute Mode

Execute mode runs agents with built-in planning, progress tracking, and controlled exit for autonomous task completion.

Execute mode provides additional event types:

  • iteration: New iteration begins (agent continues working)
  • exit: Task completion with status code (0 = success)

System Tools

Execute mode includes three built-in system tools:

Platform Integration

Using Platform Capabilities

Agents automatically have access to all ChatBotKit platform features when you specify a botId:

Platform capabilities available to agents:

  • Integrations: Slack, Discord, Jira, Linear, Google Workspace, Notion, etc.
  • Datasets: Query knowledge bases for relevant information
  • Skillsets: Use pre-built abilities and custom functions
  • Authenticated sessions: No need to manage OAuth flows

Combining Local and Remote Tools

The power of the Agent SDK comes from combining local operations with remote integrations:

Real-World Examples

Development Workflow Automation

Data Processing Pipeline

System Monitoring

Error Handling

Tool-Level Error Handling

Best practices for tool error handling:

  • Always wrap operations in try-catch
  • Return structured error objects
  • Include helpful error messages
  • Log errors for debugging
  • Don't throw exceptions from handlers

Agent-Level Error Handling

Best Practices

  1. Tool Design
    • Keep tools focused on single responsibilities
    • Provide clear, descriptive tool descriptions
    • Use detailed Zod schemas with descriptions
    • Return structured, consistent results
    • Handle errors gracefully
  2. Security
    • Validate all tool inputs
    • Sanitize file paths and commands
    • Limit tool access scope
    • Use environment variables for secrets
    • Implement rate limiting for external APIs
  3. Performance
    • Design tools for parallel execution when possible
    • Avoid blocking operations in tool handlers
    • Implement timeouts for long-running operations
    • Cache results when appropriate
    • Monitor token usage
  4. Development
    • Test tools independently before agent integration
    • Use TypeScript for type safety
    • Log tool executions for debugging
    • Set appropriate maxIterations limits
    • Provide clear task instructions
  5. Agent Prompts
    • Be specific about desired outcomes
    • Break complex tasks into clear steps
    • Specify output formats
    • Include validation criteria
    • Provide necessary context

Advanced Patterns

Multi-Step Workflows

Conditional Tool Execution

Progress Monitoring

Configuration Options

Complete Mode Options

Execute Mode Options

References

Support Resources

agentsnodejs