Tools that use the State

A tool can read or change the run it is part of.

from alpineagents import State, tool


@tool
def remember(key: str, value: str, state: State) -> str:
    """Save a note for later in this run"""
    state.data.setdefault("notes", {})[key] = value
    return f"Saved {key}"


@tool
def recall(key: str, state: State) -> str:
    """Read a note saved with remember"""
    return state.data.get("notes", {}).get(key, f"No note named {key}")

1. A parameter typed State is hidden from the model. The model sees remember(key, value) and recall(key).
2. When the tool runs, that parameter receives the current State.
3. state.data keeps values across turns. The model never sees it.

What a tool can do with the State

Call	Effect
state.data[...]	Read or keep your own values
state.finish(answer)	End the run after this turn. See Stop conditions
state.add_notice(text)	Tell the model something. It goes into the context right after this turn's results
state.answer, state.turn, state.usage, ...	Read the run

Thread safety

Tools in one turn can run at the same time on worker threads. Every State method is thread-safe. For an update to state.data in several steps, hold state.lock. See State: your own data.

Related

• State
• Tools