Skip to main content

Agent Defaults Update

[MODE:SIDEEFFECTS] Tier: base. Not idempotent (last write wins).

Replaces (not merges) the Player's agent_defaults JSON through PATCH /api/agent_defaults. Requires API key scope agents:write. Concurrent updates are serialized by the server.

When to use​

  • Setting platform-wide LLM provider/model preference.
  • Configuring provider_overrides (per-provider API keys / endpoints).
  • Updating runtime tuning fields — temperature, max_tokens, system prompt, etc.

When NOT to use​

  • Tweaking a single Agent — use fibe_resource_mutate(resource:"agent", operation:"update").
  • Resetting to admin defaults — use fibe_agent_defaults_reset.

Inputs​

FieldTypeRequiredNotes
agent_defaultsobjectyesReplacement JSON (full state)

Output​

The updated payload (same shape as fibe_agent_defaults_get).

Behavior​

  1. Authorizes via agents:write API key scope.
  2. Normalizes the payload (deep-stringifies keys, converts inline provider_args_cli strings into structured provider_args).
  3. Locks the Player row.
  4. Writes the new defaults atomically.

Gotchas​

  • Replacement, not merge. To keep existing fields, fetch current via fibe_agent_defaults_get first, deep-merge yourself, then send.
  • provider_overrides may include API keys — make sure you're connected to the right tenant.
  • Without agents:write scope: 403.
  • A missing or non-object agent_defaults payload returns 400; an invalid websocket_max_connections (must be a positive integer) returns 422.
  • Existing Agents that already have explicit overrides keep them; defaults only apply to fields NOT set on the Agent.
  • fibe_agent_defaults_get — read current state first.
  • fibe_agent_defaults_reset — start over.
  • fibe_resource_mutate(resource:"agent", operation:"update") — per-Agent overrides.