ai_agents_agents

Creates, updates, deletes, gets or lists an ai_agents_agents resource.

Overview

Name	ai_agents_agents
Type	Resource
Id	ovh.public_cloud.ai_agents_agents

Fields

The following fields are returned by SELECT queries:

get

successful operation

Name	Datatype	Description
id	string	Unique identifier of the AI agent
created_at	string (date-time)	Date of the AI agent creation (wire: createdAt)
current_state	object	Current state of the AI agent (wire: currentState)
resource_status	string	Reflects the readiness of the AI agent: READY, SUSPENDED when it is paused, or DELETING on the response to its deletion (CREATING, CREATION_PLANNED, DELETING, ERROR, OUT_OF_SYNC, READY, SUSPENDED, UNKNOWN, UPDATING) (wire: resourceStatus)
target_spec	object	Last target specification of the AI agent (wire: targetSpec)
updated_at	string (date-time)	Date of the last AI agent update (wire: updatedAt)

list

A managed AI agent

Name	Datatype	Description
id	string	Unique identifier of the AI agent
created_at	string (date-time)	Date of the AI agent creation (wire: createdAt)
current_state	object	Current state of the AI agent (wire: currentState)
resource_status	string	Reflects the readiness of the AI agent: READY, SUSPENDED when it is paused, or DELETING on the response to its deletion (CREATING, CREATION_PLANNED, DELETING, ERROR, OUT_OF_SYNC, READY, SUSPENDED, UNKNOWN, UPDATING) (wire: resourceStatus)
target_spec	object	Last target specification of the AI agent (wire: targetSpec)
updated_at	string (date-time)	Date of the last AI agent update (wire: updatedAt)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	agent_id, project_id		Get an AI agent
list	select	project_id	x_pagination_cursor, x_pagination_size	List AI agents
create	insert	project_id, target_spec		Creates an AI agent: a hosted assistant that answers on its own URL, given by currentState.endpointUrl, and reached with a token from the token action. An agent runs a model with a persona, plus whatever tools, memory and channels its configuration gives it. That configuration can come from a ready-made one published by OVHcloud, from a template of your own, or from settings supplied here — or from none of them, leaving an agent that cannot answer until it is given a model. Parts of it that OVHcloud manages are rejected here; the globalSettings preset says which. This is the only point at which this API sets an agent's configuration: from here on the agent holds its own and is configured through its endpoint. Create it paused to finish preparing it before it answers anyone.
update	update	agent_id, project_id, target_spec		targetSpec.enabled is mandatory, including on an update whose only intent is a rename. Restating the agent's current running state changes nothing; stating the other one pauses or resumes it. targetSpec.name is optional: omitting it, or restating the current name, leaves it untouched. Any other name renames the agent and redeploys it, keeping its identifier, its access tokens, its configuration and its data, and re-applying its paused state. A name another agent in the project already holds is rejected. The configuration is not settable here; it is read and changed through the agent itself.
delete	delete	agent_id, project_id		Deletion is asynchronous: the response describes the agent with resourceStatus: DELETING.
redeploy	exec	agentId, project_id		Refreshes the agent's runtime without touching its configuration or the data it holds.
token	exec	agentId, project_id		Returns a bearer token to present to the agent at currentState.endpointUrl. The token is returned once, here, and is never readable afterwards. Both body fields are optional: send {} for the defaults, which are the VIEWER role and the agent's own default lifetime. A lifetime longer than the agent's own maximum is rejected.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
agentId	string	Agent ID
agent_id	string	Agent ID (wire: agentId)
api_host	string	The OVHcloud API host. Selected by OVH_ENDPOINT (ovh-eu, ovh-ca or ovh-us; default ovh-eu). (default: api.eu.ovhcloud.com, x-stackQL-envVarSelector: {"envVar":"OVH_ENDPOINT","default":"ovh-eu","values":{"ovh-eu":"api.eu.ovhcloud.com","ovh-ca":"api.ca.ovhcloud.com","ovh-us":"api.us.ovhcloud.com"}})
project_id	string	The Public Cloud project ID. Resolved from OVH_CLOUD_PROJECT_SERVICE when set.
x_pagination_cursor	string	Pagination cursor (wire: X-Pagination-Cursor)
x_pagination_size	integer	Pagination size (wire: X-Pagination-Size)

SELECT examples

get

Get an AI agent

SELECT
id,
created_at,
current_state,
resource_status,
target_spec,
updated_at
FROM ovh.public_cloud.ai_agents_agents
WHERE agent_id = '{{ agent_id }}' -- required
AND project_id = '{{ project_id }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
;

