r2agent setup

Requirements

Python 3.10 or higher with pipx or pip
radare2

Installation

Install the latest r2agent release with pip or pipx pipx install git+https://github.com/nitanmarcel/r2agent.git@main
- for dev builds install r2agent with pip or pipx pipx install git+https://github.com/nitanmarcel/r2agent.git@dev
Install the radare2 plugin curl -o ~/.local/share/radare2/plugins/r2plugin.py https://raw.githubusercontent.com/nitanmarcel/r2agent/refs/heads/main/r2plugin.py
Run r2agent r2a -c to generate the default config.yaml
Update your config to your liking. See [configuration][./configuration.md]

Configuration

Configuration file: ~/.config/r2agent/config.yaml

C:\Users\<YourUsername>\AppData\Roaming\r2agent\config.yaml (windows)

Fields

Mandatory fields:

default_provider - must match one of the provider names you’ve defined in the providers section.
providers -> <provider_name> -> model - the model identifier in LiteLLM format.

Optional fields:

providers -> <provider_name> -> api_key - your API key for authentication.
providers -> <provider_name> -> base_url - custom base URL for the provider.
providers -> <provider_name> -> extra_headers - additional headers to send with requests.
allow_r2cmd - allow the AI to execute radare2 commands directly.

Usage

r2agent communicates over stdio using a JSON-RPC 2.0 protocol. It can be used in two ways:

Stdio Protocol - Direct communication over stdin/stdout for custom integrations
Radare2 Plugin - Use r2agent directly from within radare2

Radare2 plugin

Environment variables

R2AGENT_AUTOSTART - auto start r2agent when the radare2 session opens.

Usage

Open a binary with radare2 r2 /bin/ls
Use r2a followed by your question [0x00001000]> r2a find all string references
- Press Ctrl+C to cancel a streaming response.

Commands

Session Management

Session Management

The following session management commands are available

r2as - List sessions for current binary

r2as* - List all sessions
r2as <id> - Switch to session
r2aS - Create new session
r2as- <id> - Delete session
r2as? - Show current session

Stdio Protocol

Usage

r2a stdio

Message Format

Each message follows the JSON-RPC 2.0 (https://www.jsonrpc.org/specification) specification.

Request:

{jsonrpc:2.0,method:<method>,params:{...},id:<number>}

Response:

{jsonrpc:2.0,result:{...},id:<number>}

Error:

{jsonrpc:2.0,error:{code:<number>,message:...},id:<number>}

Notification:

no response expected

{jsonrpc:2.0,method:<method>,params:{...}}

Error codes

-32700 Parse Error
-32600 Invalid Request
-32601 Method Not Found
-32602 Invalid Params
-32603 Internal Error
-32000 Timeout Error
-32001 Cancelled Error
-32002 Version Mismatch

Management

Initialize

Handshake to establish connection and exchange version info.

Request:

{
  jsonrpc: 2.0,
  method: initialize,
  params: {
    client_version: 0.3.2,
    binary_name: example.bin
  },
  id: 1
}

Response:

{
  jsonrpc: 2.0,
  result: {
    server_version: 0.3.2,
    protocol_version: 1.0
  },
  id: 1
}

ping

Health check.

Request:

{
  jsonrpc: 2.0,
  method: ping,
  id: 2
}

Response:

{
  jsonrpc: 2.0,
  result: pong,
  id: 2
}

ask

Send a prompt to the AI agent. The server streams responses via notifications before sending the final result.

Request:

{
  jsonrpc: 2.0,
  method: ask,
  params: {prompt: What does the main function do?},
  id: 3
}

Stream notifications (server → client):

{jsonrpc: 2.0, method: stream, params: {type: agent_start, data: {name: RAgent}}}
{jsonrpc: 2.0, method: stream, params: {type: text_delta, data: {delta: The main }}}
{jsonrpc: 2.0, method: stream, params: {type: text_delta, data: {delta: function...}}}
{jsonrpc: 2.0, method: stream, params: {type: tool_call, data: {name: decompile, args: {...}}}}

Final response:

{jsonrpc: 2.0, result: The main function..., id: 3}

cancel

Cancel the current ask request. This is a notification (no response).

The pending ask will return with result “[cancelled]”.

{jsonrpc: 2.0, method: cancel}

shutdown

Gracefully stop the server.

Request:

{jsonrpc: 2.0, method: shutdown, id: 4}

Response:

{jsonrpc: 2.0, result: ok, id: 4}

Session Management

session_list

List available sessions.

Request:

{
  jsonrpc: 2.0,
  method: session_list,
  params: {filter_binary: true},
  id: 5
}

Response:

{
  jsonrpc: 2.0,
  result: [
    {
      session_id: example_20240101_120000_abc123,
      binary_name: example.bin,
      created_at: 2024-01-01T12:00:00,
      last_accessed: 2024-01-01T12:30:00,
      is_current: true
    }
  ],
  id: 5
}

session_new

Create a new session.

Request:

{
  jsonrpc: 2.0,
  method: session_new,
  params: {},
  id: 6
}

Response:

{
  jsonrpc: 2.0,
  result: {session_id: ..., message: Created new session},
  id: 6
}

session_switch

Switch to an existing session.

Request:

{
  jsonrpc: 2.0,
  method: session_switch,
  params: {session_id: <session_id>},
  id: 7
}

Response:

{
  jsonrpc: 2.0,
  result: {message: Switched to session <session_id>},
  id: 7
}

session_delete

Delete a session.

Request:

{
  jsonrpc: 2.0,
  method: session_delete,
  params: {session_id: <session_id>},
  id: 8
}

Response:

{
  jsonrpc: 2.0,
  result: {message: Deleted session <session_id>},
  id: 8
}

session_current

Get the current session info.

Request:

{
  jsonrpc: 2.0,
  method: session_current,
  params: {},
  id: 9
}

Response:

{
  jsonrpc: 2.0,
  result: {session_id: ..., binary_name: example.bin},
  id: 9
}

Tool Calls (IPC)

The server may request the client to execute radare2 commands.

Server → Client (notification):

{
  jsonrpc: 2.0,
  method: tool_call,
  params: {
    id: 1,
    name: r2cmd,
    args: {command: pdf @ main}
  }
}

Client → Server (notification):

{
  jsonrpc: 2.0,
  method: tool_result,
  params: {
    id: 1,
    result: ... disassembly output ...
  }
}

Keyboard shortcuts

r2agent