Skip to content
CantoraAPI documentation
POST
/v1/organizations/{organizationId}/projects/{projectId}/agent-configuration-applies

Apply or recover one complete Agent Configuration

Apply the exact previewed Agent Configuration under optimistic preconditions, or resume the same idempotent request from its durable Configuration Revision.

Authentication

Send an API key as a Bearer token in the Authorization header.

Parameters

NameLocationRequiredDescription
organizationIdpathYes
The Organization to address.
stringA Cantora Organization identifier, prefixed with `org_`.
  • maximum length 64
  • pattern ^org_[\s\S]+$
projectIdpathYes
The Project to address.
stringA Cantora Project identifier, prefixed with `proj_`.
  • maximum length 64
  • pattern ^proj_[\s\S]+$

Request body

Required.

application/json
object
  • unknown properties allowed false
requestIdrequired
stringThe idempotency key for this exact apply attempt.
  • maximum length 200
  • minimum length 1
desiredrequired
DesiredAgentConfigurationInputThe complete desired Test Agent Configuration accepted during preview.
manifestDigestrequired
stringThe lowercase SHA-256 manifest digest returned by preview.
preconditionsrequired
AgentConfigurationPreconditionsThe exact mutable Product State observed during preview.

Responses

200ApplyAgentConfigurationResult
application/json
ApplyAgentConfigurationResult
400The request path, headers, query, or JSON body did not satisfy the published schema
401Unauthorized
application/json
UnauthorizedEncoded
403Forbidden
application/json
ForbiddenEncoded
404NotFound
application/json
NotFoundEncoded
409Conflict
application/json
ConflictEncoded
412PreconditionFailed
application/json
PreconditionFailedEncoded

Reusable schemas

ApplyAgentConfigurationResult

object
  • unknown properties allowed false
revisionrequired
ConfigurationRevisionEncodedThe monotonically increasing revision within the Agent Definition.
configurationrequired
AgentConfigurationEncodedThe current Agent Configuration after the apply.

UnauthorizedEncoded

object
  • unknown properties allowed false
_tagrequired
stringThe stable machine-readable error type.
  • allowed values "Unauthorized"
reasonrequired
stringA safe explanation of why the credential was rejected.

ForbiddenEncoded

object
  • unknown properties allowed false
_tagrequired
stringThe stable machine-readable error type.
  • allowed values "Forbidden"
permissionrequired
stringThe permission required by the refused operation.

NotFoundEncoded

object
  • unknown properties allowed false
_tagrequired
stringThe stable machine-readable error type.
  • allowed values "NotFound"
resourcerequired
stringThe resource type relevant to the error.
idrequired
stringThe identifier supplied for the resource that was not found.

ConflictEncoded

object
  • unknown properties allowed false
_tagrequired
stringThe stable machine-readable error type.
  • allowed values "Conflict"
resourcerequired
stringThe resource type relevant to the error.
reasonrequired
stringA safe explanation of the state conflict.

PreconditionFailedEncoded

object
  • unknown properties allowed false
_tagrequired
stringThe stable machine-readable error type.
  • allowed values "PreconditionFailed"
resourcerequired
stringThe resource type relevant to the error.
  • allowed values "agent", "agentDefinition", "agentConfiguration"
currentAgentReleaseIdrequired
The current Agent Release identifier, or null before the first activation.
Any of
stringA Cantora Agent Release identifier, prefixed with `agent_release_`.
  • maximum length 64
  • pattern ^agent_release_[\s\S]+$
null
currentEtagrequired
stringThe current strong ETag required for the next conditional activation.
  • maximum length 12
  • pattern ^"(?:0|[1-9][0-9]{0,9})"$

DesiredAgentConfigurationInput

object
  • unknown properties allowed false
intentrequired
stringWhether the configuration creates a new binding or updates an identified Agent Definition.
  • allowed values "create", "update"
agentDefinitionIdrequired
The Agent Definition identifier.
Any of
stringA Cantora Agent Definition identifier, prefixed with `agentdef_`.
  • maximum length 64
  • pattern ^agentdef_[\s\S]+$
null
keyrequired
stringThe stable, human-authored Agent Definition key.
displayNamerequired
stringThe human-readable resource name.
testReleaserequired
objectThe desired Test Environment and activation reason.
  • unknown properties allowed false
