←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.

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