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

Signature

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

Signature

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

Signature

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

Signature

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