Skip to content

Python Library

ScoutML has two main Python interfaces:

  • track for decorators and simple logging
  • get_client() for direct API calls

Most users should start with track.

Use track

from scoutml import track

track.init(task="Track my agent", agent_id="demo-agent")

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

write_code()
track.complete()

Use The Client

from scoutml import get_client

client = get_client()

session = client.start_session(
    agent_id="demo-agent",
    task="Client example",
    description="Using the low-level client"
)

client.add_event(
    session["id"],
    "search",
    {"query": "session tracking"}
)

client.complete_session(
    session["id"],
    summary={"result": "done"}
)

Client Methods

start_session(...)

Creates a session.

session = client.start_session(
    agent_id="demo-agent",
    task="Build feature",
    description="Trying the SDK",
    metadata={"team": "agents"}
)

add_event(...)

Adds one action to a session.

client.add_event(
    session["id"],
    "code",
    {"file": "feature.py"},
    duration=120
)

complete_session(...)

Marks the session as finished.

client.complete_session(
    session["id"],
    summary={"result": "success"}
)

get_session(...)

Fetches the saved session.

saved = client.get_session(session["id"])
print(saved["status"])
print(len(saved["events"]))

Error Handling

from scoutml import ScoutMLError, AuthenticationError

try:
    session = client.start_session(agent_id="demo-agent", task="Test")
except AuthenticationError:
    print("Your API key is invalid.")
except ScoutMLError as exc:
    print(f"ScoutML error: {exc}")

Which One Should I Use?

Use track if:

  • you want the fastest setup
  • you already have Python functions you can decorate
  • you want automatic timing and error logging

Use get_client() if:

  • you want full control over when events are sent
  • you are building your own wrapper around the API