inspect-scout

Common errors

• AttributeError: module 'inspect_scout' has no attribute 'LogAgent'

  cause Attempting to use the `LogAgent` class, which was deprecated and removed in inspect-scout 0.4.0.
  fix Update your code to use the `@inspect_scout.inspect` decorator for tracing agent functions/methods.

• AttributeError: module 'inspect_scout' has no attribute 'start_transcript'

  cause Attempting to use the `start_transcript` context manager, which was deprecated and removed in inspect-scout 0.3.0.
  fix Update your code to use the `inspect_scout.transcript_session` context manager for tracing blocks of code.

• Transcripts are not generated or found in the expected location.

  cause The `inspect_scout.configure()` function was not called, or its `output_dir` parameter was not set correctly, leading to default or temporary storage that isn't easily accessible.
  fix Add `inspect_scout.configure(output_dir='path/to/your/transcript_folder')` at the beginning of your application to explicitly define where transcripts should be saved.

Warnings

• breaking The `LogAgent` class, used in versions prior to 0.4.0, has been removed and replaced by the `@inspect_scout.inspect` decorator.
  Fix: Migrate from `LogAgent` instances to decorating your agent functions/methods with `@inspect_scout.inspect(name="YourAgentName")`.
• breaking The `start_transcript` context manager, used in versions prior to 0.3.0, has been removed and replaced by `inspect_scout.transcript_session`.
  Fix: Replace `with inspect_scout.start_transcript(...)` with `with inspect_scout.transcript_session(...)`.
• gotcha Transcripts may not be saved or found in the expected location if `inspect_scout.configure()` is not called early in your application's lifecycle.
  Fix: Always call `inspect_scout.configure(output_dir='your/desired/path')` before any agent interactions to ensure transcripts are stored correctly. Defaults may vary or use temporary directories.
• gotcha Distinguishing between `@inspect_scout.inspect` and `inspect_scout.transcript_session`.
  Fix: `@inspect_scout.inspect` is a decorator for functions or methods that represent agent actions. `inspect_scout.transcript_session` is a context manager for explicitly tracing arbitrary blocks of code.

Install

• pip install inspect-scout Install stable version

Imports

• inspect
  wrong:

  import inspect_scout.inspect

  correct:

  from inspect_scout import inspect

  While `import inspect_scout.inspect` is syntactically valid, the decorator is typically imported directly as `inspect` for cleaner syntax when used as `@inspect`.
• transcript_session

  from inspect_scout import transcript_session

• configure

  from inspect_scout import configure

Quickstart

This quickstart demonstrates how to use `inspect-scout` to automatically capture transcripts of an AI agent's interactions using the `@inspect` decorator. It also shows the `transcript_session` context manager for manual tracing of code blocks and how to configure the output directory.

import inspect_scout
import os
import tempfile
import shutil

# Configure inspect-scout to save transcripts to a temporary directory
temp_dir = tempfile.mkdtemp()
inspect_scout.configure(output_dir=temp_dir, print_transcript_on_exit=False)
print(f"Transcripts will be saved to: {temp_dir}")

# Define a simple agent function
def my_agent_logic(input_text: str):
    if "hello" in input_text.lower():
        return "Hello there! How can I help you?"
    elif "tool" in input_text.lower():
        return "Simulating tool use..."
    return "I am a generic agent."

# Use the @inspect decorator to capture the agent's transcript
@inspect_scout.inspect(name="MyTestAgent")
def my_inspected_agent(input_text: str):
    print(f"Agent received: {input_text}")
    response = my_agent_logic(input_text)
    print(f"Agent responded: {response}")
    return response

if __name__ == "__main__":
    print("\n--- Running inspected agent ---")
    result1 = my_inspected_agent("Hello agent!")
    print(f"First call result: {result1}")

    result2 = my_inspected_agent("Tell me about tool use.")
    print(f"Second call result: {result2}")

    print("\n--- Running inspected block ---")
    with inspect_scout.transcript_session(name="ManualBlockSession"):
        print("Inside a manually traced block.")
        block_result = my_agent_logic("What's up?")
        print(f"Block agent result: {block_result}")

    # Clean up the temporary directory
    shutil.rmtree(temp_dir)
    print(f"\nCleaned up temporary directory: {temp_dir}")