list

List AI agents

SELECT
id,
created_at,
current_state,
resource_status,
target_spec,
updated_at
FROM ovh.public_cloud.ai_agents_agents
WHERE project_id = '{{ project_id }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
AND x_pagination_cursor = '{{ x_pagination_cursor }}'
AND x_pagination_size = '{{ x_pagination_size }}'
;

INSERT examples

create

Creates an AI agent: a hosted assistant that answers on its own URL, given by currentState.endpointUrl, and reached with a token from the token action. An agent runs a model with a persona, plus whatever tools, memory and channels its configuration gives it. That configuration can come from a ready-made one published by OVHcloud, from a template of your own, or from settings supplied here — or from none of them, leaving an agent that cannot answer until it is given a model. Parts of it that OVHcloud manages are rejected here; the globalSettings preset says which. This is the only point at which this API sets an agent's configuration: from here on the agent holds its own and is configured through its endpoint. Create it paused to finish preparing it before it answers anyone.

INSERT INTO ovh.public_cloud.ai_agents_agents (
target_spec,
project_id
)
SELECT 
'{{ target_spec }}' /* required */,
'{{ project_id }}'
RETURNING
id,
created_at,
current_state,
resource_status,
target_spec,
updated_at
;

Manifest

# Description fields are for documentation purposes
- name: ai_agents_agents
props:
  - name: project_id
    value: "{{ project_id }}"
    description: Required parameter for the ai_agents_agents resource.
  - name: target_spec
    description: |
      Desired specification of the AI agent to create
    value:
      config:
        agent:
          name: "{{ name }}"
        auth:
          kagentJwt:
            allowUnlimited: {{ allowUnlimited }}
            enabled: {{ enabled }}
            maxTtlSeconds: {{ maxTtlSeconds }}
            secretB64: "{{ secretB64 }}"
          mode: "{{ mode }}"
          oauth2:
            audience: "{{ audience }}"
            issuer: "{{ issuer }}"
            jwksUri: "{{ jwksUri }}"
            ownerSub: "{{ ownerSub }}"
            requiredScopes:
              - "{{ requiredScopes }}"
        builtins:
          network: {{ network }}
          search: {{ search }}
          searchApiKey: "{{ searchApiKey }}"
          searchProvider: "{{ searchProvider }}"
          toolsDeny:
            - "{{ toolsDeny }}"
          wizard: {{ wizard }}
        channels:
          telegram:
            botToken: "{{ botToken }}"
            enabled: {{ enabled }}
            webhookSecret: "{{ webhookSecret }}"
          webex:
            accessToken: "{{ accessToken }}"
            enabled: {{ enabled }}
            webhookSecret: "{{ webhookSecret }}"
        exec:
          apiKey: "{{ apiKey }}"
          autoSuspendIdleSeconds: {{ autoSuspendIdleSeconds }}
          baseUrl: "{{ baseUrl }}"
          defaultImage: "{{ defaultImage }}"
          enabled: {{ enabled }}
        llm:
          failover:
            on:
              - "{{ on }}"
          fallbacks:
            - maxTokens: {{ maxTokens }}
              model: "{{ model }}"
              providerId: "{{ providerId }}"
              temperature: {{ temperature }}
          maxContextMessages: {{ maxContextMessages }}
          maxTokens: {{ maxTokens }}
          model: "{{ model }}"
          providerId: "{{ providerId }}"
          temperature: {{ temperature }}
          vision:
            maxTokens: {{ maxTokens }}
            model: "{{ model }}"
            providerId: "{{ providerId }}"
            temperature: {{ temperature }}
        mcpIndexer:
          embedderBatchSize: {{ embedderBatchSize }}
          embedderModel: "{{ embedderModel }}"
          providerId: "{{ providerId }}"
        mcpServers: "{{ mcpServers }}"
        memory:
          consolidateOnTurnEnd: {{ consolidateOnTurnEnd }}
          consolidationCron: "{{ consolidationCron }}"
          consolidationMaxRounds: {{ consolidationMaxRounds }}
          corePredicates:
            - "{{ corePredicates }}"
          embedderBatchSize: {{ embedderBatchSize }}
          embedderModel: "{{ embedderModel }}"
          enabled: {{ enabled }}
          gcCron: "{{ gcCron }}"
          gcMaxSize: {{ gcMaxSize }}
          gcMinRetention: {{ gcMinRetention }}
          gcSoftLimit: {{ gcSoftLimit }}
          halfLifeDays: {{ halfLifeDays }}
          identityPromotionThreshold: {{ identityPromotionThreshold }}
          inferenceLlmFallback: {{ inferenceLlmFallback }}
          mergeSimilarityThreshold: {{ mergeSimilarityThreshold }}
          providerId: "{{ providerId }}"
          ruleIdleGcDays: {{ ruleIdleGcDays }}
          rulesMax: {{ rulesMax }}
        profiles:
          enabled: {{ enabled }}
          items: "{{ items }}"
        providers: "{{ providers }}"
        relay:
          enabled: {{ enabled }}
          maxMessagesPerRoom: {{ maxMessagesPerRoom }}
          maxRooms: {{ maxRooms }}
          roomCreation: "{{ roomCreation }}"
        skills:
          builtins:
            - "{{ builtins }}"
          enabled: {{ enabled }}
          items: "{{ items }}"
        soul: "{{ soul }}"
        toolPermissions:
          judge:
            enabled: {{ enabled }}
            model: "{{ model }}"
            providerId: "{{ providerId }}"
            soul: "{{ soul }}"
          rules:
            - action: "{{ action }}"
              args: "{{ args }}"
              phase: "{{ phase }}"
              reason: "{{ reason }}"
              result: "{{ result }}"
              tool: "{{ tool }}"
              triggers: "{{ triggers }}"
              unattended: "{{ unattended }}"
        version: "{{ version }}"
        workspace:
          agentsPath: "{{ agentsPath }}"
          mount:
            - accessKey: "{{ accessKey }}"
              backend: "{{ backend }}"
              bucket: "{{ bucket }}"
              endpoint: "{{ endpoint }}"
              maxFileBytes: {{ maxFileBytes }}
              maxFiles: {{ maxFiles }}
              maxTotalBytes: {{ maxTotalBytes }}
              path: "{{ path }}"
              prefix: "{{ prefix }}"
              region: "{{ region }}"
              ro: {{ ro }}
              secretKey: "{{ secretKey }}"
          scratchpad:
            cleanupCron: "{{ cleanupCron }}"
            enabled: {{ enabled }}
            maxDownloadBytes: {{ maxDownloadBytes }}
            path: "{{ path }}"
            retentionDays: {{ retentionDays }}
            spillBytes: {{ spillBytes }}
          skillsPath: "{{ skillsPath }}"
          zerofs:
            enabled: {{ enabled }}
            mountPath: "{{ mountPath }}"
      enabled: {{ enabled }}
      name: "{{ name }}"
      template:
        id: "{{ id }}"

