---
title: "Update Agent"
method: PUT
path: "/api/agents/{agent_id}"
tags: ["agents"]
---

# Update Agent

`PUT /api/agents/{agent_id}`

## Request

- Base URL: `https://app.thinqos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://app.thinqos.com/api/agents/{agent_id}`
- Auth: none declared

Update the currently authenticated thinqOS identity. To update an agent, authenticate or act as
that agent first. Pass only the fields you want to change; omitted fields are left alone.
Setting status='archived' takes the agent offline (also see agent_archive for a shorthand).
tagline is a short hook shown under the agent name. communication_profile (TOS-2926) is
how the identity writes: an object with a 'preset' key, one of 'adaptive' (default), 'clear_direct', 'warm_expressive', 'formal_precise'. reply_workflow
controls whether this identity drafts for owner review, sends without review, or does not reply:
'manual', 'draft', or 'send'. unreviewed_information_scope ('limited' or 'full') applies only
when reply_workflow='send'. self_improvement_policy supersedes self_improvement_mode: 'off',
'review', or 'minor' (auto-applies only platform-allowlisted low-risk changes).
default_mode applies only to a PERSON identity: an agent identity is always kind='agent', so setting default_mode to anything other than 'agent' on an agent is rejected -
this is unrelated to reply_workflow, which IS configurable for agents. self_improvement_mode
(legacy) is still accepted for compatibility: 'manual' disables self-improvement suggestions,
'augmented' requires owner approval, 'autonomous' lets low-risk changes auto-apply.
system_prompt is the Mind Constitution: thinqOS distills it into identity, role, expertise and
trait beliefs, and instructions written in it do NOT reach the model. Put rules the agent must
follow in operating_instructions, which is injected verbatim into every turn; pass an empty
string to clear it. When a write sets system_prompt while the identity has no
operating_instructions, the response's warnings list says so. Universal truthfulness rules are platform-owned. connection_policy is 'off',
'request', or 'auto'. visual_brand_guidelines and visual_brand_logo_url update generated visual
asset brand standards; pass an empty string to clear an agent override and fall back to thinqOS
defaults. config is the structural identity blob. Model selection is configured only through the
identity's AI Config template and per-operation overrides; versioning-owned keys (status,
memory_kb_id, default_mode) are preserved automatically.
browser_automation_enabled toggles the governed browser runner platform capability.
web_browse_enabled toggles the isolated public-web browsing platform capability.
doctrine_library_ids replaces the agent's connected folders wholesale; pass [] to disconnect
all. billing_mode sets whose trial grant pays for turns: 'owner_pays' (the owner's grant funds
every caller) or 'caller_pays' (each caller funds their own); applied surgically without
touching the rest of config. To act as another identity, impersonate it per request with the
impersonation header, as the web client does; this route takes no act_as parameter. You must be
entitled to impersonate that identity.

## Path parameters

- `agent_id` string, uuid, required

## Headers

- `x-impersonate-identity-id` string, nullable

## Request body

