# Agents ## List agents `$ cadenya agents list` **get** `/v1/agents` Lists all agents in the workspace ### Parameters - `--cursor: optional string` Pagination cursor from previous response - `--include-info: optional boolean` When set to true you may use more of your alloted API rate-limit - `--limit: optional number` Maximum number of results to return - `--prefix: optional string` Filter expression (query param: prefix) - `--sort-order: optional string` Sort order for results (asc or desc by creation time) ### Returns - `ListAgentsResponse: object { items, pagination }` List agents response - `items: optional array of Agent` - `metadata: object { id, accountId, createdAt, 5 more }` 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: string` 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 - `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) - `externalId: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `status: "AGENT_STATUS_UNSPECIFIED" or "AGENT_STATUS_DRAFT" or "AGENT_STATUS_PUBLISHED" or "AGENT_STATUS_ARCHIVED"` Status of the agent - `"AGENT_STATUS_UNSPECIFIED"` - `"AGENT_STATUS_DRAFT"` - `"AGENT_STATUS_PUBLISHED"` - `"AGENT_STATUS_ARCHIVED"` - `variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" or "VARIATION_SELECTION_MODE_RANDOM" or "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: optional string` Description of the agent's purpose - `webhookEventsUrl: optional string` The URL that Cadenya will send events for any objective assigned to the agent. - `info: optional object { createdBy, variationCount }` AgentInfo contains simple information about an agent for display or quick reference - `createdBy: optional object { metadata, spec }` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `metadata: object { id, accountId, name, 3 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `variationCount: optional number` - `pagination: optional object { nextCursor, total }` - `nextCursor: optional string` - `total: optional number` ### Example ```cli cadenya agents list \ --api-key 'My API Key' ``` #### Response ```json { "items": [ { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "status": "AGENT_STATUS_UNSPECIFIED", "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED", "description": "description", "webhookEventsUrl": "webhookEventsUrl" }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "variationCount": 0 } } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Create a new agent `$ cadenya agents create` **post** `/v1/agents` Creates a new agent in the workspace ### Parameters - `--metadata: object { name, externalId, labels }` CreateResourceMetadata contains the user-provided fields for creating 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. - `--spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `--default-variation: optional object { metadata, spec, agentId }` Create agent variation request ### Returns - `agent: object { metadata, spec, info }` Agent resource - `metadata: object { id, accountId, createdAt, 5 more }` 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: string` 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 - `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) - `externalId: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `status: "AGENT_STATUS_UNSPECIFIED" or "AGENT_STATUS_DRAFT" or "AGENT_STATUS_PUBLISHED" or "AGENT_STATUS_ARCHIVED"` Status of the agent - `"AGENT_STATUS_UNSPECIFIED"` - `"AGENT_STATUS_DRAFT"` - `"AGENT_STATUS_PUBLISHED"` - `"AGENT_STATUS_ARCHIVED"` - `variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" or "VARIATION_SELECTION_MODE_RANDOM" or "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: optional string` Description of the agent's purpose - `webhookEventsUrl: optional string` The URL that Cadenya will send events for any objective assigned to the agent. - `info: optional object { createdBy, variationCount }` AgentInfo contains simple information about an agent for display or quick reference - `createdBy: optional object { metadata, spec }` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `metadata: object { id, accountId, name, 3 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `variationCount: optional number` ### Example ```cli cadenya agents create \ --api-key 'My API Key' \ --metadata '{name: name}' \ --spec '{status: AGENT_STATUS_UNSPECIFIED, variationSelectionMode: VARIATION_SELECTION_MODE_UNSPECIFIED}' ``` #### Response ```json { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "status": "AGENT_STATUS_UNSPECIFIED", "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED", "description": "description", "webhookEventsUrl": "webhookEventsUrl" }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "variationCount": 0 } } ``` ## Get an agent by ID `$ cadenya agents retrieve` **get** `/v1/agents/{id}` Retrieves an agent by ID from the workspace ### Parameters - `--id: string` Agent ID ### Returns - `agent: object { metadata, spec, info }` Agent resource - `metadata: object { id, accountId, createdAt, 5 more }` 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: string` 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 - `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) - `externalId: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `status: "AGENT_STATUS_UNSPECIFIED" or "AGENT_STATUS_DRAFT" or "AGENT_STATUS_PUBLISHED" or "AGENT_STATUS_ARCHIVED"` Status of the agent - `"AGENT_STATUS_UNSPECIFIED"` - `"AGENT_STATUS_DRAFT"` - `"AGENT_STATUS_PUBLISHED"` - `"AGENT_STATUS_ARCHIVED"` - `variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" or "VARIATION_SELECTION_MODE_RANDOM" or "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: optional string` Description of the agent's purpose - `webhookEventsUrl: optional string` The URL that Cadenya will send events for any objective assigned to the agent. - `info: optional object { createdBy, variationCount }` AgentInfo contains simple information about an agent for display or quick reference - `createdBy: optional object { metadata, spec }` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `metadata: object { id, accountId, name, 3 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `variationCount: optional number` ### Example ```cli cadenya agents retrieve \ --api-key 'My API Key' \ --id id ``` #### Response ```json { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "status": "AGENT_STATUS_UNSPECIFIED", "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED", "description": "description", "webhookEventsUrl": "webhookEventsUrl" }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "variationCount": 0 } } ``` ## Delete an agent `$ cadenya agents delete` **delete** `/v1/agents/{id}` Deletes an agent from the workspace ### Parameters - `--id: string` Agent ID ### Example ```cli cadenya agents delete \ --api-key 'My API Key' \ --id id ``` ## Update an agent `$ cadenya agents update` **patch** `/v1/agents/{id}` Updates an agent in the workspace ### Parameters - `--id: string` Agent ID (from path) - `--metadata: optional object { name, externalId, labels }` 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. - `--spec: optional object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `--update-mask: optional string` Fields to update ### Returns - `agent: object { metadata, spec, info }` Agent resource - `metadata: object { id, accountId, createdAt, 5 more }` 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: string` 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 - `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) - `externalId: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `status: "AGENT_STATUS_UNSPECIFIED" or "AGENT_STATUS_DRAFT" or "AGENT_STATUS_PUBLISHED" or "AGENT_STATUS_ARCHIVED"` Status of the agent - `"AGENT_STATUS_UNSPECIFIED"` - `"AGENT_STATUS_DRAFT"` - `"AGENT_STATUS_PUBLISHED"` - `"AGENT_STATUS_ARCHIVED"` - `variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" or "VARIATION_SELECTION_MODE_RANDOM" or "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: optional string` Description of the agent's purpose - `webhookEventsUrl: optional string` The URL that Cadenya will send events for any objective assigned to the agent. - `info: optional object { createdBy, variationCount }` AgentInfo contains simple information about an agent for display or quick reference - `createdBy: optional object { metadata, spec }` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `metadata: object { id, accountId, name, 3 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `variationCount: optional number` ### Example ```cli cadenya agents update \ --api-key 'My API Key' \ --id id ``` #### Response ```json { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "status": "AGENT_STATUS_UNSPECIFIED", "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED", "description": "description", "webhookEventsUrl": "webhookEventsUrl" }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "variationCount": 0 } } ``` ## Domain Types ### Agent - `agent: object { metadata, spec, info }` Agent resource - `metadata: object { id, accountId, createdAt, 5 more }` 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: string` 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 - `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) - `externalId: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `status: "AGENT_STATUS_UNSPECIFIED" or "AGENT_STATUS_DRAFT" or "AGENT_STATUS_PUBLISHED" or "AGENT_STATUS_ARCHIVED"` Status of the agent - `"AGENT_STATUS_UNSPECIFIED"` - `"AGENT_STATUS_DRAFT"` - `"AGENT_STATUS_PUBLISHED"` - `"AGENT_STATUS_ARCHIVED"` - `variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" or "VARIATION_SELECTION_MODE_RANDOM" or "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: optional string` Description of the agent's purpose - `webhookEventsUrl: optional string` The URL that Cadenya will send events for any objective assigned to the agent. - `info: optional object { createdBy, variationCount }` AgentInfo contains simple information about an agent for display or quick reference - `createdBy: optional object { metadata, spec }` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `metadata: object { id, accountId, name, 3 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `variationCount: optional number` ### Agent Info - `agent_info: object { createdBy, variationCount }` AgentInfo contains simple information about an agent for display or quick reference - `createdBy: optional object { metadata, spec }` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `metadata: object { id, accountId, name, 3 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `variationCount: optional number` ### Agent Spec - `agent_spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `status: "AGENT_STATUS_UNSPECIFIED" or "AGENT_STATUS_DRAFT" or "AGENT_STATUS_PUBLISHED" or "AGENT_STATUS_ARCHIVED"` Status of the agent - `"AGENT_STATUS_UNSPECIFIED"` - `"AGENT_STATUS_DRAFT"` - `"AGENT_STATUS_PUBLISHED"` - `"AGENT_STATUS_ARCHIVED"` - `variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" or "VARIATION_SELECTION_MODE_RANDOM" or "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: optional string` Description of the agent's purpose - `webhookEventsUrl: optional string` The URL that Cadenya will send events for any objective assigned to the agent. ### Page - `page: object { nextCursor, total }` - `nextCursor: optional string` - `total: optional number` # Webhook Deliveries ## List webhook deliveries `$ cadenya agents:webhook-deliveries list` **get** `/v1/agents/{agentId}/webhook_deliveries` Lists all webhook deliveries for an agent ### Parameters - `--agent-id: string` - `--cursor: optional string` Pagination cursor from previous response - `--event-type: optional "OBJECTIVE_EVENT_TYPE_UNSPECIFIED" or "OBJECTIVE_EVENT_TYPE_USER_MESSAGE" or "OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED" or 9 more` Optional filter by event type - `--limit: optional number` Maximum number of results to return - `--objective-id: optional string` Optional filter by objective ID ### Returns - `ListAgentWebhookDeliveriesResponse: object { items, pagination }` - `items: optional array of WebhookDelivery` - `data: object { agentId, attemptCount, eventType, 11 more }` Webhook delivery data - `agentId: string` Related resources - `attemptCount: number` - `eventType: "OBJECTIVE_EVENT_TYPE_UNSPECIFIED" or "OBJECTIVE_EVENT_TYPE_USER_MESSAGE" or "OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED" or 9 more` The type of objective event that triggered this webhook delivery - `"OBJECTIVE_EVENT_TYPE_UNSPECIFIED"` - `"OBJECTIVE_EVENT_TYPE_USER_MESSAGE"` - `"OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED"` - `"OBJECTIVE_EVENT_TYPE_TOOL_APPROVED"` - `"OBJECTIVE_EVENT_TYPE_TOOL_DENIED"` - `"OBJECTIVE_EVENT_TYPE_TOOL_CALLED"` - `"OBJECTIVE_EVENT_TYPE_SUB_OBJECTIVE_CREATED"` - `"OBJECTIVE_EVENT_TYPE_ERROR"` - `"OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE"` - `"OBJECTIVE_EVENT_TYPE_TOOL_RESULT"` - `"OBJECTIVE_EVENT_TYPE_TOOL_ERROR"` - `"OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED"` - `httpStatusCode: number` Response details (no response_body to avoid storing large payloads) - `lastAttemptAt: string` - `latencyMs: number` - `objectiveEventId: string` - `objectiveId: string` - `responseContentLength: string` Content length of the response body in bytes - `status: "WEBHOOK_DELIVERY_STATUS_UNSPECIFIED" or "WEBHOOK_DELIVERY_STATUS_PENDING" or "WEBHOOK_DELIVERY_STATUS_COMPLETED" or 2 more` - `"WEBHOOK_DELIVERY_STATUS_UNSPECIFIED"` - `"WEBHOOK_DELIVERY_STATUS_PENDING"` - `"WEBHOOK_DELIVERY_STATUS_COMPLETED"` - `"WEBHOOK_DELIVERY_STATUS_FAILED"` - `"WEBHOOK_DELIVERY_STATUS_DISABLED"` - `webhookId: string` - `webhookUrl: string` Webhook delivery details - `errorMessage: optional string` - `responseHeaders: optional map[string]` Response headers received from the webhook endpoint - `metadata: object { id, accountId, createdAt, 4 more }` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `id: string` Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...") - `accountId: string` Account this operation belongs to for multi-tenant isolation (prefixed ULID) - `createdAt: string` Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying - `profileId: string` ID of the actor (user or service account) that created this operation - `workspaceId: string` Workspace this operation belongs to for organizational grouping (prefixed ULID) - `externalId: optional string` External ID for the operation (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `pagination: optional object { nextCursor, total }` - `nextCursor: optional string` - `total: optional number` ### Example ```cli cadenya agents:webhook-deliveries list \ --api-key 'My API Key' \ --agent-id agentId ``` #### Response ```json { "items": [ { "data": { "agentId": "agentId", "attemptCount": 0, "eventType": "OBJECTIVE_EVENT_TYPE_UNSPECIFIED", "httpStatusCode": 0, "lastAttemptAt": "2019-12-27T18:11:19.117Z", "latencyMs": 0, "objectiveEventId": "objectiveEventId", "objectiveId": "objectiveId", "responseContentLength": "responseContentLength", "status": "WEBHOOK_DELIVERY_STATUS_UNSPECIFIED", "webhookId": "webhookId", "webhookUrl": "webhookUrl", "errorMessage": "errorMessage", "responseHeaders": { "foo": "string" } }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Domain Types ### Webhook Delivery - `webhook_delivery: object { data, metadata }` - `data: object { agentId, attemptCount, eventType, 11 more }` Webhook delivery data - `agentId: string` Related resources - `attemptCount: number` - `eventType: "OBJECTIVE_EVENT_TYPE_UNSPECIFIED" or "OBJECTIVE_EVENT_TYPE_USER_MESSAGE" or "OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED" or 9 more` The type of objective event that triggered this webhook delivery - `"OBJECTIVE_EVENT_TYPE_UNSPECIFIED"` - `"OBJECTIVE_EVENT_TYPE_USER_MESSAGE"` - `"OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED"` - `"OBJECTIVE_EVENT_TYPE_TOOL_APPROVED"` - `"OBJECTIVE_EVENT_TYPE_TOOL_DENIED"` - `"OBJECTIVE_EVENT_TYPE_TOOL_CALLED"` - `"OBJECTIVE_EVENT_TYPE_SUB_OBJECTIVE_CREATED"` - `"OBJECTIVE_EVENT_TYPE_ERROR"` - `"OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE"` - `"OBJECTIVE_EVENT_TYPE_TOOL_RESULT"` - `"OBJECTIVE_EVENT_TYPE_TOOL_ERROR"` - `"OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED"` - `httpStatusCode: number` Response details (no response_body to avoid storing large payloads) - `lastAttemptAt: string` - `latencyMs: number` - `objectiveEventId: string` - `objectiveId: string` - `responseContentLength: string` Content length of the response body in bytes - `status: "WEBHOOK_DELIVERY_STATUS_UNSPECIFIED" or "WEBHOOK_DELIVERY_STATUS_PENDING" or "WEBHOOK_DELIVERY_STATUS_COMPLETED" or 2 more` - `"WEBHOOK_DELIVERY_STATUS_UNSPECIFIED"` - `"WEBHOOK_DELIVERY_STATUS_PENDING"` - `"WEBHOOK_DELIVERY_STATUS_COMPLETED"` - `"WEBHOOK_DELIVERY_STATUS_FAILED"` - `"WEBHOOK_DELIVERY_STATUS_DISABLED"` - `webhookId: string` - `webhookUrl: string` Webhook delivery details - `errorMessage: optional string` - `responseHeaders: optional map[string]` Response headers received from the webhook endpoint - `metadata: object { id, accountId, createdAt, 4 more }` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `id: string` Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...") - `accountId: string` Account this operation belongs to for multi-tenant isolation (prefixed ULID) - `createdAt: string` Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying - `profileId: string` ID of the actor (user or service account) that created this operation - `workspaceId: string` Workspace this operation belongs to for organizational grouping (prefixed ULID) - `externalId: optional string` External ID for the operation (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} ### Webhook Delivery Data - `webhook_delivery_data: object { agentId, attemptCount, eventType, 11 more }` - `agentId: string` Related resources - `attemptCount: number` - `eventType: "OBJECTIVE_EVENT_TYPE_UNSPECIFIED" or "OBJECTIVE_EVENT_TYPE_USER_MESSAGE" or "OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED" or 9 more` The type of objective event that triggered this webhook delivery - `"OBJECTIVE_EVENT_TYPE_UNSPECIFIED"` - `"OBJECTIVE_EVENT_TYPE_USER_MESSAGE"` - `"OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED"` - `"OBJECTIVE_EVENT_TYPE_TOOL_APPROVED"` - `"OBJECTIVE_EVENT_TYPE_TOOL_DENIED"` - `"OBJECTIVE_EVENT_TYPE_TOOL_CALLED"` - `"OBJECTIVE_EVENT_TYPE_SUB_OBJECTIVE_CREATED"` - `"OBJECTIVE_EVENT_TYPE_ERROR"` - `"OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE"` - `"OBJECTIVE_EVENT_TYPE_TOOL_RESULT"` - `"OBJECTIVE_EVENT_TYPE_TOOL_ERROR"` - `"OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED"` - `httpStatusCode: number` Response details (no response_body to avoid storing large payloads) - `lastAttemptAt: string` - `latencyMs: number` - `objectiveEventId: string` - `objectiveId: string` - `responseContentLength: string` Content length of the response body in bytes - `status: "WEBHOOK_DELIVERY_STATUS_UNSPECIFIED" or "WEBHOOK_DELIVERY_STATUS_PENDING" or "WEBHOOK_DELIVERY_STATUS_COMPLETED" or 2 more` - `"WEBHOOK_DELIVERY_STATUS_UNSPECIFIED"` - `"WEBHOOK_DELIVERY_STATUS_PENDING"` - `"WEBHOOK_DELIVERY_STATUS_COMPLETED"` - `"WEBHOOK_DELIVERY_STATUS_FAILED"` - `"WEBHOOK_DELIVERY_STATUS_DISABLED"` - `webhookId: string` - `webhookUrl: string` Webhook delivery details - `errorMessage: optional string` - `responseHeaders: optional map[string]` Response headers received from the webhook endpoint