Decorators¶

ScoutML is built around a few simple decorators.

Use them to mark what your agent is doing.

Core Decorators¶

`@track.code`¶

Use this for functions that create, edit, or generate code.

@track.code
def write_feature():
    return {"file": "feature.py"}

`@track.search`¶

Use this for search or retrieval steps.

@track.search
def search_web(query):
    return {"query": query, "results": 5}

`@track.tool("name")`¶

Use this for any other tool call.

@track.tool("browser")
def open_page(url):
    return {"url": url, "title": "Docs"}

`@track.action("custom_name")`¶

Use this when you want your own action type.

@track.action("plan")
def create_plan():
    return {"steps": ["search", "code", "test"]}

What Gets Logged¶

Each decorated function records:

the action name
the function name
the arguments
the keyword arguments
the return value
the duration
whether an error happened

Errors¶

If a decorated function raises an exception, ScoutML logs the action as an error and then re-raises the exception.

@track.code
def broken_step():
    raise ValueError("Something failed")

Manual Logging¶

You can also log actions yourself.

Log any action¶

track.log("search", {"query": "agent telemetry"})

Add a note¶

track.note("Switched to a smaller prompt")

Tips¶

Call track.init(...) once near the start of your script.
Use short, clear function names.
Return small dictionaries or simple values when possible.
Call track.complete(...) when the run finishes.
Use @track.tool("name") when code or search do not fit.

Example¶

from scoutml import track

track.init(task="Decorator guide example", agent_id="demo-agent")

@track.code
def write_code():
    return {"file": "main.py"}

@track.search
def search_docs(query):
    return {"query": query, "results": 2}

@track.tool("browser")
def open_page(url):
    return {"url": url}

write_code()
search_docs("python functions")
open_page("https://example.com")
track.note("All steps finished")
track.complete()