environmentIdrequired
stringThe Environment identifier.
  • maximum length 64
  • pattern ^env_[\s\S]+$
reasonrequired
stringThe human-readable reason for activating the Test Agent Version.
manifestrequired
AgentVersionManifestInputThe complete immutable Agent behavior and execution-budget declaration.

AgentConfigurationPreconditions

object
  • unknown properties allowed false
agentDefinitionIdrequired
The Agent Definition identifier.
Any of
stringA Cantora Agent Definition identifier, prefixed with `agentdef_`.
  • maximum length 64
  • pattern ^agentdef_[\s\S]+$
null
definitionKeyrequired
The stable Agent Definition key.
Any of
string
null
definitionDisplayNamerequired
The Agent Definition display name observed during preview, or null when creating it.
Any of
string
null
definitionStatusrequired
The Agent Definition lifecycle status observed during preview, or null when creating it.
Any of
AgentDefinitionStatus
null
testAgentPrincipalIdrequired
The Test Agent Principal identifier, or null before it is created.
Any of
stringA Cantora Principal identifier, prefixed with `principal_`.
  • maximum length 64
  • pattern ^principal_[\s\S]+$
null
testReleaseGenerationrequired
integerThe current Test Agent Release generation, starting at zero before activation.
  • minimum 0
currentManifestDigestrequired
The current Test Agent Version manifest digest, or null before the first activation.
Any of
string
null
integrationBindings
The exact Integration selections and generations observed during preview.
Any of
array
  • at most items 16
Items
AgentConfigurationIntegrationBindingPrecondition
null

ConfigurationRevisionEncoded

object
  • unknown properties allowed false
configurationRevisionIdrequired
stringThe durable Configuration Revision identifier.
  • maximum length 64
  • pattern ^configuration_revision_[\s\S]+$
requestIdrequired
stringThe request identifier used for logs and support.
organizationIdrequired
stringThe Organization identifier.
  • maximum length 64
  • pattern ^org_[\s\S]+$
projectIdrequired
stringThe Project identifier.
  • maximum length 64
  • pattern ^proj_[\s\S]+$
testEnvironmentIdrequired
stringThe Test Environment identifier, or null before it can be resolved.
  • maximum length 64
  • pattern ^env_[\s\S]+$
agentDefinitionIdrequired
The Agent Definition identifier.
Any of
stringA Cantora Agent Definition identifier, prefixed with `agentdef_`.
  • maximum length 64
  • pattern ^agentdef_[\s\S]+$
null
testAgentPrincipalIdrequired
The Test Agent Principal identifier, or null before it is created.
Any of
stringA Cantora Principal identifier, prefixed with `principal_`.
  • maximum length 64
  • pattern ^principal_[\s\S]+$
null
agentVersionIdrequired
The immutable Agent Version identifier.
Any of
stringA Cantora Agent Version identifier, prefixed with `agent_version_`.
  • maximum length 64
  • pattern ^agent_version_[\s\S]+$
null
testAgentReleaseIdrequired
The Test Agent Release identifier, or null before it is activated.
Any of
stringA Cantora Agent Release identifier, prefixed with `agent_release_`.
  • maximum length 64
  • pattern ^agent_release_[\s\S]+$
null
manifestDigestrequired
stringThe lowercase SHA-256 digest of the normalized manifest.
statusrequired
stringThe current lifecycle status.
  • allowed values "Pending", "Running", "Succeeded", "Failed"
progressrequired
ConfigurationRevisionProgressHow the Surface presents progress while work runs.
failurerequired
The safe failure detail, or null unless the Configuration Revision failed.
Any of
ConfigurationRevisionFailureEncoded
null
createdAtrequired
stringWhen the resource was created, in UTC.
  • format date-time
updatedAtrequired
stringWhen the resource was last updated, in UTC.
  • format date-time

AgentConfigurationEncoded

object
  • unknown properties allowed false
organizationIdrequired
stringThe Organization identifier.
  • maximum length 64
  • pattern ^org_[\s\S]+$
projectIdrequired
stringThe Project identifier.
  • maximum length 64
  • pattern ^proj_[\s\S]+$
agentDefinitionIdrequired
stringThe Agent Definition identifier.
  • maximum length 64
  • pattern ^agentdef_[\s\S]+$
