set_semantic_state | SignalWire

Set the semantic state that semantic gates read as semantic_state, alongside the conversation. The state is stored at global_data.semantic_state.

Each call replaces the whole state. To change one field, send the whole state with that field changed; send {} to reset it. Keep it to what your application has established, such as a total it computed or an order the caller confirmed, rather than what the caller claims. No other global data reaches the decision model as state, though a gate question can still bring in a value with a ${global_data...} variable.

This is shorthand for update_global_data({"semantic_state": state}).

Parameters

state

dict[str, Any]Required

The new semantic state.

Returns

FunctionResult — self, for chaining.

Examples

from signalwire import AgentBase, FunctionResult, SemanticGate
agent = AgentBase(name="pizza-agent", route="/pizza")
agent.set_prompt_text("You take pizza orders. Quote the total before placing the order.")
PRICES = {"small": 12.00, "medium": 15.00, "large": 18.00}
@agent.tool(
    description="Quote the total for a pizza order",
    parameters={
        "type": "object",
        "properties": {
            "size": {"type": "string", "enum": list(PRICES)},
            "quantity": {"type": "integer"},
        },
        "required": ["size", "quantity"],
    },
)
def quote_order(args, raw_data):
    total = f"${PRICES[args['size']] * args['quantity']:.2f}"
    return (
        FunctionResult(f"The total is {total}. Read it to the caller and ask them to confirm.")
        .set_semantic_state({"quoted_total": total})
    )
@agent.tool(
    description="Place the quoted pizza order",
    gates=[
        SemanticGate(
            "Has the caller agreed in `conversation` to pay the total in `semantic_state`?",
            threshold=0.9,
            on_fail="place_order was not run. Read the total to the caller and ask them to confirm it.",
        )
    ],
)
def place_order(args, raw_data):
    return FunctionResult("The order is placed. Tell the caller it will be ready in 20 minutes.")
agent.serve()