Redact tool arguments and results

Keep the arguments or results of specific tools out of the telemetry your application sends to AIO, either by listing tools in a redaction policy or by marking a tool in code.

The model still receives every argument and result in full. Only the recorded copy changes. For what redaction is and how it works, see Redaction overview.

Before you begin

• Install and configure the Python SDK, as described in Instrument your code.
• Find the name each tool reports in telemetry. Tool names must match exactly.
• Call aio.init once at startup, before you create HTTP or model clients. A second call to aio.init doesn't apply a new policy.

Redact tool arguments

1. In your application's startup code, pass a policy to aio.init that lists the tools whose arguments you want to withhold:

import acceldata_aio_tracer as aio
aio.init(
    redaction=aio.redaction_policy(
        redact_tool_arguments=["data_fetch", "send_invoice"],
    ),
)

2. Replace data_fetch and send_invoice with the names your tools report in telemetry.
3. Restart your application.

After this change, the recorded copy of a listed tool's arguments looks like this:

• Tool spans: the arguments are replaced by a fingerprint, which is sha256: followed by 64 hexadecimal characters. A span that reports several tool names is withheld if any of them is on the list.
• Tool calls in messages: a listed tool's call keeps its name and ID, so you still see that the call happened. Its arguments are replaced by a fingerprint.
• Tool calls written into message text: some frameworks write a tool call into the message text instead of a separate tool call. For a listed tool, everything from the first such call to the end of the text is replaced by one fingerprint. Text before the call is kept. Text after it is lost.

The fingerprint isn't salted, so the same arguments always produce the same fingerprint. You can tell whether two calls used the same arguments without seeing them.

Mark a tool in code

Mark a tool with aio.redact_arguments to withhold its arguments without adding it to the policy list. Marked tools are added to the tools in redact_tool_arguments.

You can use aio.redact_arguments in three ways:

• As a decorator on a tool class.
• As a decorator with an explicit name=.
• As a plain call for a tool whose definition you don't control.

import acceldata_aio_tracer as aio
from pydantic import BaseModel
# Mark a tool class. The name comes from the default of its "name" field.
@aio.redact_arguments
class SQLQueryTool(BaseModel):
    name: str = "data_fetch"
# Mark a function and give the tool name explicitly.
@aio.redact_arguments(name="run_report")
def run_query(sql: str) -> list[dict]:
    return []
# Mark a tool you don't define yourself.
aio.redact_arguments(name="third_party_tool")
aio.init(
    redaction=aio.redaction_policy(
        redact_tool_results=["data_fetch"],
    ),
)

If you don't pass name=, the SDK looks for the tool name in this order:

1. The default value of a pydantic name field.
2. A string name attribute.
3. The object's __name__.

Keep these points in mind when you mark tools:

• Arguments only: a mark never withholds results. To withhold results, see Redact tool results.
• Whole process: a mark applies to the whole process.
• Import order: the module that defines a marked tool must be imported before that tool's spans are exported. A tool that's imported lazily isn't covered until it's first imported.

Redact tool results

Results have their own setting, because a tool's arguments can be proprietary while its results are the caller's own data. You can't mark a tool in code to withhold its results. Use the policy instead.

1. In your application's startup code, list the tools whose results you want to withhold:

import acceldata_aio_tracer as aio
aio.init(
    redaction=aio.redaction_policy(
        redact_tool_results=["customer_lookup"],
    ),
)

2. Replace customer_lookup with the name your tool reports in telemetry.
3. Restart your application.

After this change, a listed tool's results are withheld in two places:

• Tool spans: the result is replaced by a fingerprint.
• Tool turns in messages: the tool turn keeps its other fields, and its content is replaced by a fingerprint.

The SDK matches a tool turn to its tool by the call ID:

• Turn with a matching call ID: the turn is withheld only if that call's tool is on the list.
• Turn without a matching call ID: the turn is withheld whenever any tool is on the results list. This withholds more than you asked for, on purpose. LangChain tool turns don't carry an ID, so with LangChain every tool turn is withheld.

Set tool lists from environment variables

Instead of passing a policy in code, set either of these environment variables. Give a comma-separated list of tool names. Blank entries and extra spaces are ignored.

export AIO_REDACT_TOOL_ARGUMENTS="data_fetch,send_invoice"
export AIO_REDACT_TOOL_RESULTS="customer_lookup"

Check the result

1. Open a trace that includes a call to a redacted tool, as described in Explore traces.
2. In the waterfall, select the tool's step.
3. In the step pane, go to the Input / Output tab.

The tool step's input preview shows the arguments' fingerprint, sha256: followed by 64 hexadecimal characters, instead of the arguments.

Troubleshooting

A marked tool's arguments still appear

If the SDK can't find a name for a marked tool, it logs a warning like this one and doesn't mark the tool:

aio: @redact_arguments could not determine a tool name for <my_tools.Fetcher object at 0x10f3c2d90> — pass name= explicitly, or nothing will be redacted for it

Pass name= with the tool's name. Also check that the tool's module is imported before the tool runs.

Arguments or results of a listed tool still appear

Check that the name in your list matches the name the tool reports in telemetry exactly. If you set the lists with environment variables, check that you don't also pass redaction to aio.init.

Next steps

• Hide system prompts and tool definitions
• Redact by pattern
• Drop attributes and spans
• Python SDK