LangGraph Platform Ruby SDK

An unoffical Ruby SDK for interacting with the LangGraph Platform API. This gem provides a Ruby-idiomatic interface for managing assistants, threads, runs, crons, store operations, and Model Context Protocol (MCP) interactions.

Current Status

This is a work in progress. The SDK is not yet complete and fully tested.

Roadmap

• [x] Assistants
• [x] Threads
• [x] Runs
• [ ] Crons
• [ ] Store Operations
• [ ] Model Context Protocol (MCP)

Installation

Add this line to your application's Gemfile:

gem 'langgraph-platform'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install langgraph-platform

Quick Start

require 'langgraph_platform'

# Initialize the client
client = LanggraphPlatform::Client.new(
  api_key: 'your-api-key-here',
  base_url: 'https://api.langchain.com' # For local development, use http://127.0.0.1:2024
)

# Create an assistant
assistant = client.assistants.create(
  graph_id: 'my-graph',
  name: 'My Assistant',
  config: { recursion_limit: 10 }
)

# Create a thread
thread = client.threads.create(
  metadata: { user_id: 'user123' }
)

# Run the assistant
run = client.runs.create(
  thread.thread_id,
  assistant_id: assistant.assistant_id,
  input: { message: 'Hello, world!' }
)

puts "Run status: #{run.status}"

Configuration

Environment Variables

The SDK can be configured using environment variables:

