Files
sdk/docs/AgentsAPIApi.md
zeekayandHanzo Dev b55332704a feat: Hanzo Cloud SDK for Kotlin (generated from OpenAPI v8.0.0)
Coroutine-native client covering the full Hanzo /v1 cloud surface, for JVM and
Android. Generated with openapi-generator kotlin (library=jvm-okhttp4,
useCoroutines=true). Coordinate: ai.hanzo:sdk. Base URL: https://api.hanzo.ai.

Co-authored-by: Hanzo Dev <[email protected]>
2026-07-25 07:10:32 -07:00

14 KiB

AgentsAPIApi

All URIs are relative to https://api.hanzo.ai

Method HTTP request Description
cloudAgentsControllerActivity GET /v1/agents/activity
cloudAgentsControllerCreate POST /v1/agents
cloudAgentsControllerDelete DELETE /v1/agents/{ref}
cloudAgentsControllerGet GET /v1/agents/{ref}
cloudAgentsControllerList GET /v1/agents
cloudAgentsControllerMetrics GET /v1/agents/metrics
cloudAgentsControllerRun POST /v1/agents/{ref}/run
cloudAgentsControllerRuns GET /v1/agents/{ref}/runs
cloudAgentsControllerUpdate PATCH /v1/agents/{ref}

cloudAgentsControllerActivity

CloudAgentsControllerActivity200Response cloudAgentsControllerActivity()

The org-wide recent-activity feed (newest first, capped at 50). Each recorded run is an invoked/failed event; each agent's own create/update timestamps are created/updated events. Nothing is invented.

Example

// Import classes:
//import ai.hanzo.sdk.infrastructure.*
//import ai.hanzo.sdk.models.*

val apiInstance = AgentsAPIApi()
try {
    val result : CloudAgentsControllerActivity200Response = apiInstance.cloudAgentsControllerActivity()
    println(result)
} catch (e: ClientException) {
    println("4xx response calling AgentsAPIApi#cloudAgentsControllerActivity")
    e.printStackTrace()
} catch (e: ServerException) {
    println("5xx response calling AgentsAPIApi#cloudAgentsControllerActivity")
    e.printStackTrace()
}

Parameters

This endpoint does not need any parameter.

Return type

CloudAgentsControllerActivity200Response

Authorization

Configure bearerAuth statically:

ApiClient.accessToken = ""

Configure bearerAuth dynamically:

apiInstance.accessTokenProvider = { "" }

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

cloudAgentsControllerCreate

CloudAgentsAgent cloudAgentsControllerCreate(cloudAgentsCreateAgentRequest)

Create an agent (a model + instructions + tool names). A long-running agent additionally requires a 5-field cron 'schedule' and is invoked by the scheduler; a one-shot agent runs only when POSTed to /run.

Example

// Import classes:
//import ai.hanzo.sdk.infrastructure.*
//import ai.hanzo.sdk.models.*

val apiInstance = AgentsAPIApi()
val cloudAgentsCreateAgentRequest : CloudAgentsCreateAgentRequest =  // CloudAgentsCreateAgentRequest | 
try {
    val result : CloudAgentsAgent = apiInstance.cloudAgentsControllerCreate(cloudAgentsCreateAgentRequest)
    println(result)
} catch (e: ClientException) {
    println("4xx response calling AgentsAPIApi#cloudAgentsControllerCreate")
    e.printStackTrace()
} catch (e: ServerException) {
    println("5xx response calling AgentsAPIApi#cloudAgentsControllerCreate")
    e.printStackTrace()
}

Parameters

Name Type Description Notes
cloudAgentsCreateAgentRequest CloudAgentsCreateAgentRequest

Return type

CloudAgentsAgent

Authorization

Configure bearerAuth statically:

ApiClient.accessToken = ""

Configure bearerAuth dynamically:

apiInstance.accessTokenProvider = { "" }

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

cloudAgentsControllerDelete

cloudAgentsControllerDelete(ref)

Delete an agent and its run history.

Example

// Import classes:
//import ai.hanzo.sdk.infrastructure.*
//import ai.hanzo.sdk.models.*

val apiInstance = AgentsAPIApi()
val ref : kotlin.String = ref_example // kotlin.String | The agent's public id (agent_...) or org-unique name.
try {
    apiInstance.cloudAgentsControllerDelete(ref)
} catch (e: ClientException) {
    println("4xx response calling AgentsAPIApi#cloudAgentsControllerDelete")
    e.printStackTrace()
} catch (e: ServerException) {
    println("5xx response calling AgentsAPIApi#cloudAgentsControllerDelete")
    e.printStackTrace()
}

