Agents

AgentService manages AI agents at the WORKSPACE level. Agents are workspace-scoped resources that define AI behavior and tool access. All operations are implicitly scoped to the workspace determined by the JWT token.

Authentication: Bearer token (JWT) Scope: Workspace-level operations

List agents

client.Agents.List(ctx, query) (*CursorPagination[Agent], error)

GET/v1/agents

Create a new agent

client.Agents.New(ctx, body) (*Agent, error)

POST/v1/agents

Get an agent by ID

client.Agents.Get(ctx, id) (*Agent, error)

GET/v1/agents/{id}

Delete an agent

client.Agents.Delete(ctx, id) error

DELETE/v1/agents/{id}

Update an agent

client.Agents.Update(ctx, id, body) (*Agent, error)

PATCH/v1/agents/{id}

ModelsExpand Collapse

type Agent struct{…}

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...")

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)

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"}

Spec AgentSpec

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

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

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 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...")

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"}

Spec ProfileSpec

ProfileSpec contains the profile-specific fields

Type ProfileSpecType

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum

One of the following:

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 user (required, unique per account)

Name stringoptional

Display name for the user (e.g., "Bobby Tables")

VariationCount int64optional

type AgentInfo struct{…}

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

CreatedBy Profileoptional

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...")

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"}

Spec ProfileSpec

ProfileSpec contains the profile-specific fields

Type ProfileSpecType

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum

One of the following:

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 user (required, unique per account)

Name stringoptional

Display name for the user (e.g., "Bobby Tables")

VariationCount int64optional

type AgentSpec struct{…}

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

WebhookEventsURL stringoptional

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

type Page struct{…}

NextCursor stringoptional

Total int64optional

AgentsWebhook Deliveries

Authentication: Bearer token (JWT) Scope: Workspace-level operations

List webhook deliveries

client.Agents.WebhookDeliveries.List(ctx, agentID, query) (*CursorPagination[WebhookDelivery], error)

GET/v1/agents/{agentId}/webhook_deliveries

ModelsExpand Collapse

type WebhookDelivery struct{…}

Data WebhookDeliveryData

Webhook delivery data

AgentID string

Related resources

AttemptCount int64

EventType WebhookDeliveryDataEventType

The type of objective event that triggered this webhook delivery

formatenum

One of the following:

const WebhookDeliveryDataEventTypeObjectiveEventTypeUnspecified WebhookDeliveryDataEventType = "OBJECTIVE_EVENT_TYPE_UNSPECIFIED"

const WebhookDeliveryDataEventTypeObjectiveEventTypeUserMessage WebhookDeliveryDataEventType = "OBJECTIVE_EVENT_TYPE_USER_MESSAGE"

const WebhookDeliveryDataEventTypeObjectiveEventTypeToolApprovalRequested WebhookDeliveryDataEventType = "OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED"

const WebhookDeliveryDataEventTypeObjectiveEventTypeToolApproved WebhookDeliveryDataEventType = "OBJECTIVE_EVENT_TYPE_TOOL_APPROVED"

const WebhookDeliveryDataEventTypeObjectiveEventTypeToolDenied WebhookDeliveryDataEventType = "OBJECTIVE_EVENT_TYPE_TOOL_DENIED"

const WebhookDeliveryDataEventTypeObjectiveEventTypeToolCalled WebhookDeliveryDataEventType = "OBJECTIVE_EVENT_TYPE_TOOL_CALLED"

const WebhookDeliveryDataEventTypeObjectiveEventTypeSubObjectiveCreated WebhookDeliveryDataEventType = "OBJECTIVE_EVENT_TYPE_SUB_OBJECTIVE_CREATED"

const WebhookDeliveryDataEventTypeObjectiveEventTypeError WebhookDeliveryDataEventType = "OBJECTIVE_EVENT_TYPE_ERROR"

const WebhookDeliveryDataEventTypeObjectiveEventTypeAssistantMessage WebhookDeliveryDataEventType = "OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE"

const WebhookDeliveryDataEventTypeObjectiveEventTypeToolResult WebhookDeliveryDataEventType = "OBJECTIVE_EVENT_TYPE_TOOL_RESULT"

const WebhookDeliveryDataEventTypeObjectiveEventTypeToolError WebhookDeliveryDataEventType = "OBJECTIVE_EVENT_TYPE_TOOL_ERROR"

const WebhookDeliveryDataEventTypeObjectiveEventTypeContextWindowCompacted WebhookDeliveryDataEventType = "OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED"

HTTPStatusCode int64

Response details (no response_body to avoid storing large payloads)

formatint32

LastAttemptAt Time

LatencyMs int64

ObjectiveEventID string

ObjectiveID string

ResponseContentLength string

Content length of the response body in bytes

Status WebhookDeliveryDataStatus

formatenum

One of the following:

const WebhookDeliveryDataStatusWebhookDeliveryStatusUnspecified WebhookDeliveryDataStatus = "WEBHOOK_DELIVERY_STATUS_UNSPECIFIED"

const WebhookDeliveryDataStatusWebhookDeliveryStatusPending WebhookDeliveryDataStatus = "WEBHOOK_DELIVERY_STATUS_PENDING"

const WebhookDeliveryDataStatusWebhookDeliveryStatusCompleted WebhookDeliveryDataStatus = "WEBHOOK_DELIVERY_STATUS_COMPLETED"

const WebhookDeliveryDataStatusWebhookDeliveryStatusFailed WebhookDeliveryDataStatus = "WEBHOOK_DELIVERY_STATUS_FAILED"

const WebhookDeliveryDataStatusWebhookDeliveryStatusDisabled WebhookDeliveryDataStatus = "WEBHOOK_DELIVERY_STATUS_DISABLED"

WebhookID string

WebhookURL string

Webhook delivery details

ErrorMessage stringoptional

ResponseHeaders map[string, string]optional

Response headers received from the webhook endpoint

Metadata OperationMetadata

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 Time

Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying

formatdate-time

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 stringoptional

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

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

type WebhookDeliveryData struct{…}