Support State Store inspection and item management in azd ai agent

Background

Hosted agents can use Foundry State Stores to persist checkpoints and other application data beyond an individual request or process. Developers need a way to inspect this data, seed or replace test values, and delete individual items without adding diagnostic endpoints to their agents.

Expose these operations through azd ai agent state-stores, with one active store per agent to avoid repeating a store name on every item command. This proposal covers existing stores only. Store creation, updates, and deletion remain the responsibility of agent code or other tooling.

Reading materials

• AgentServer State Store guide: store lifecycle, JSON values, user isolation, item operations, ETags, and pagination.
• Foundry State Store REST contract proposal: the external agent-scoped data-plane API.

CLI overview

API paths below are relative to the Foundry project endpoint. {store} and {key} are base64url-encoded by azd. CLI arguments are the original logical names, including names containing /.

[...] denotes optional arguments; A | B denotes mutually exclusive alternatives. --tag is repeatable.

# GET /agents/{agent}/endpoint/state_stores
azd ai agent state-stores list
    [--limit <count>]
    [--order <asc|desc>]
    [--after <cursor> | --before <cursor>]

# GET /agents/{agent}/endpoint/state_stores/{store}
# Validate the named store, then save its name as the active store locally.
# Without a name: GET the store collection for a picker, then GET the selected store.
azd ai agent state-stores select [store-name]

# GET /agents/{agent}/endpoint/state_stores/{store}
# Use the active store when the name is omitted.
azd ai agent state-stores show [store-name]

# GET /agents/{agent}/endpoint/state_stores/{store}/items:keys
# Return keys and metadata, not item values.
azd ai agent state-stores items list
    [--store <store-name>]
    [--limit <count>]
    [--order <asc|desc>]
    [--after <cursor> | --before <cursor>]

# GET /agents/{agent}/endpoint/state_stores/{store}/items/{key}
azd ai agent state-stores items show <key>
    [--store <store-name>]

# PUT /agents/{agent}/endpoint/state_stores/{store}/items/{key}
# Upsert: create a missing item or replace an existing item; no CLI existence probe.
# With --if-match, send the supplied ETag in the If-Match header.
azd ai agent state-stores items set <key>
    (--value <json-object> | --value-file <path|->)
    [--store <store-name>]
    [--tag <key=value>]...
    [--if-match <etag>]

# DELETE /agents/{agent}/endpoint/state_stores/{store}/items/{key}
# With --if-match, send the supplied ETag in the If-Match header.
azd ai agent state-stores items delete <key>
    [--store <store-name>]
    [--if-match <etag>]
    [--yes]

There is no state-stores create|update|delete, or separate items create command in this scope.

Examples

The following examples assume the agent has already created stores named checkpoints/run-42 and checkpoints/run-43. Store names and item keys are application-defined; azd does not infer them from invocation or session IDs.

# Discover the agent's existing stores
azd ai agent state-stores list --output table

# Select a store once for subsequent item commands
azd ai agent state-stores select "checkpoints/run-42"

# Inspect the active store and its item keys
azd ai agent state-stores show
azd ai agent state-stores items list --output table

# Read a full item, including its JSON value, tags, and ETag
azd ai agent state-stores items show "task-123"

# Create or replace a test item in the existing store
azd ai agent state-stores items set "test-checkpoint" \
  --value '{"step":1,"status":"pending"}' \
  --tag kind=checkpoint

# Replace the item from a file, conditional on the ETag just read
# checkpoint.json contains only the JSON object value, not a REST request envelope.
ETAG=$(azd ai agent state-stores items show "test-checkpoint" | jq -r '.etag')
azd ai agent state-stores items set "test-checkpoint" \
  --value-file checkpoint.json \
  --tag kind=checkpoint \
  --if-match "$ETAG"

# Inspect another store without changing the active selection
azd ai agent state-stores items show "task-456" \
  --store "checkpoints/run-43"

# Fetch the next page only when the first page reports more results
PAGE=$(azd ai agent state-stores items list --limit 20 --order asc)
if [ "$(printf '%s' "$PAGE" | jq -r '.has_more')" = "true" ]; then
  LAST_ID=$(printf '%s' "$PAGE" | jq -r '.last_id')
  azd ai agent state-stores items list \
    --limit 20 --order asc --after "$LAST_ID"
fi

# Delete only the test item, without a confirmation prompt
azd ai agent state-stores items delete "test-checkpoint" --yes

# Select an agent service in a multi-agent project
azd ai agent state-stores list --agent-name worker

# Explicit targeting also works outside an azd project
azd ai agent state-stores items show "task-123" \
  --agent-endpoint "$AGENT_ENDPOINT" \
  --store "checkpoints/run-42"