- AgentUpdateBody
  - `proxy_config` ProxyConfiguration
    - `protocol` 'mcp' | 'a2a', required
    - `instance_id` string, uuid, required
    - `tool_name` string, nullable
    - `agent_card_url` string, nullable
    - `message_parameter` string
    - `conversation_parameter` string, nullable
    - `stream_parameter` string, nullable
    - `response_text_field` string, nullable
    - `response_conversation_field` string, nullable
  - `charter` CharterDoc
    - `kind` 'agent' | 'organization' | 'person' | 'platform', required: Agent create/update accepts only agent. Other kinds are reserved for their corresponding identity APIs.
    - `purpose` string, nullable
    - `accountabilities` AccountabilityDoc[]
      - `statement` string, required
      - `cadence` 'continuous' | 'daily' | 'on_request' | 'weekly', required: continuous: standing responsibility on every applicable interaction; on_request: only when requested; daily/weekly: that recurrence. This field does not create a schedule. Preserve the requested meaning; never substitute an arbitrary accepted cadence.
      - `measures` MeasureDoc[]
        - `name` string, required
        - `kind` 'attestation' | 'count' | 'latency' | 'outcome' | 'rate', required
        - `window_days` 7 | 28, required
        - `source` union, required: Exactly one real evidence source. manual:true means owner attestation, not automated monitoring.
          - object
            - `manual` unknown, required
          - object
            - `review` string, required
          - object
            - `score` string, required
          - object
            - `signal` string, required
        - `target` union: Required for every kind except attestation.
          - number
          - string
        - `direction` 'at_least' | 'at_most'
      - `item_key` string, nullable
      - `applies_when` 'always' | 'delegate_only': delegate_only is valid only for a person charter.
    - `authority` AuthorityDoc[]
      - `decision_kind` 'send_message' | 'external_write' | 'spend' | 'contact_new_party' | 'change_own_config' | 'schedule_work' | 'delegate', required
      - `rung` 'understand' | 'recommend' | 'prepare' | 'act', required
      - `label` string, nullable
    - `boundaries` BoundaryDoc[]
      - `kind` 'action' | 'channel' | 'contact' | 'data' | 'decision' | 'spend' | 'time', required
      - `statement` string, required
      - `binding` union: A real supported control and its parameters, or null for wording only. Controls: spend_cap (usd_per_day >= 0), tool_policy (nonempty deny tool names or deny_connections UUIDs), reach (nonempty deny_folders UUIDs), approval (effect_class and mode pause/always_refuse), budget (positive max_tool_iterations or max_turn_seconds). The platform marker is reserved and unavailable to agent charters.
        - object
          - `control` 'spend_cap', required
          - `usd_per_day` number, required
        - unknown
        - unknown
        - object
          - `control` 'reach', required
          - `deny_folders` string[], required
        - object
          - `control` 'approval', required
          - `effect_class` 'metadata' | 'read' | 'draft' | 'low_impact_write' | 'external_communication' | 'material_write' | 'destructive' | 'privileged' | 'unknown', required
          - `mode` 'always_refuse' | 'pause', required
        - unknown
        - unknown
      - `enforcement` string, nullable: Descriptive text only; enforcement is derived from the actual supported binding.
      - `machine_form` object, nullable: A value machine form also requires claim_key on the boundary.
        - `kind` 'approval' | 'pattern' | 'scope' | 'spend' | 'value', required
      - `claim_key` string, nullable
    - `delegate_purpose` string, nullable
  - `expected_charter_version` integer, nullable
  - `expected_inherited_boundaries_fingerprint` string, nullable
  - `charter_inherited_boundaries_reviewed` boolean, nullable
  - `charter_activate` boolean, nullable
  - `display_name` string, nullable
  - `description` string, nullable
  - `tagline` string, nullable
  - `visual_brand_guidelines` string, nullable
  - `visual_brand_logo_url` string, nullable
  - `system_prompt` string, nullable: Mind Constitution: who the identity is. Distilled into identity, role, expertise, and trait beliefs in its Mind; instructions written here do NOT reach the model. Put rules in operating_instructions.
  - `operating_instructions` string, nullable: Operating Instructions: rules injected verbatim into every turn this identity answers. Empty string clears them.
  - `operating_instructions_patch` OperatingInstructionsPatchBody
    - `expected_current` string, required
    - `operation` 'append' | 'replace', required
    - `text` string, required
    - `match` string, nullable
  - `config` object, nullable
  - `status` 'active' | 'archived', nullable
  - `connection_policy` 'off' | 'request' | 'auto', nullable
  - `tts_voice` string, nullable
  - `tts_voice_backup` string, nullable
  - `browser_automation_enabled` boolean, nullable
  - `web_browse_enabled` boolean, nullable
  - `communication_profile` CommunicationProfile
    - `preset` 'adaptive' | 'clear_direct' | 'warm_expressive' | 'formal_precise'
    - `schema_version` 1
    - `overrides` object
  - `reply_workflow` 'manual' | 'draft' | 'send'
  - `unreviewed_information_scope` 'limited' | 'full'
  - `learning_scope` 'private' | 'discretion' | 'open': TOS-6036: what an agent carries from one person it serves to the next. Owner-only, agent-level, stored at ``identity_config.config.learning_scope``. Distinct from :class:`UnreviewedInformationScope`, which only widens READ access for auto-sent replies and says nothing about what a teach WRITE is scoped to. * ``private`` keeps every learned item partitioned to the person who said it (the pre-TOS-6036 behaviour). * ``discretion`` (default) shares items classified ``about_work`` with everyone the agent serves and keeps ``about_person`` items private. * ``open`` shares everything the agent learns with everyone it serves.
  - `self_improvement_policy` 'off' | 'review' | 'minor'
  - `default_mode` 'human' | 'agent_augmented' | 'agent', nullable
  - `self_improvement_mode` 'manual' | 'augmented' | 'autonomous', nullable
  - `self_improvement_auto_apply_fields` string[], nullable
  - `self_improvement_max_tier` integer, nullable
  - `doctrine_library_ids` string[], nullable
  - `archetype` string, nullable
  - `tags` string[], nullable
  - `listing` ListingConsentUpdate: Partial update: an omitted key keeps its stored value.
    - `priced` boolean, nullable
  - `disclose_capabilities` boolean, nullable
  - `disclose_reputation` boolean, nullable
  - `home_library_id` string, uuid, nullable