keyrequired
stringThe stable, human-authored Agent Definition key.
displayNamerequired
stringThe human-readable resource name.
statusrequired
AgentDefinitionStatusThe current lifecycle status.
testEnvironmentIdrequired
The Test Environment identifier, or null before it can be resolved.
Any of
stringA Cantora Environment identifier, prefixed with `env_`.
  • maximum length 64
  • pattern ^env_[\s\S]+$
null
testAgentPrincipalIdrequired
The Test Agent Principal identifier, or null before it is created.
Any of
stringA Cantora Principal identifier, prefixed with `principal_`.
  • maximum length 64
  • pattern ^principal_[\s\S]+$
null
testAgentStatusrequired
The Test Agent lifecycle status, or null before it is created.
Any of
string
null
currentAgentVersionIdrequired
The current Test Agent Version identifier, or null before the first activation.
Any of
stringA Cantora Agent Version identifier, prefixed with `agent_version_`.
  • maximum length 64
  • pattern ^agent_version_[\s\S]+$
null
currentManifestrequired
The current Test Agent Version manifest, or null before the first activation.
Any of
AgentVersionManifest
null
currentManifestDigestrequired
The current Test Agent Version manifest digest, or null before the first activation.
Any of
string
null
currentTestAgentReleaseIdrequired
The current Test Agent Release identifier, or null before the first activation.
Any of
stringA Cantora Agent Release identifier, prefixed with `agent_release_`.
  • maximum length 64
  • pattern ^agent_release_[\s\S]+$
null
currentTestAgentReleaseReasonrequired
The current Test Agent Release reason, or null before the first activation.
Any of
string
null
testReleaseGenerationrequired
integerThe current Test Agent Release generation, starting at zero before activation.
  • minimum 0
testReleaseEtagrequired
stringThe strong ETag for the current Test Agent Release generation.
latestConfigurationRevisionIdrequired
The latest Configuration Revision for this Agent Definition, or null before an apply.
Any of
stringA Cantora Configuration Revision identifier, prefixed with `configuration_revision_`.
  • maximum length 64
  • pattern ^configuration_revision_[\s\S]+$
null

AgentVersionManifestInput

Any of
AgentVersionManifestInputV1Alpha2
AgentVersionManifestInputV1Alpha3

AgentDefinitionStatus

string
  • allowed values "active", "disabled"

AgentConfigurationIntegrationBindingPrecondition

object
  • unknown properties allowed false
bindingNamerequired
stringThe logical Environment binding name requested by the Agent Version.
  • maximum length 100
  • minimum length 1
  • pattern ^[a-z][a-z0-9_]*$
integrationIdrequired
stringThe stable Organization-scoped Integration identifier.
  • maximum length 64
  • pattern ^integration_[\s\S]+$
integrationVersionIdrequired
stringThe immutable Integration Version identifier.
  • maximum length 64
  • pattern ^integration_version_[\s\S]+$
integrationVersionDigestrequired
stringThe lowercase SHA-256 digest of the exact Integration Version manifest.
  • pattern ^[0-9a-f]{64}$
requiredConnectionScoperequired
stringThe narrowest Connection scope this Agent dependency accepts.
  • allowed values "tenant"
integrationEnvironmentBindingIdrequired
stringThe stable Integration Environment Binding identifier.
  • maximum length 64
  • pattern ^integration_binding_[\s\S]+$
integrationEnvironmentBindingGenerationrequired
integerThe Integration Environment Binding generation observed during preview or retained by the Release.
  • greater than 0
dataIntegrationApplicationIdrequired
stringThe Organization-owned data Integration Application identifier.
  • maximum length 64
  • pattern ^data_integration_app_[\s\S]+$

ConfigurationRevisionProgress

object
  • unknown properties allowed false
agentDefinitionrequired
ConfigurationRevisionStepStatusWhether the Agent Definition step has completed.
testAgentrequired
ConfigurationRevisionStepStatusWhether the Test Agent step has completed.
agentVersionrequired
ConfigurationRevisionStepStatusWhether the Agent Version step has completed.
testReleaserequired
ConfigurationRevisionStepStatusThe desired Test Environment and activation reason.

ConfigurationRevisionFailureEncoded

object
  • unknown properties allowed false
coderequired
stringThe stable machine-readable condition code.
messagerequired
stringThe safe human-readable condition detail.

AgentVersionManifest

Any of
AgentVersionManifestV1Alpha2
AgentVersionManifestV1Alpha3

