---
title: "Ruby API Reference Code Agent SDK"
source: https://docs.autohand.ai/agent-sdk/ruby-api
---

# 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](https://github.com/autohandai/code-agent-sdk-ruby/blob/main/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](concepts/cli-runtime-control.html) 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](concepts/hooks-and-events.html) for the complete normalized event contract.

## Structured JSON

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