# client.agents

> client.agents — the agents operations.

`client.agents` — the `agents` operations.

On `AsyncKindgi` every method is the same, awaited.

## `client.agents.list()`

```python signature
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
```

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()`

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

Publish an agent definition. `POST /v1/agents`

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

## `client.agents.get()`

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

Fetch the latest 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.

## `client.agents.list_versions()`

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

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()`

```python signature
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
```

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. In a tenant with environment orders, the new version is made in the first environment of the agent's project's order, and reaches the later ones when a build of the agent is promoted; the agent's project doesn't change.

## `client.agents.get_version()`

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

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

## `client.agents.unregister()`

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

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

## `client.agents.reinstate_version()`

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

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