AgentVersionManifestInputV1Alpha2

object
  • unknown properties allowed false
schemaVersionrequired
stringThe Agent Version manifest schema identifier.
  • allowed values "config.cantora.ai/agent-version/v1alpha2"
instructionsrequired
stringThe complete natural-language instructions for the Agent Version.
  • maximum length 262144
modelrequired
AgentVersionModelThe exact provider model and behavior settings pinned by the Agent Version.
toolsrequired
LegacyAgentVersionToolsThe tool keys the Agent Version may call.
requiredBindingsrequired
AgentVersionDependenciesThe configuration bindings the Agent Version requires at runtime.
budgetsrequired
AgentVersionBudgetsInputThe finite execution limits enforced for the Agent Version.

AgentVersionManifestInputV1Alpha3

object
  • unknown properties allowed false
schemaVersionrequired
stringThe Agent Version manifest schema identifier.
  • allowed values "config.cantora.ai/agent-version/v1alpha3"
instructionsrequired
stringThe complete natural-language instructions for the Agent Version.
  • maximum length 262144
modelrequired
AgentVersionModelThe exact provider model and behavior settings pinned by the Agent Version.
toolsrequired
AgentVersionToolsThe tool keys the Agent Version may call.
requiredBindingsrequired
AgentVersionDependenciesThe configuration bindings the Agent Version requires at runtime.
integrationDependenciesrequired
arrayThe exact immutable Integration Versions and logical bindings this Agent Version requires.
  • at most items 16
Items
AgentVersionIntegrationDependency
contextSnapshotModel
ContextSnapshotModelInputThe exact model used for Conversation history compaction. Omission resolves to the reviewed gpt-5.6-luna configuration.
budgetsrequired
AgentVersionBudgetsInputThe finite execution limits enforced for the Agent Version.
entrypoints
arrayThe named host-started operations declared by this Agent Version.
  • at most items 16
  • at least items 1
Items
AgentEntrypointInput

ConfigurationRevisionStepStatus

string
  • allowed values "Pending", "Succeeded"

AgentVersionManifestV1Alpha2

object
  • unknown properties allowed false
schemaVersionrequired
stringThe Agent Version manifest schema identifier.
  • allowed values "config.cantora.ai/agent-version/v1alpha2"
instructionsrequired
stringThe complete natural-language instructions for the Agent Version.
  • maximum length 262144
modelrequired
AgentVersionModelThe exact provider model and behavior settings pinned by the Agent Version.
toolsrequired
LegacyAgentVersionToolsThe tool keys the Agent Version may call.
requiredBindingsrequired
AgentVersionDependenciesThe configuration bindings the Agent Version requires at runtime.
budgetsrequired
AgentVersionBudgetsThe finite execution limits enforced for the Agent Version.

AgentVersionManifestV1Alpha3

object
  • unknown properties allowed false
schemaVersionrequired
stringThe Agent Version manifest schema identifier.
  • allowed values "config.cantora.ai/agent-version/v1alpha3"
instructionsrequired
stringThe complete natural-language instructions for the Agent Version.
  • maximum length 262144
modelrequired
AgentVersionModelThe exact provider model and behavior settings pinned by the Agent Version.
toolsrequired
AgentVersionToolsThe tool keys the Agent Version may call.
requiredBindingsrequired
AgentVersionDependenciesThe configuration bindings the Agent Version requires at runtime.
integrationDependenciesrequired
arrayThe exact immutable Integration Versions and logical bindings this Agent Version requires.
  • at most items 16
Items
AgentVersionIntegrationDependency
contextSnapshotModel
AgentVersionModelThe exact provider model and behavior settings used for Conversation history compaction.
budgetsrequired
AgentVersionBudgetsThe finite execution limits enforced for the Agent Version.
entrypoints
arrayThe named host-started operations declared by this Agent Version.
  • at most items 16
  • at least items 1
Items
AgentEntrypoint

AgentVersionModel

Any of
object
  • unknown properties allowed false
providerrequired
stringThe model, Surface, or integration provider key.
  • allowed values "googleVertex"
modelrequired
stringThe exact provider model and behavior settings pinned by the Agent Version.
  • maximum length 256
  • minimum length 1
settingsrequired
GoogleVertexModelSettingsThe provider-native settings that change model behavior.
object
  • unknown properties allowed false
