> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lakera.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lakera.ai/_mcp/server.

# 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](/docs/red/trace-agent-tools) — then bind the id here.

## Prerequisites

* An agent runtime instrumented for tracing, per
  [Trace Agent Tools](/docs/red/trace-agent-tools)
* A scan you run with the SDK — see the [Quickstart](/docs/red/sdk-quickstart)
* A Red Team API Key from the [AI Red Teaming platform](https://red.lakera.ai)

## 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`](/docs/red/sdk-reference#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.

#### TypeScript

```typescript
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)
  }
})
```

#### Python

```python
async def handler(session):
    async for msg in session:
        reply = await my_agent.send(msg.attack)  # returns {session_id, text}
        session.set_session_id(reply.session_id)  # set-once
        await msg.respond(reply.text)

await scan.run(handler)
```

> **Note**
>
> Targets you connect in the AI Red Teaming platform don't need this — Red captures the
> target's session id and associates tool activity with the scan automatically.

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

#### TypeScript

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

#### Python

```python
from lakera_red_sdk import ToolResponsePoisoningStrategyOptions

scan = await client.create_scan(
    target.target_id,
    name="Tool poisoning",
    strategy=ToolResponsePoisoningStrategyOptions(number_of_attacks_per_objective=5),
    objectives=["security.data-exfiltration.1"],
)
```

See [Tool Response Poisoning](/docs/red/sdk-reference#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`.