Parameters

Name Type Description Notes
ref kotlin.String The agent's public id (agent_...) or org-unique name.

Return type

null (empty response body)

Authorization

Configure bearerAuth statically:

ApiClient.accessToken = ""

Configure bearerAuth dynamically:

apiInstance.accessTokenProvider = { "" }

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

cloudAgentsControllerGet

CloudAgentsAgentDetail cloudAgentsControllerGet(ref)

Get an agent by its public id (agent_...) or org-unique name, with its instructions and up to 20 recent runs.

Example

// Import classes:
//import ai.hanzo.sdk.infrastructure.*
//import ai.hanzo.sdk.models.*

val apiInstance = AgentsAPIApi()
val ref : kotlin.String = ref_example // kotlin.String | The agent's public id (agent_...) or org-unique name.
try {
    val result : CloudAgentsAgentDetail = apiInstance.cloudAgentsControllerGet(ref)
    println(result)
} catch (e: ClientException) {
    println("4xx response calling AgentsAPIApi#cloudAgentsControllerGet")
    e.printStackTrace()
} catch (e: ServerException) {
    println("5xx response calling AgentsAPIApi#cloudAgentsControllerGet")
    e.printStackTrace()
}

Parameters

Name Type Description Notes
ref kotlin.String The agent's public id (agent_...) or org-unique name.

Return type

CloudAgentsAgentDetail

Authorization

Configure bearerAuth statically:

ApiClient.accessToken = ""

Configure bearerAuth dynamically:

apiInstance.accessTokenProvider = { "" }

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

cloudAgentsControllerList

CloudAgentsControllerList200Response cloudAgentsControllerList()

List the org's agents (most-recently-updated first).

Example

// Import classes:
//import ai.hanzo.sdk.infrastructure.*
//import ai.hanzo.sdk.models.*

val apiInstance = AgentsAPIApi()
try {
    val result : CloudAgentsControllerList200Response = apiInstance.cloudAgentsControllerList()
    println(result)
} catch (e: ClientException) {
    println("4xx response calling AgentsAPIApi#cloudAgentsControllerList")
    e.printStackTrace()
} catch (e: ServerException) {
    println("5xx response calling AgentsAPIApi#cloudAgentsControllerList")
    e.printStackTrace()
}

Parameters

This endpoint does not need any parameter.

Return type

CloudAgentsControllerList200Response

Authorization

Configure bearerAuth statically:

ApiClient.accessToken = ""

Configure bearerAuth dynamically:

apiInstance.accessTokenProvider = { "" }

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

cloudAgentsControllerMetrics

CloudAgentsMetrics cloudAgentsControllerMetrics(range)

Invocations-over-time histogram for the org's Agents dashboard. Every point is a real count of recorded runs in that bucket, one series line per agent that ran in the window. The Resource Usage rollup is all-null (this store meters no CPU/memory/storage/cost).

Example

// Import classes:
//import ai.hanzo.sdk.infrastructure.*
//import ai.hanzo.sdk.models.*

val apiInstance = AgentsAPIApi()
val range : kotlin.String = range_example // kotlin.String | Window token; one of 24H, 7D, 30D (default 30D).
try {
    val result : CloudAgentsMetrics = apiInstance.cloudAgentsControllerMetrics(range)
    println(result)
} catch (e: ClientException) {
    println("4xx response calling AgentsAPIApi#cloudAgentsControllerMetrics")
    e.printStackTrace()
} catch (e: ServerException) {
    println("5xx response calling AgentsAPIApi#cloudAgentsControllerMetrics")
    e.printStackTrace()
}

Parameters

Name Type Description Notes
range kotlin.String Window token; one of 24H, 7D, 30D (default 30D). [optional] [enum: 24H, 7D, 30D]

Return type

CloudAgentsMetrics

Authorization

Configure bearerAuth statically:

ApiClient.accessToken = ""

Configure bearerAuth dynamically:

apiInstance.accessTokenProvider = { "" }

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

cloudAgentsControllerRun

CloudAgentsRun cloudAgentsControllerRun(ref, agentsRunRequest)