providerrequired
stringThe model, Surface, or integration provider key.
  • allowed values "openai"
modelrequired
stringThe exact provider model and behavior settings pinned by the Agent Version.
  • maximum length 256
  • minimum length 1
settingsrequired
OpenAiModelSettingsThe provider-native settings that change model behavior.

LegacyAgentVersionTools

array
  • at most items 100
  • unique items true
Items
string
  • allowed values "run_code", "search_knowledge"

AgentVersionDependencies

array
  • at most items 100
  • unique items true
Items
string
  • maximum length 100
  • minimum length 1
  • pattern ^[a-z][a-z0-9_]*$

AgentVersionBudgetsInput

object
  • unknown properties allowed false
maxModelStepsrequired
integerThe maximum number of model calls in one Run.
  • maximum 100
  • minimum 1
maxToolCallsrequired
integerThe maximum number of tool calls in one Run.
  • maximum 100
  • minimum 0
totalWallTimeMsrequired
integerThe maximum total Run duration in milliseconds.
  • maximum 300000
  • minimum 1000
modelStepTimeMsrequired
integerThe maximum duration of one model step in milliseconds.
  • maximum 300000
  • minimum 1000
streamStallTimeMsrequired
integerThe maximum duration without stream progress in milliseconds.
  • maximum 300000
  • minimum 1000
maxInputTokens
integerThe maximum number of model input tokens. Omission resolves to 250,000.
  • maximum 10000000
  • minimum 1
maxOutputTokensrequired
integerThe maximum number of model output tokens.
  • maximum 1000000
  • minimum 1
maxReasoningTokensrequired
integerThe maximum number of model reasoning tokens.
  • maximum 1000000
  • minimum 0
maxTotalTokensrequired
integerThe maximum total model tokens in one Run.
  • maximum 10000000
  • minimum 1
maxToolResultBytesrequired
integerThe maximum aggregate tool-result size in bytes.
  • maximum 10000000
  • minimum 1
maxEstimatedCostMicrosrequired
integerThe maximum estimated model cost in millionths of the billing currency.
  • maximum 1000000000
  • minimum 1

AgentVersionTools

array
  • at most items 100
  • unique items true
Items
AgentToolName

AgentVersionIntegrationDependency

object
  • unknown properties allowed false
bindingNamerequired
stringThe logical Environment binding name requested by the Agent Version.
  • maximum length 100
  • minimum length 1
  • pattern ^[a-z][a-z0-9_]*$
integrationIdrequired
stringThe stable Organization-scoped Integration identifier.
  • maximum length 64
  • pattern ^integration_[\s\S]+$
integrationVersionIdrequired
stringThe immutable Integration Version identifier.
  • maximum length 64
  • pattern ^integration_version_[\s\S]+$
integrationVersionDigestrequired
stringThe lowercase SHA-256 digest of the exact Integration Version manifest.
  • pattern ^[0-9a-f]{64}$
requiredConnectionScoperequired
stringThe narrowest Connection scope this Agent dependency accepts.
  • allowed values "tenant"

ContextSnapshotModelInput

Any of
object
  • unknown properties allowed false
providerrequired
stringThe model, Surface, or integration provider key.
  • allowed values "googleVertex"
modelrequired
stringThe exact provider model and behavior settings pinned by the Agent Version.
  • maximum length 256
  • minimum length 1
settingsrequired
GoogleVertexModelSettingsThe provider-native settings that change model behavior.
object
  • unknown properties allowed false
providerrequired
stringThe model, Surface, or integration provider key.
  • allowed values "openai"
modelrequired
stringThe exact provider model and behavior settings pinned by the Agent Version.
  • maximum length 256
  • minimum length 1
settingsrequired
OpenAiModelSettingsThe provider-native settings that change model behavior.

AgentEntrypointInput

object
  • unknown properties allowed false
keyrequired
AgentEntrypointKeyThe stable, human-authored Agent Definition key.
purposerequired
stringA plain-language description of the work this entrypoint performs.
  • maximum length 500
  • minimum length 1
openingInstructionrequired
stringThe fixed instruction that starts a Run admitted through this entrypoint.
  • maximum length 16384
  • minimum length 1
acceptedTriggerKindsrequired
arrayThe Run trigger kinds allowed to select this entrypoint.
  • at least items 1
  • unique items true
