💎 ChatSDK Ruby

Agent Tools

Generate provider-agnostic tool definitions for AI agents with preset permission levels.

ChatSDK::AI::ToolBuilder generates provider-agnostic tool definitions for AI agents that can interact with chat platforms.

Creating Tools

tools = ChatSDK::AI.create_tools(preset: :messenger)

Returns a hash of tool_name => definition:

{
  fetch_messages: {
    description: "Fetch recent messages from a channel or thread",
    parameters: { type: "object", properties: { ... }, required: [...] },
    read_only: true,
    requires_approval: false
  },
  post_message: {
    description: "Post a message to a channel or thread",
    parameters: { ... },
    read_only: false,
    requires_approval: true
  },
  # ...
}

Presets

PresetToolsUse Case
:readerfetch_messages, fetch_threadRead-only agents that observe conversations
:messengerReader + post_message, send_direct_message, add_reaction, start_typingAgents that participate in conversations
:moderatorMessenger + edit_message, delete_message, remove_reactionFull moderation capabilities

Approval Gates

Write tools can be gated behind approval:

# With approval (default) -- write tools have requires_approval: true
tools = ChatSDK::AI.create_tools(preset: :messenger, require_approval: true)

# Without approval -- all tools have requires_approval: false
tools = ChatSDK::AI.create_tools(preset: :messenger, require_approval: false)

Read-only tools (fetch_messages, fetch_thread) never require approval regardless of the setting.

Executing Tools

Use ChatSDK::AI::ToolExecutor to dispatch an LLM's tool call to the correct adapter method:

executor = ChatSDK::AI.create_executor(chat: chat)

# When your LLM returns a tool call:
result = executor.execute(:post_message, {
  adapter_name: "slack",
  channel_id: "C123",
  text: "Hello from the agent!"
})
# => { id: "msg_1", text: "Hello from the agent!" }

Arguments accept both symbol and string keys. The chat: parameter is required for the executor (it needs access to the adapters to dispatch calls).

Available Tools

fetch_messages

Fetch recent messages from a channel or thread.

ParameterTypeRequiredDescription
adapter_namestringyesAdapter name (e.g., "slack")
channel_idstringyesChannel ID
thread_idstringnoThread ID
limitintegernoMax messages (default: 20)

fetch_thread

Fetch all messages in a specific thread.

ParameterTypeRequiredDescription
adapter_namestringyesAdapter name
channel_idstringyesChannel ID
thread_idstringyesThread ID

post_message

Post a message to a channel or thread.

ParameterTypeRequiredDescription
adapter_namestringyesAdapter name
channel_idstringyesChannel ID
thread_idstringnoThread ID (for replies)
textstringyesMessage text (markdown)

send_direct_message

Send a direct message to a user.

ParameterTypeRequiredDescription
adapter_namestringyesAdapter name
user_idstringyesUser ID
textstringyesMessage text

edit_message

Edit an existing message. Moderator preset only.

ParameterTypeRequiredDescription
adapter_namestringyesAdapter name
channel_idstringyesChannel ID
message_idstringyesMessage ID to edit
textstringyesNew message text

delete_message

Delete a message. Moderator preset only.

ParameterTypeRequiredDescription
adapter_namestringyesAdapter name
channel_idstringyesChannel ID
message_idstringyesMessage ID to delete

add_reaction

Add an emoji reaction to a message.

ParameterTypeRequiredDescription
adapter_namestringyesAdapter name
channel_idstringyesChannel ID
message_idstringyesMessage ID
emojistringyesEmoji name (e.g., "thumbsup")

remove_reaction

Remove an emoji reaction. Moderator preset only.

ParameterTypeRequiredDescription
adapter_namestringyesAdapter name
channel_idstringyesChannel ID
message_idstringyesMessage ID
emojistringyesEmoji name

start_typing

Show a typing indicator in a channel.

ParameterTypeRequiredDescription
adapter_namestringyesAdapter name
channel_idstringyesChannel ID
thread_idstringnoThread ID

On this page