Run the agent — composes its instructions with the caller input and executes one real chat completion through the in-process AI client, records the run, and returns the run view. Requires a validated principal (money path). The org's credit balance is pre-authorized before any inference (fail-closed); a successful run debits a flat per-run fee metered as product=agent. Duration is recorded; the run is real.

Example

// Import classes:
//import ai.hanzo.sdk.infrastructure.*
//import ai.hanzo.sdk.models.*

val apiInstance = AgentsAPIApi()
val ref : kotlin.String = ref_example // kotlin.String | The agent's public id (agent_...) or org-unique name.
val agentsRunRequest : AgentsRunRequest =  // AgentsRunRequest | 
try {
    val result : CloudAgentsRun = apiInstance.cloudAgentsControllerRun(ref, agentsRunRequest)
    println(result)
} catch (e: ClientException) {
    println("4xx response calling AgentsAPIApi#cloudAgentsControllerRun")
    e.printStackTrace()
} catch (e: ServerException) {
    println("5xx response calling AgentsAPIApi#cloudAgentsControllerRun")
    e.printStackTrace()
}

Parameters

| ref | kotlin.String| The agent's public id (agent_...) or org-unique name. | |

Name Type Description Notes
agentsRunRequest AgentsRunRequest [optional]

Return type

CloudAgentsRun

Authorization

Configure bearerAuth statically:

ApiClient.accessToken = ""

Configure bearerAuth dynamically:

apiInstance.accessTokenProvider = { "" }

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

cloudAgentsControllerRuns

CloudAgentsControllerRuns200Response cloudAgentsControllerRuns(ref, limit)

The agent's run history, newest first.

Example

// Import classes:
//import ai.hanzo.sdk.infrastructure.*
//import ai.hanzo.sdk.models.*

val apiInstance = AgentsAPIApi()
val ref : kotlin.String = ref_example // kotlin.String | The agent's public id (agent_...) or org-unique name.
val limit : kotlin.Int = 56 // kotlin.Int | Max runs to return (default 50, max 200).
try {
    val result : CloudAgentsControllerRuns200Response = apiInstance.cloudAgentsControllerRuns(ref, limit)
    println(result)
} catch (e: ClientException) {
    println("4xx response calling AgentsAPIApi#cloudAgentsControllerRuns")
    e.printStackTrace()
} catch (e: ServerException) {
    println("5xx response calling AgentsAPIApi#cloudAgentsControllerRuns")
    e.printStackTrace()
}

Parameters

| ref | kotlin.String| The agent's public id (agent_...) or org-unique name. | |

Name Type Description Notes
limit kotlin.Int Max runs to return (default 50, max 200). [optional]

Return type

CloudAgentsControllerRuns200Response

Authorization

Configure bearerAuth statically:

ApiClient.accessToken = ""

Configure bearerAuth dynamically:

apiInstance.accessTokenProvider = { "" }

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

cloudAgentsControllerUpdate

CloudAgentsAgent cloudAgentsControllerUpdate(ref, agentsUpdateAgentRequest)

Update an agent's mutable fields. The resulting execution mode + schedule are re-validated, so a partial update can never leave a long-running agent without a valid cron.

Example

// Import classes:
//import ai.hanzo.sdk.infrastructure.*
//import ai.hanzo.sdk.models.*

val apiInstance = AgentsAPIApi()
val ref : kotlin.String = ref_example // kotlin.String | The agent's public id (agent_...) or org-unique name.
val agentsUpdateAgentRequest : AgentsUpdateAgentRequest =  // AgentsUpdateAgentRequest | 
try {
    val result : CloudAgentsAgent = apiInstance.cloudAgentsControllerUpdate(ref, agentsUpdateAgentRequest)
    println(result)
} catch (e: ClientException) {
    println("4xx response calling AgentsAPIApi#cloudAgentsControllerUpdate")
    e.printStackTrace()
} catch (e: ServerException) {
    println("5xx response calling AgentsAPIApi#cloudAgentsControllerUpdate")
    e.printStackTrace()
}

Parameters

| ref | kotlin.String| The agent's public id (agent_...) or org-unique name. | |

Name Type Description Notes
agentsUpdateAgentRequest AgentsUpdateAgentRequest

Return type

CloudAgentsAgent

Authorization

Configure bearerAuth statically:

ApiClient.accessToken = ""

Configure bearerAuth dynamically:

apiInstance.accessTokenProvider = { "" }

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json