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,
    /,
    *,
    project_id: str | UUID | None = None,
    timeout: float | None = None,
) -> Agent

Signature

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

An item more than one project serves (an environment order carries it to later environments) answers its newest active version that can run in a project the caller reads, and 404 when there is none. projectId narrows that to one project. An item with one project answers its latest active version. For an agent, that is its highest version, which numbers the next one. It is not always what a project runs: agents.projects says what runs in each project.

client.agents.projects()

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

Signature

List the projects an agent runs in, and what runs in each. GET /v1/agents/{agentId}/projects

The project the agent was first published in, then each other project a version of it can run in: one that a deployment which is not retired shipped a version into, an unregistered version included. A change to the agent reaches each of them. Only the projects the caller can read are named, its first project included. A retired agent still answers. Without environment orders, an agent has one project. Under kindgi dev, whose pack names no project, the list is empty. Each project says what a run there that names no version gets (runs) and why (follows): a pin that covers the project, else its Latest. Latest moves only when a deployment into the project ships a version, or when a person publishes a full version or adds one as the latest version; a pin never moves it. segments lists the pins on segments inside the project. highest is the agent's highest version, which numbers the next one. A version the caller can't see is left out.

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.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.set_owner()

set_owner(
    agent_id: str | UUID,
    body: SetAgentOwnerBody | Mapping[str, Any] | None = None,
    /,
    *,
    timeout: float | None = None,
    **fields: Any,
) -> SetAgentOwnerResult

Signature

Set an agent's owner. PUT /v1/agents/{agentId}/owner

One owner per agent: the person its corrections go to when they need the owner. Setting it again replaces the one before. Needs admin on the agent (an admin of its project). With a directory of people, the owner must be one of the tenant's.

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 highest active version, which numbers the next one. 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).