Public documentation

Targets

Targets define how Roleplay sends messages to the agent under test.

HTTP Target

Use an HTTP target when your agent exposes an endpoint.

target:
  type: http
  url: http://localhost:3000/agent
  method: POST
  headers:
    Authorization: "Bearer ${AGENT_API_KEY}"
  input:
    messageField: message
    sessionField: sessionId
  output:
    responseField: response
  timeoutMs: 30000

Supported methods:

POST
PUT
PATCH

Defaults:

method: POST
input.messageField: message
input.sessionField: sessionId
output.responseField: response
timeoutMs: 30000

The target endpoint should accept a JSON body containing the current message and session ID, and return a JSON response containing the agent reply.

CLI Target

Use a CLI target when your agent can be executed as a local command.

target:
  type: cli
  command: "node ./examples/agents/simple-support-agent.js"
  mode: stdin
  shell: false
  timeoutMs: 30000

Fields:

Field	Values	Default	Description
`command`	string	required	Command to run.
`mode`	`stdin`, `arg`	`stdin`	How messages are passed.
`shell`	boolean	`false`	Whether to execute through a shell.
`timeoutMs`	positive integer	`30000`	Command timeout.

CLI targets execute local commands. Use --yes to acknowledge command execution in automated runs.

roleplay run .roleplay/scenarios/my-cli-scenario.yml --yes

Set shell: true only when you intentionally need shell behavior such as expansion or compound commands.

Mock Target

Use a mock target for deterministic local tests.

target:
  type: mock
  behavior: safe-support-agent

Supported behaviors:

naive-refund-agent
safe-support-agent
prompt-injection-vulnerable

Mock targets are useful for learning, documentation examples, and tests that should not call external services.

Built-In Attack Pack Targets

When running social-engineering-core, pass a target directly through CLI flags instead of editing generated scenario YAML.

HTTP:

roleplay run social-engineering-core --target http://localhost:3000/agent --provider <provider> --judge hybrid

CLI:

roleplay run social-engineering-core --target-command "node ./agent.js" --yes --provider <provider> --judge hybrid

Environment variables:

ROLEPLAY_TARGET_URL=http://localhost:3000/agent ROLEPLAY_LLM_PROVIDER=<provider> ROLEPLAY_JUDGE_MODE=hybrid ROLEPLAY_JUDGE_PROVIDER=<provider> roleplay run social-engineering-core
ROLEPLAY_TARGET_COMMAND="node ./agent.js" ROLEPLAY_LLM_PROVIDER=<provider> ROLEPLAY_JUDGE_MODE=hybrid ROLEPLAY_JUDGE_PROVIDER=<provider> roleplay run social-engineering-core --yes