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

CMake

include(FetchContent)

FetchContent_Declare(
  autohand_sdk
  GIT_REPOSITORY https://github.com/autohandai/code-agent-sdk-cpp.git
  GIT_TAG main
)

FetchContent_MakeAvailable(autohand_sdk)
target_link_libraries(my_app PRIVATE autohand::sdk)

`autohand::Config`

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

cpp

auto config = autohand::Config::from_environment()
    .with_cwd(".")
    .with_model("fantail2")
    .with_skill("cpp")
    .with_instructions("Prefer small, typed C++ APIs.");

`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.

cpp

autohand::Agent agent(autohand::Config::from_environment().with_cwd("."));
auto run = agent.send("Review the public API.");
auto result = run.wait();
agent.close();
  • 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.

cpp

auto json = agent.run_json(
    "Assess release readiness.",
    R"({"summary":"string","risks":[]})");