Ruby API Reference

Reference surface for the Ruby SDK. These APIs wrap the Autohand CLI JSON-RPC runtime while keeping host-language lifecycle and event handling idiomatic.

Source: autohandai/code-agent-sdk-ruby/docs/API_REFERENCE.md.

Install

`AutohandSDK.configure`

Configuration sets the working directory, CLI binary path, debug output, request timeout, model override, skills, system prompt additions, and execution-mode flags.

`AutohandSDK::Client`

Use the low-level wrapper when you need direct JSON-RPC control.

  • .open(config = nil, **options) { |client| ... }
  • #start / #stop / #close
  • #stream_prompt(message_or_params, **options)
  • #prompt(message_or_params, **options)
  • #abort(reason: nil)
  • #permission_response
  • #set_permission_mode(mode)
  • #set_plan_mode(enabled)
  • #get_state
  • #get_messages

`AutohandSDK::Agent`

The high-level agent API is the best fit for product code that sends prompts, streams events, and waits for final results.

  • .create(config = nil, instructions: nil, **options)
  • #send(input, **options)
  • #run(input, **options)
  • #run_json(input, schema_name: nil, schema: nil, output_instructions: nil, validate: nil, **options)
  • #stream(input, **options)

Run

  • #stream returns an event enumerator
  • #wait returns the final result hash
  • #json(validate: nil) parses the final text as JSON
  • #abort aborts the active run

CLI Runtime Control

The typed runtime-control surface is available on AutohandSDK::Client and its RPC client.

  • Conversation and handoff: reset, create_browser_handoff, attach_browser_handoff, attach_latest_browser_handoff
  • Auto-mode: start_automode, get_automode_status, pause_automode, resume_automode, cancel_automode, get_automode_log
  • Approvals and sessions: acknowledge_permission, respond_to_directory_access, acknowledge_directory_access, decide_changes, get_session_history, get_session_details, attach_session
  • Integrations and context: set_yolo_mode, register_vscode_mcp_tools, complete_mcp_invocation, recommend_project_learning, update_project_learning, generate_project_skill, get_tools_registry, set_context_compaction

See Control the CLI runtime for behavior, safety contracts, and the equivalent names in every CLI-backed SDK.

SDK events

All CLI-backed SDKs expose the same runtime event names, with language-specific wrappers or helper methods around the raw JSON payload.

  • agent_start
  • turn_start
  • message_update
  • message_end
  • tool_start
  • tool_update
  • tool_end
  • permission_request
  • automode_iteration, automode_complete, automode_error
  • error

See Hooks and events for the complete normalized event contract.

Structured JSON

Use the JSON helpers when the host application needs typed output from the final assistant response.