## Update an agent

`agents.update(id, **kwargs) -> Agent`

**patch** `/v1/workspaces/{workspaceId}/agents/{id}`

Updates an agent in the workspace

### Parameters

- `workspace_id: String`

- `id: String`

- `metadata: UpdateResourceMetadata`

  UpdateResourceMetadata contains the user-provided fields for updating
  a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id,
  created_at) are excluded since they are set by the server.

  - `name: String`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")

  - `bundle_key: String`

    Optional bundle ownership key. See ResourceMetadata.bundle_key.

  - `external_id: String`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

- `spec: AgentSpec`

  Agent specification (user-provided configuration)

  - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

    Status of the agent

    - `:AGENT_STATUS_UNSPECIFIED`

    - `:AGENT_STATUS_DRAFT`

    - `:AGENT_STATUS_PUBLISHED`

    - `:AGENT_STATUS_ARCHIVED`

  - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

    Controls how variations are automatically selected when creating objectives
    Defaults to RANDOM when unspecified

    - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

    - `:VARIATION_SELECTION_MODE_RANDOM`

    - `:VARIATION_SELECTION_MODE_WEIGHTED`

  - `description: String`

    Description of the agent's purpose

  - `input_data_schema: Hash[Symbol, untyped]`

    InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation
    prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as the tool's input parameter schema. If omitted,
    the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.

  - `output_definition: Hash[Symbol, untyped]`

    Optional output definition for objectives created for this agent.
    When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here.
    Use this option when you want structured data to be created by your objectives.

  - `webhook_events_url: String`

    The URL that Cadenya will send events for any objective assigned to the agent.

- `update_mask: String`

  Fields to update

### Returns

- `class Agent`

  Agent resource

  - `metadata: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentSpec`

    Agent specification (user-provided configuration)

    - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

      Status of the agent

      - `:AGENT_STATUS_UNSPECIFIED`

      - `:AGENT_STATUS_DRAFT`

      - `:AGENT_STATUS_PUBLISHED`

      - `:AGENT_STATUS_ARCHIVED`

    - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

      Controls how variations are automatically selected when creating objectives
      Defaults to RANDOM when unspecified

      - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

      - `:VARIATION_SELECTION_MODE_RANDOM`

      - `:VARIATION_SELECTION_MODE_WEIGHTED`

    - `description: String`

      Description of the agent's purpose

    - `input_data_schema: Hash[Symbol, untyped]`

      InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation
      prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as the tool's input parameter schema. If omitted,
      the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.

    - `output_definition: Hash[Symbol, untyped]`

      Optional output definition for objectives created for this agent.
      When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here.
      Use this option when you want structured data to be created by your objectives.

    - `webhook_events_url: String`

      The URL that Cadenya will send events for any objective assigned to the agent.

  - `info: AgentInfo`

    AgentInfo contains simple information about an agent for display or quick reference

    - `created_by: Profile`

      A profile identifies a user or non-human principal (such as an API key)
      at the account level. Profiles are account-scoped and can be granted access
      to multiple workspaces.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `variation_count: Integer`

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

agent = cadenya.agents.update("id", workspace_id: "workspaceId")

puts(agent)
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "status": "AGENT_STATUS_UNSPECIFIED",
    "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED",
    "description": "description",
    "inputDataSchema": {
      "foo": "bar"
    },
    "outputDefinition": {
      "foo": "bar"
    },
    "webhookEventsUrl": "webhookEventsUrl"
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "variationCount": 0
  }
}
```