Items
AgentEntrypointTriggerKind
parametersrequired
arrayThe complete path, query, and header parameters for this operation.
  • at most items 32
Items
AgentEntrypointParameter
toolsrequired
AgentVersionToolsThe tool keys the Agent Version may call.
connectionBindingsrequired
AgentVersionDependenciesThe declared Connection bindings available to this entrypoint.
dataAccessrequired
stringWhether the entrypoint may use Tenant data alone or Tenant data plus an eligible User's data.
  • allowed values "tenant", "tenantAndOptionalUser"
userAuthorityrequired
stringWhether a Run may receive authority for an eligible User through this entrypoint.
  • allowed values "none", "optional"
effectsrequired
stringThe consequential external-effect authority available to this entrypoint.
  • allowed values "none"
deliveryrequired
stringThe external Delivery authority available to this entrypoint.
  • allowed values "none"
outputModerequired
stringWhether this entrypoint returns internal Run output or permits external presentation.
  • allowed values "internalOnly"
resultrequired
AgentEntrypointResultThe strict result contract for this entrypoint.
budgetsrequired
AgentVersionBudgetsInputThe finite execution limits enforced for the Agent Version.

AgentVersionBudgets

object
  • unknown properties allowed false
maxModelStepsrequired
integerThe maximum number of model calls in one Run.
  • maximum 100
  • minimum 1
maxToolCallsrequired
integerThe maximum number of tool calls in one Run.
  • maximum 100
  • minimum 0
totalWallTimeMsrequired
integerThe maximum total Run duration in milliseconds.
  • maximum 300000
  • minimum 1000
modelStepTimeMsrequired
integerThe maximum duration of one model step in milliseconds.
  • maximum 300000
  • minimum 1000
streamStallTimeMsrequired
integerThe maximum duration without stream progress in milliseconds.
  • maximum 300000
  • minimum 1000
maxInputTokensrequired
integerThe maximum number of model input tokens recorded for this execution budget.
  • maximum 10000000
  • minimum 1
maxOutputTokensrequired
integerThe maximum number of model output tokens.
  • maximum 1000000
  • minimum 1
maxReasoningTokensrequired
integerThe maximum number of model reasoning tokens.
  • maximum 1000000
  • minimum 0
maxTotalTokensrequired
integerThe maximum total model tokens in one Run.
  • maximum 10000000
  • minimum 1
maxToolResultBytesrequired
integerThe maximum aggregate tool-result size in bytes.
  • maximum 10000000
  • minimum 1
maxEstimatedCostMicrosrequired
integerThe maximum estimated model cost in millionths of the billing currency.
  • maximum 1000000000
  • minimum 1

AgentEntrypoint

object
  • unknown properties allowed false
keyrequired
AgentEntrypointKeyThe stable entrypoint key within this Agent Version.
purposerequired
stringA plain-language description of the work this entrypoint performs.
  • maximum length 500
  • minimum length 1
openingInstructionrequired
stringThe fixed instruction that starts a Run admitted through this entrypoint.
  • maximum length 16384
  • minimum length 1
acceptedTriggerKindsrequired
arrayThe Run trigger kinds allowed to select this entrypoint.
  • at least items 1
  • unique items true
Items
AgentEntrypointTriggerKind
parametersrequired
arrayThe complete set of strict top-level parameters accepted by this entrypoint.
  • at most items 32
Items
AgentEntrypointParameter
toolsrequired
AgentVersionToolsThe tool keys the Agent Version may call.
connectionBindingsrequired
AgentVersionDependenciesThe declared Connection bindings available to this entrypoint.
dataAccessrequired
stringWhether the entrypoint may use Tenant data alone or Tenant data plus an eligible User's data.
  • allowed values "tenant", "tenantAndOptionalUser"
userAuthorityrequired
stringWhether a Run may receive authority for an eligible User through this entrypoint.
  • allowed values "none", "optional"
effectsrequired
stringThe consequential external-effect authority available to this entrypoint.
  • allowed values "none"
deliveryrequired
stringThe external Delivery authority available to this entrypoint.
  • allowed values "none"
outputModerequired
stringWhether this entrypoint returns internal Run output or permits external presentation.
  • allowed values "internalOnly"
resultrequired
AgentEntrypointResultThe strict result contract for this entrypoint.
budgetsrequired
AgentVersionBudgetsThe finite execution limits enforced for the Agent Version.

