State and sessions

​

Scopes

​

The API

• Keys are 1–200 letters, digits and . _ : -.
• Values are any JSON up to 1 MiB (413 too_large). Write ids and amounts as strings: JSON numbers lose precision. NaN, numbers that overflow and strings containing NUL are refused.
• Compare-and-set: if_version makes a PUT conditional. 0 means “only if absent”. A mismatch is 409 version_conflict with the current_version; read again and retry.
• Append adds items to a list atomically, creating it if needed. 409 not_a_list when the value isn’t a list, 413 when the list would pass 1 MiB. Use it for conversation history, so two turns never overwrite each other.

​

With the SDKs

def chat(inv: agentos.Invocation):
    message = inv.input["message"]
    history = inv.state.session.append("history", [{"role": "user", "content": message}])
    reply = f"turn {(history.length + 1) // 2}: you said {message!r}"
    inv.state.session.append("history", [{"role": "assistant", "content": reply}])

    # compare-and-set loop: read, change, write; again if another run wrote in between
    visits = inv.state.agent.update("visits", lambda n: n + 1, default=0)
    return {"reply": reply, "visits": visits}

async chat(inv) {
  const message: string = inv.input.message;
  const history = await inv.state.session.append("history", [{ role: "user", content: message }]);
  const reply = `turn ${Math.floor((history.length + 1) / 2)}: you said '${message}'`;
  await inv.state.session.append("history", [{ role: "assistant", content: reply }]);

  const visits = await inv.state.agent.update<number>("visits", (n) => n + 1, { default: 0 });
  return { reply, visits };
},

• get(key, default) returns the value, or the default when the key is absent.
• get_versioned / getVersioned returns the value and its version. A key with no value gives (None, 0) / {value: undefined, version: 0}, and put(…, if_version=0) then writes only if it is still absent.
• put(key, value, if_version=…) raises VersionConflict (with current_version) on a mismatch.
• update(key, fn, default=…) is a compare-and-set loop: it reads, applies fn, and writes if nobody wrote in between, otherwise it tries again.

​

Sessions

• One turn runs at a time. Starting a turn while another is queued or running is refused with 409 session_busy. A held turn doesn’t block the session: once it is decided its resume may run while a newer turn runs, which is why history should be kept with append.
• The caller that created a session owns it; environment admins can use every session.

​

End users