UPDATE examples

update

targetSpec.enabled is mandatory, including on an update whose only intent is a rename. Restating the agent's current running state changes nothing; stating the other one pauses or resumes it. targetSpec.name is optional: omitting it, or restating the current name, leaves it untouched. Any other name renames the agent and redeploys it, keeping its identifier, its access tokens, its configuration and its data, and re-applying its paused state. A name another agent in the project already holds is rejected. The configuration is not settable here; it is read and changed through the agent itself.

UPDATE ovh.public_cloud.ai_agents_agents
SET 
target_spec = '{{ target_spec }}'
WHERE 
agent_id = '{{ agent_id }}' --required
AND project_id = '{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
AND target_spec = '{{ target_spec }}' --required
RETURNING
id,
created_at,
current_state,
resource_status,
target_spec,
updated_at;

DELETE examples

delete

Deletion is asynchronous: the response describes the agent with resourceStatus: DELETING.

DELETE FROM ovh.public_cloud.ai_agents_agents
WHERE agent_id = '{{ agent_id }}' --required
AND project_id = '{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
;

Lifecycle Methods

EXEC variables use wire (API) names.

redeploy

Refreshes the agent's runtime without touching its configuration or the data it holds.

EXEC ovh.public_cloud.ai_agents_agents.redeploy 
@agentId='{{ agentId }}' --required, 
@project_id='{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
;

token

Returns a bearer token to present to the agent at currentState.endpointUrl. The token is returned once, here, and is never readable afterwards. Both body fields are optional: send {} for the defaults, which are the VIEWER role and the agent's own default lifetime. A lifetime longer than the agent's own maximum is rejected.

EXEC ovh.public_cloud.ai_agents_agents.token 
@agentId='{{ agentId }}' --required, 
@project_id='{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"lifetimeSeconds": {{ lifetimeSeconds }}, 
"role": "{{ role }}"
}'
;