GoogleVertexModelSettings

object
  • unknown properties allowed false
thinkingLevelrequired
stringThe Google Vertex-native thinking level.
  • allowed values "minimal", "low", "medium", "high"

OpenAiModelSettings

object
  • unknown properties allowed false
reasoningEffortrequired
stringThe OpenAI-native reasoning effort.
  • allowed values "none", "low", "medium", "high", "xhigh", "max"
reasoningModerequired
stringThe OpenAI-native reasoning mode.
  • allowed values "standard", "pro"

AgentToolName

string
  • allowed values "run_code", "search_knowledge", "search_api_reference", "propose_action"

AgentEntrypointKey

string
  • maximum length 100
  • minimum length 1
  • pattern ^[a-z][a-z0-9_]*$

AgentEntrypointTriggerKind

Any of
string
  • allowed values "manual"

AgentEntrypointParameter

Any of
AgentEntrypointStringParameter
AgentEntrypointIntegerParameter
AgentEntrypointNumberParameter
AgentEntrypointBooleanParameter
AgentEntrypointStringListParameter

AgentEntrypointResult

object
  • unknown properties allowed false
typerequired
stringThe closed contract behavior type.
  • allowed values "text"
maximumBytesrequired
integerThe greatest accepted UTF-8 result size in bytes.
  • maximum 1048576
  • minimum 1
allowsNoChangerequired
booleanWhether the entrypoint may complete successfully without producing a result value.

AgentEntrypointStringParameter

object
  • unknown properties allowed false
keyrequired
AgentEntrypointKeyThe stable parameter key within this entrypoint.
descriptionrequired
stringA human-readable explanation of this contract element.
  • maximum length 500
  • minimum length 1
requiredrequired
booleanWhether the parameter must be present.
typerequired
stringThe closed contract behavior type.
  • allowed values "string"
minimumLengthrequired
integerThe least accepted string length.
  • maximum 65536
  • minimum 0
maximumLengthrequired
integerThe greatest accepted string length.
  • maximum 65536
  • minimum 1

AgentEntrypointIntegerParameter

object
  • unknown properties allowed false
keyrequired
AgentEntrypointKeyThe stable parameter key within this entrypoint.
descriptionrequired
stringA human-readable explanation of this contract element.
  • maximum length 500
  • minimum length 1
requiredrequired
booleanWhether the parameter must be present.
typerequired
stringThe closed contract behavior type.
  • allowed values "integer"
minimumrequired
integerThe least accepted numeric value.
maximumrequired
integerThe greatest accepted numeric value.

AgentEntrypointNumberParameter

object
  • unknown properties allowed false
keyrequired
AgentEntrypointKeyThe stable parameter key within this entrypoint.
descriptionrequired
stringA human-readable explanation of this contract element.
  • maximum length 500
  • minimum length 1
requiredrequired
booleanWhether the parameter must be present.
typerequired
stringThe closed contract behavior type.
  • allowed values "number"
minimumrequired
numberThe least accepted numeric value.
maximumrequired
numberThe greatest accepted numeric value.

AgentEntrypointBooleanParameter

object
  • unknown properties allowed false
keyrequired
AgentEntrypointKeyThe stable parameter key within this entrypoint.
descriptionrequired
stringA human-readable explanation of this contract element.
  • maximum length 500
  • minimum length 1
requiredrequired
booleanWhether the parameter must be present.
typerequired
stringThe closed contract behavior type.
  • allowed values "boolean"

AgentEntrypointStringListParameter

object
  • unknown properties allowed false
keyrequired
AgentEntrypointKeyThe stable parameter key within this entrypoint.
descriptionrequired
stringA human-readable explanation of this contract element.
  • maximum length 500
  • minimum length 1
requiredrequired
booleanWhether the parameter must be present.
typerequired
stringThe closed contract behavior type.
  • allowed values "stringList"
minimumItemsrequired
integerThe least accepted number of list items.
  • maximum 100
  • minimum 0
maximumItemsrequired
integerThe greatest accepted number of list items.
  • maximum 100
  • minimum 1
minimumItemLengthrequired
integerThe least accepted string length for one list item.
  • maximum 65536
  • minimum 0
maximumItemLengthrequired
integerThe greatest accepted string length for one list item.
  • maximum 65536
  • minimum 1