client.agents.promotions

client.agents.promotions — the agents.promotions operations.

On AsyncKindgi every method is the same, awaited.

`client.agents.promotions.list()`

list(
    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,
) -> PromotionPage

List an agent's promotions. GET /v1/agents/{agentId}/promotions

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

`client.agents.promotions.create()`

create(
    agent_id: str | UUID,
    body: PromoteBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> Promotion

Make a version live for a scope. POST /v1/agents/{agentId}/promotions

Pins version live 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 promotion is recorded, with who asked and why. Needs promote on the agent.

`client.agents.promotions.check()`

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

Check a promotion against its gate. POST /v1/agents/{agentId}/promotions/check

What POST …/promotions with the same body would do, with nothing recorded: would-promote, needs-approval (with the approval it needs) or gate-failed, with every check. For a pipeline: evaluate, check, promote. Needs read on the agent.

`client.agents.promotions.get()`

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

Get a promotion. GET /v1/agents/{agentId}/promotions/{promotionId}