Skip to content
cadenya
Get started
API Reference
Agents

List agents

client.Agents.List(ctx, workspaceID, query) (*CursorPagination[Agent], error)
GET/v1/workspaces/{workspaceId}/agents

Lists all agents in the workspace

ParametersExpand Collapse
workspaceID string
query AgentListParams
BundleKey param.Field[string]Optional

Filter by bundle_key — return only resources owned by this bundle.

Cursor param.Field[string]Optional

Pagination cursor from previous response

IncludeInfo param.Field[bool]Optional

When true, the info field on each returned agent is populated. Requests with this flag count more against your rate limit.

Limit param.Field[int64]Optional

Maximum number of results to return

formatint32
Prefix param.Field[string]Optional

Filter expression (query param: prefix)

Query param.Field[string]Optional

Free-form search query

SortOrder param.Field[string]Optional

Sort order for results (asc or desc by creation time)

Status param.Field[AgentListParamsStatus]Optional

Filter by agent publication status

formatenum
const AgentListParamsStatusAgentStatusUnspecified AgentListParamsStatus = "AGENT_STATUS_UNSPECIFIED"
const AgentListParamsStatusAgentStatusDraft AgentListParamsStatus = "AGENT_STATUS_DRAFT"
const AgentListParamsStatusAgentStatusPublished AgentListParamsStatus = "AGENT_STATUS_PUBLISHED"
const AgentListParamsStatusAgentStatusArchived AgentListParamsStatus = "AGENT_STATUS_ARCHIVED"
VariationSelectionMode param.Field[AgentListParamsVariationSelectionMode]Optional

Filter by variation selection mode

formatenum
const AgentListParamsVariationSelectionModeVariationSelectionModeUnspecified AgentListParamsVariationSelectionMode = "VARIATION_SELECTION_MODE_UNSPECIFIED"
const AgentListParamsVariationSelectionModeVariationSelectionModeRandom AgentListParamsVariationSelectionMode = "VARIATION_SELECTION_MODE_RANDOM"
const AgentListParamsVariationSelectionModeVariationSelectionModeWeighted AgentListParamsVariationSelectionMode = "VARIATION_SELECTION_MODE_WEIGHTED"
ReturnsExpand Collapse
type Agent struct{…}

Agent resource

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

ID string

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

AccountID string

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

CreatedAt Time

Timestamp when this resource was created

formatdate-time
Name string

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

ProfileID string

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

WorkspaceID string

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

BundleKey stringOptional

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.

ExternalID stringOptional

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

Labels map[string, string]Optional

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

Agent specification (user-provided configuration)

Status AgentSpecStatus

Status of the agent

formatenum
One of the following:
const AgentSpecStatusAgentStatusUnspecified AgentSpecStatus = "AGENT_STATUS_UNSPECIFIED"
const AgentSpecStatusAgentStatusDraft AgentSpecStatus = "AGENT_STATUS_DRAFT"
const AgentSpecStatusAgentStatusPublished AgentSpecStatus = "AGENT_STATUS_PUBLISHED"
const AgentSpecStatusAgentStatusArchived AgentSpecStatus = "AGENT_STATUS_ARCHIVED"
VariationSelectionMode AgentSpecVariationSelectionMode

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

formatenum
One of the following:
const AgentSpecVariationSelectionModeVariationSelectionModeUnspecified AgentSpecVariationSelectionMode = "VARIATION_SELECTION_MODE_UNSPECIFIED"
const AgentSpecVariationSelectionModeVariationSelectionModeRandom AgentSpecVariationSelectionMode = "VARIATION_SELECTION_MODE_RANDOM"
const AgentSpecVariationSelectionModeVariationSelectionModeWeighted AgentSpecVariationSelectionMode = "VARIATION_SELECTION_MODE_WEIGHTED"
Description stringOptional

Description of the agent’s purpose

InputDataSchema map[string, unknown]Optional

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.

OutputDefinition map[string, unknown]Optional

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.

WebhookEventsURL stringOptional

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

Info AgentInfoOptional

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

CreatedBy ProfileOptional

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.

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…”)

AccountID 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

ProfileID string
ExternalID stringOptional

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

Labels map[string, string]Optional

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

Configuration for a profile.

Type ProfileSpecType

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

formatenum
One of the following:
const ProfileSpecTypeProfileTypeUnspecified ProfileSpecType = "PROFILE_TYPE_UNSPECIFIED"
const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"
const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"
const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"
Email stringOptional

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

Name stringOptional

Display name (e.g., “Bobby Tables”).

VariationCount int64Optional

List agents

package main

import (
  "context"
  "fmt"

  "github.com/cadenya/cadenya-go"
  "github.com/cadenya/cadenya-go/option"
)

func main() {
  client := cadenya.NewClient(
    option.WithAPIKey("My API Key"),
  )
  page, err := client.Agents.List(
    context.TODO(),
    "workspaceId",
    cadenya.AgentListParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

{
  "items": [
    {
      "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
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
Returns Examples
{
  "items": [
    {
      "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
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}