• LANGGRAPH_API_KEY: Your LangGraph Platform API key (use fake-api-key for local development)
• LANGGRAPH_BASE_URL: Custom base URL (defaults to https://api.langchain.com)

Client Configuration

client = LanggraphPlatform::Client.new(
  api_key: 'your-api-key',
  base_url: 'https://custom-api.example.com',
  timeout: 30,
  retries: 3
)

# Or configure after initialization
client.configure do |config|
  config.timeout = 60
  config.retries = 5
end

Features

Assistants

# Create an assistant
assistant = client.assistants.create(
  graph_id: 'my-graph',
  name: 'My Assistant',
  config: { recursion_limit: 10 },
  metadata: { version: '1.0' }
)

# Find an assistant
assistant = client.assistants.find('assistant-id')

# Search assistants
assistants = client.assistants.search(
  metadata: { version: '1.0' },
  limit: 10
)

# Update an assistant
client.assistants.update('assistant-id', name: 'Updated Name')

# Delete an assistant
client.assistants.delete('assistant-id')

Threads

# Create a thread
thread = client.threads.create(
  metadata: { user_id: 'user123' }
)

# Get thread state
state = client.threads.state(thread.thread_id)

# Update thread state
client.threads.update_state(
  thread.thread_id,
  values: { key: 'value' }
)

# Get thread history
history = client.threads.history(thread.thread_id, limit: 10)

# Search threads
threads = client.threads.search(
  status: 'idle',
  limit: 10
)

Runs

# Create a run
run = client.runs.create(
  thread.thread_id,
  assistant_id: assistant.assistant_id,
  input: { message: 'Hello!' }
)

# Create a run with webhook
run = client.runs.create(
  thread.thread_id,
  assistant_id: assistant.assistant_id,
  input: { message: 'Hello!' },
  webhook: 'https://your-app.com/webhooks/langgraph'
)

# Stream a run
client.runs.stream(
  thread.thread_id,
  assistant_id: assistant.assistant_id,
  input: { message: 'Hello!' }
) do |type, data, id, reconnection_time|
  puts "Event: #{type}, Data: #{data}"
end

# Stream a run with webhook
client.runs.stream(
  thread.thread_id,
  assistant_id: assistant.assistant_id,
  input: { message: 'Hello!' },
  webhook: 'https://your-app.com/webhooks/langgraph'
) do |type, data, id, reconnection_time|
  puts "Event: #{type}, Data: #{data}"
end

# Wait for a run to complete
result = client.runs.wait(
  thread.thread_id,
  assistant_id: assistant.assistant_id,
  input: { message: 'Hello!' }
)

# Wait for a run with webhook
result = client.runs.wait(
  thread.thread_id,
  assistant_id: assistant.assistant_id,
  input: { message: 'Hello!' },
  webhook: 'https://your-app.com/webhooks/langgraph'
)

# List runs
runs = client.runs.list(thread.thread_id)

# Cancel a run
client.runs.cancel(thread.thread_id, run.run_id)

Crons

Under development and untested.

# Create a cron job
cron = client.crons.create(
  assistant_id: assistant.assistant_id,
  schedule: '0 */6 * * *', # Every 6 hours
  payload: { task: 'periodic_task' }
)

# List cron jobs
crons = client.crons.list(assistant_id: assistant.assistant_id)

# Enable/disable cron jobs
client.crons.enable(cron.cron_id)
client.crons.disable(cron.cron_id)

Store Operations

Under development and untested.

# Store data
client.store.put('namespace', 'key', { data: 'value' })

# Retrieve data
item = client.store.get('namespace', 'key')

# List items in namespace
items = client.store.list('namespace', prefix: 'user_')

# Delete data
client.store.delete('namespace', 'key')

# Batch operations
client.store.batch_put([
  { namespace: 'ns1', key: 'key1', value: 'value1' },
  { namespace: 'ns1', key: 'key2', value: 'value2' }
])

Model Context Protocol (MCP)

Under development and untested.

# List available tools
tools = client.mcp.list_tools

# Call a tool
result = client.mcp.call_tool(
  'tool_name',
  arguments: { param: 'value' }
)

# List resources
resources = client.mcp.list_resources

# Read a resource
content = client.mcp.read_resource('resource://example')

# Work with prompts
prompts = client.mcp.list_prompts
result = client.mcp.complete_prompt('prompt_name', arguments: {})

Webhooks

The SDK supports webhooks that are called after LangGraph API calls complete. Webhooks can be used with any run creation method:

# Thread-based runs with webhooks
run = client.runs.create(
  thread.thread_id,
  assistant_id: assistant.assistant_id,
  input: { message: 'Process this data' },
  webhook: 'https://your-app.com/webhooks/langgraph'
)

# Stateless runs with webhooks
client.runs.create_stateless(
  assistant_id: assistant.assistant_id,
  input: { message: 'Process this data' },
  webhook: 'https://your-app.com/webhooks/langgraph'
)

# Streaming runs with webhooks
client.runs.stream(
  thread.thread_id,
  assistant_id: assistant.assistant_id,
  input: { message: 'Process this data' },
  webhook: 'https://your-app.com/webhooks/langgraph'
) do |type, data, id, reconnection_time|
  # Handle streaming events
end

Webhook Requirements:

• Must be a valid URI (up to 65,536 characters)
• Should handle HTTP POST requests from LangGraph Platform
• Called after the API call completes

Streaming

The SDK supports Server-Sent Events (SSE) streaming for real-time responses. Streaming blocks receive four parameters directly from the SSE parser:

• type: Event type (e.g., 'messages/partial', 'updates', 'values', 'error')
• data: Parsed JSON data or raw string content
• id: Event ID (optional)
• reconnection_time: SSE reconnection time in milliseconds (optional)

client.runs.stream(
  thread.thread_id,
  assistant_id: assistant.assistant_id,
  input: { message: 'Tell me a story' }
) do |type, data, id, reconnection_time|
  case type
  when 'data'
    puts "Data: #{data}"
  when 'message'
    puts "Message: #{data}"
  when 'error'
    puts "Error: #{data}"
  when 'end'
    puts "Stream ended"
  end
end

Error Handling

The SDK provides specific error classes for different API errors:

begin
  assistant = client.assistants.find('nonexistent-id')
rescue LanggraphPlatform::Errors::NotFoundError => e
  puts "Assistant not found: #{e.message}"
rescue LanggraphPlatform::Errors::UnauthorizedError => e
  puts "Authentication failed: #{e.message}"
rescue LanggraphPlatform::Errors::APIError => e
  puts "API error: #{e.message}"
end

Available error classes:

• LanggraphPlatform::Errors::APIError - Base error class
• LanggraphPlatform::Errors::BadRequestError - 400 errors
• LanggraphPlatform::Errors::UnauthorizedError - 401 errors
• LanggraphPlatform::Errors::NotFoundError - 404 errors
• LanggraphPlatform::Errors::ConflictError - 409 errors
• LanggraphPlatform::Errors::ValidationError - 422 errors
• LanggraphPlatform::Errors::ServerError - 500+ errors

Examples

Check out the examples/ directory for more comprehensive examples:

• examples/basic_usage.rb - Basic CRUD operations
• examples/streaming_example.rb - Streaming functionality

Development

To run the tests:

$ bundle exec rspec

To run RuboCop:

$ bundle exec rubocop

Acknowledgments

• Thanks to the LangGraph team for their work on the SDKs and for providing the API reference.
• Thanks to the Shopify team for event_stream_parser gem.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/gysmuller/langgraph-platform.

License

The gem is available as open source under the terms of the MIT License.

Changelog

See CHANGELOG.md for a list of changes.