C++ API Reference

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

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

Install

`autohand::Config`

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

`autohand::AutohandSdk`

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

  • start() / stop()
  • request(method, params_json)
  • prompt(message, options)
  • stream_prompt(message, on_event, options)
  • interrupt()
  • set_plan_mode(enabled)
  • set_permission_mode(mode)
  • set_model(model)
  • get_state()
  • get_messages()
  • permission_response(request_id, decision)

`autohand::Agent`

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

  • send(prompt, options)
  • run(prompt, options)
  • run_json(prompt, schema_json)
  • allow_permission(request_id)
  • deny_permission(request_id)
  • set_plan_mode(enabled)
  • close()

Run

  • stream(on_event): stream events and record final text
  • wait(): wait until the run finishes and collect text/events
  • json_text(): parse final output as JSON text
  • abort(): interrupt the current run

CLI Runtime Control

Core lifecycle and auto-mode operations are available on autohand::Agent and autohand::AutohandSdk. Use autohand::AutohandSdk for the complete approval, session, MCP, learning, tool-registry, and context surface.

  • 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, attach_session
  • Integrations and context: set_yolo, set_yolo_compat, set_vscode_mcp_tools, respond_to_mcp_invocation, recommend_project_skills, update_project_skills, generate_skill, get_tools_registry, set_context_compact

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.