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

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

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

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

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

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 workspace's.

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