client.agents.pinned

client.agents.pinned — the agents.pinned operations.

On AsyncKindgi every method is the same, awaited.

client.agents.pinned.resolve()

resolve(
    agent_id: str | UUID,
    /,
    *,
    project_id: str | UUID | None = None,
    segments: Sequence[ScopeSegment | Mapping[str, str]] | None = None,
    timeout: float | None = None,
) -> AgentPinnedVersionResolution

Signature

The version a run would use. GET /v1/agents/{agentId}/pinned

Resolves the version a run of this agent would use for a project and segment path: the most specific pinned version (segment path, project, org, tenant), else the project's Latest: the version the newest deployment into the project shipped, or that a person published or added as the latest version there, whichever is newer. Without a project, Latest is taken over every version of the agent. A run that names its version, or a follow-up turn in a conversation, isn't resolved this way.

client.agents.pinned.list()

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

Signature

List an agent's pinned versions. GET /v1/agents/{agentId}/pinned-versions

Every scope with a pinned version, and the pin change that set it.

client.agents.pinned.pin()

pin(
    agent_id: str | UUID,
    body: AgentPinBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> PinAnswer

Signature

Pin a version for a scope. POST /v1/agents/{agentId}/pinned/pin

Pins version for scope: runs in that scope that don't name a version use it, from the next run. Open conversations keep their version. The version must be registered and active. Every pin is recorded, with who asked and why. Needs pin on the agent.

client.agents.pinned.check()

check(
    agent_id: str | UUID,
    body: AgentPinBody | Mapping[str, Any] | None = None,
    /,
    *,
    timeout: float | None = None,
    **fields: Any,
) -> PinCheck

Signature

Check a pin against its gate. POST /v1/agents/{agentId}/pinned/check

What POST …/pinned/pin with the same body would do, with nothing recorded: would-pin, needs-approval (with the approval it needs) or gate-failed, with every check. For a pipeline: evaluate, check, pin. Under kindgi dev, where a pin writes the version into the pack's files, it also warns about the files it would write over that git hasn't committed (uncommittedFiles), or that the pack isn't in git (notInGit). Needs read on the agent.

client.agents.pinned.history()

history(
    agent_id: str | UUID,
    /,
    *,
    limit: int | None = None,
    cursor: str | None = None,
    scope_kind: Literal['tenant', 'org', 'project', 'segment'] | None = None,
    scope_id: str | UUID | None = None,
    segments: Sequence[ScopeSegment | Mapping[str, str]] | None = None,
    timeout: float | None = None,
) -> PinPage

Signature

List an agent's pin history. GET /v1/agents/{agentId}/pin-history

The history of pinned-version changes (pins and unpins), newest first. scopeKind (tenant, org, project, segment) with scopeId and segment narrows it to one scope.

client.agents.pinned.get_change()

get_change(
    agent_id: str | UUID,
    change_id: str | UUID,
    /,
    *,
    timeout: float | None = None,
) -> Pin

Signature

Get a pin change. GET /v1/agents/{agentId}/pin-history/{changeId}

client.agents.pinned.unpin()

unpin(
    agent_id: str | UUID,
    body: AgentUnpinBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> PinAnswer

Signature

Remove a scope's pinned version. POST /v1/agents/{agentId}/pinned/unpin

Removes the scope's own pin: its runs use the next scope up (and the latest when nothing is pinned). Recorded like a pin. Needs pin on the agent.