Enable Tool Tracing for SDK Scans

When you drive scans with the SDK, call setSessionId with your agent’s session id so the tool calls your agent reports join the right conversation in the scan.

A session is one conversation between your scan driver and your agent. A scan runs many sessions, and one attack can use more than one, for example when it restarts the conversation. Call setSessionId once in each session.

This is the scan-driver half of tool tracing. First instrument your agent’s runtime — see Trace Agent Tools — then bind the id here.

Prerequisites

• An agent runtime instrumented for tracing, per Trace Agent Tools
• A scan you run with the SDK — see the Quickstart
• A Red Team API Key from the AI Red Teaming platform

Bind the session id

In your scan driver, call setSessionId on each session with the same session id your tools report with. The call is set-once and valid any time before the session ends, which also covers targets that reveal their id only in the first response. For tool-response-poisoning scans, call it before you respond to the first message: Red binds the poison to the session after that first turn and fails the run if no id is bound by then.

await scan.run(async (session) => {
  for await (const msg of session) {
    const reply = await myAgent.send(msg.attack) // returns { sessionId, text }
    session.setSessionId(reply.sessionId) // set-once
    await msg.respond(reply.text)
  }
})

Test tool response poisoning

With tracing in place, you can run the tool-response-poisoning strategy. It checks whether your agent follows instructions planted in a tool result. Each attack is one session: a greeting, then a request that leads your agent to call a tool, whose result Red poisons. Bind the session id before you reply to the greeting, as in the handler above.

const scan = await client.createScan({
  name: "Tool poisoning",
  targetId: target.targetId,
  strategy: { name: "tool-response-poisoning", numberOfAttacksPerObjective: 5 },
  objectives: ["security.data-exfiltration.1"],
})

See Tool Response Poisoning for the options, supported targets, and how Red places the payload.

Reference

setSessionId / set_session_id

Binds the scan session to your session id. Set-once: callable any time before the session ends, idempotent, and errors only if you change an already-set id.

session.relaySessionId (session.relay_session_id in Python) is Red’s id for this session. session.sessionId (session.session_id in Python) is the id you set with setSessionId.