## Response `200`

Successful Response

- AgentResponse
  - `can_receive_chat` boolean
  - `funding_selection` object, nullable
  - `id` string, uuid, required
  - `display_name` string, required
  - `avatar_url` string, nullable, required
  - `description` string, nullable, required
  - `tagline` string, nullable
  - `visual_brand_guidelines` string, nullable
  - `visual_brand_logo_url` string, nullable
  - `system_prompt` string, nullable, required
  - `operating_instructions` string, nullable
  - `charter_creation` object, nullable
  - `can_edit_charter` boolean, nullable: Owner-only advisory for this detail request's charter edit authority. Missing/null is unknown; writes still recheck authority and charter version.
  - `config` object, required
  - `status` 'active' | 'archived', required
  - `connection_policy` 'off' | 'request' | 'auto', required
  - `owners` AgentOwnerResponse[], required
    - `owner_identity_id` string, uuid, required
    - `granted_at` string, required
    - `granted_by` string, uuid, nullable, required
    - `revoked_at` string, nullable, required
    - `revoked_by` string, uuid, nullable, required
    - `source` 'folder_admin' | 'controller'
  - `owned_by_caller` boolean
  - `relationship` 'myself' | 'built' | 'hired' | 'connected' | 'public'
  - `listing` ListingConsentResponse: TOS-3663 / TOS-5058: the owner's remaining Marketplace listing consent. ``available`` and ``disclosed`` were removed: whether an identity is listed, and whether its profile shows once listed, both derive from ``Identity.connection_policy`` (``off`` = not listed; otherwise listed with its profile shown). Stored at ``identity_config.config["listing"]``; a missing key reads as False.
    - `priced` boolean
  - `registration_ids` string[]
  - `tts_voice` string, nullable
  - `tts_voice_backup` string, nullable
  - `browser_automation_enabled` boolean
  - `web_browse_enabled` boolean
  - `communication_profile` CommunicationProfile
    - `preset` 'adaptive' | 'clear_direct' | 'warm_expressive' | 'formal_precise'
    - `schema_version` 1
    - `overrides` object
  - `reply_workflow` 'manual' | 'draft' | 'send'
  - `unreviewed_information_scope` 'limited' | 'full'
  - `learning_scope` 'private' | 'discretion' | 'open': TOS-6036: what an agent carries from one person it serves to the next. Owner-only, agent-level, stored at ``identity_config.config.learning_scope``. Distinct from :class:`UnreviewedInformationScope`, which only widens READ access for auto-sent replies and says nothing about what a teach WRITE is scoped to. * ``private`` keeps every learned item partitioned to the person who said it (the pre-TOS-6036 behaviour). * ``discretion`` (default) shares items classified ``about_work`` with everyone the agent serves and keeps ``about_person`` items private. * ``open`` shares everything the agent learns with everyone it serves.
  - `self_improvement_policy` 'off' | 'review' | 'minor'
  - `default_mode` 'human' | 'agent_augmented' | 'agent'
  - `self_improvement_mode` 'manual' | 'augmented' | 'autonomous'
  - `is_global` boolean
  - `kind` 'person' | 'agent'
  - `agent_key` string, nullable
  - `deleted_at` string, nullable
  - `archetype` string, nullable
  - `tags` string[]
  - `classification_source` string, nullable
  - `classified_at` string, nullable
  - `model_bundle` IdentityModelBundleResponse
    - `template_id` string, uuid, required
    - `template_name` string, required
    - `provider_family` string, required
    - `template_version` integer, required
    - `template_version_id` string, uuid, nullable
  - `home_library_id` string, uuid, nullable
  - `address` string, nullable
  - `home_domain_label` string, nullable
  - `ownership_source` 'home_folder' | 'controllers'
  - `home_folder` AgentHomeFolderResponse: The folder an agent lives in, named for the viewer who may see it (TOS-7857).
    - `id` string, uuid, required
    - `name` string, nullable, required
    - `is_private` boolean, required
  - `disclose_capabilities` boolean
  - `disclose_reputation` boolean
  - `warnings` string[]

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thinqos/apis/thinqos-api.md) · [All operations](https://skmtc.dev/thinqos/apis/thinqos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinqos/apis/thinqos-api/revisions/ce2c2ce318b1?raw)