client.agents

client.agents — the agents operations.

On AsyncKindgi every method is the same, awaited.

client.agents.list()

list(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    name: str | None = None,
    scope_kind: Literal['tenant', 'org', 'project'] | None = None,
    scope_id: str | UUID | None = None,
    inherit: bool | None = None,
    include_retired: bool | None = None,
    timeout: float | None = None,
) -> AgentCollectionPage

Signature

List agents. GET /v1/agents

Cursor-paginated list of the latest version per agent id. Optional ?name= filters by prefix on agent id. A retired agent (every version unregistered) is listed only with ?includeRetired=true, as its highest version with unregisteredAt, so it can be found and a version reinstated.

client.agents.publish()

publish(
    body: PublishAgentBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> PublishAgentResult

Signature

Publish an agent definition. POST /v1/agents

Body is a full defineAgent spec. Server validates via @kindgi/agents.defineAgent before persisting.

client.agents.get()

get(agent_id: str | UUID, /, *, timeout: float | None = None) -> Agent

Signature

Fetch the latest version of an agent. GET /v1/agents/{agentId}

client.agents.list_versions()

list_versions(
    agent_id: str | UUID,
    /,
    *,
    limit: int | None = None,
    cursor: str | None = None,
    include_tombstoned: bool | None = None,
    timeout: float | None = None,
) -> AgentCollectionPage

Signature

List versions of an agent. GET /v1/agents/{agentId}/versions

Cursor-paginated. Sort order is binding-defined (built-in registry: semver asc). Defaults to active versions only. Pass ?includeTombstoned=true to include unregistered versions too, each with unregisteredAt: a retired agent (every version unregistered) answers too, with its versions to reinstate.

client.agents.derive_version()

derive_version(
    agent_id: str | UUID,
    body: DeriveAgentVersionBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> Agent

Signature

Derive an agent version with data-block pins swapped. POST /v1/agents/{agentId}/versions

An expert's edit, without a code change: a new agent version that is from's bag with some prompt or settings pins swapped (derivedFrom: { version, reason: 'edited', label, by }), numbered the next free patch after the agent's highest version. Only blocks from already references swap, to a published, active version of the right kind (model settings for the model-settings block); tool pins come from code. Needs publish on the agent.

client.agents.get_version()

get_version(
    agent_id: str | UUID,
    version: str,
    /,
    *,
    timeout: float | None = None,
) -> Agent

Signature

Fetch a specific agent version. GET /v1/agents/{agentId}/versions/{version}

client.agents.unregister()

unregister(
    agent_id: str | UUID,
    version: str,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> UnregisterAgentResult

Signature

Unregister a specific agent version. POST /v1/agents/{agentId}/versions/{version}/unregister

client.agents.reinstate_version()

reinstate_version(
    agent_id: str | UUID,
    version: str,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> ReinstateAgentVersionResult

Signature

Reinstate a specific tombstoned agent version. POST /v1/agents/{agentId}/versions/{version}/reinstate

Un-tombstones a previously-unregistered version: clears the tombstone on that version and recomputes the latest active version. Restores the manifest bytes verbatim (semver hygiene: reinstate never mutates). Idempotent — reinstating an active version is a no-op (returns wasTombstoned: false). Reinstating any version of a fully-retired agent reactivates the identity: subsequent GETs return 200, invocations succeed. Publish is always allowed regardless of retirement state — this verb is for restoring previously-unregistered bytes, not for reactivating a retired identity (a fresh publish does that).