OSS Coordinator
Use this reference with the complete developer tour and Python types. The example at the end runs after the tour setup.
assistance
Section titled “assistance”Read OSS Coordinator enablement and provider configuration status.
assistance(self)| Parameter | Type and default | Usage |
|---|
Returns: AssistanceSettings: overseer, version, overseer_configured.
Permissions, lifecycle and errors: Provider configured and workspace enabled are separate states. The wire name overseer is retained for SDK/API compatibility; the product calls it Coordinator.
Working Python example. Input/output fields are in the types reference.
update_assistance
Section titled “update_assistance”Enable or disable Coordinator through the public API, without the UI.
update_assistance(self, *, overseer: bool | None=None, version: int | None=None)| Parameter | Type and default | Usage |
|---|---|---|
overseer |
bool | None (default None) |
Whether OSS Coordinator is enabled in this workspace. The wire name is retained for compatibility. |
version |
int | None (default None) |
Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
Returns: Current AssistanceSettings after the update.
Permissions, lifecycle and errors: A person needs manage assistance:workspace. Configure a provider on the engine first. Use version to reject stale updates; disabling invalidates unconfirmed plans.
Working Python example. Input/output fields are in the types reference.
plan_overseer
Section titled “plan_overseer”Prepare a reviewable Coordinator plan using the caller’s authorized specialist context.
plan_overseer(self, prompt: str, target: dict[str, str] | None=None, *, previous_plan_id: str | None=None, key: str | None=None)| Parameter | Type and default | Usage |
|---|---|---|
prompt |
str (required) |
Instruction to Coordinator. The engine supplies only currently permitted specialist context. |
target |
dict[str, str] | None (default None) |
Target kind and stable ID. Choose a new target or an existing conversation, not both. |
previous_plan_id |
str | None (default None) |
Optional prior plan belonging to the caller for continuing permitted context. |
key |
str | None (default None) |
Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation. |
Returns: OverseerPlan with operation, sources, selected agents, instructions, expiry and requires_confirmation.
Permissions, lifecycle and errors: Does not automatically dispatch the plan. Model failures send no instructions. Retain the key for a transport-unknown result; optional target narrows scope and previous_plan_id supplies permitted prior context.
Working Python example. Input/output fields are in the types reference.
overseer_plans
Section titled “overseer_plans”List Coordinator plans visible to the current person.
overseer_plans(self)| Parameter | Type and default | Usage |
|---|
Returns: Array of OverseerPlan.
Permissions, lifecycle and errors: Another person’s plans are not implicitly shared. Plans do not grant permission; current access is rechecked on use.
Working Python example. Input/output fields are in the types reference.
overseer_plan
Section titled “overseer_plan”Read one Coordinator plan and its current dispatch/reply state.
overseer_plan(self, plan_id: str)| Parameter | Type and default | Usage |
|---|---|---|
plan_id |
str (required) |
Saved Coordinator plan ID returned by plan_overseer or coordinate. |
Returns: OverseerPlan, with dispatches, replies and any reply_summary.
Permissions, lifecycle and errors: A returned request may still be open. Do not present an instruction’s acceptance as finished specialist work.
Working Python example. Input/output fields are in the types reference.
confirm_overseer
Section titled “confirm_overseer”Dispatch a still-valid reviewed plan.
confirm_overseer(self, plan_id: str)| Parameter | Type and default | Usage |
|---|---|---|
plan_id |
str (required) |
Saved Coordinator plan ID returned by plan_overseer or coordinate. |
Returns: OverseerPlan containing attributed dispatches.
Permissions, lifecycle and errors: Uses only the saved server plan ID. Rechecks current permissions, scope, enablement and expiry. Repeating confirmation reuses that plan’s dispatch, not a new arbitrary model command.
Working Python example. Input/output fields are in the types reference.
summarize_overseer
Section titled “summarize_overseer”Ask the configured model to summarize currently authorized specialist replies.
summarize_overseer(self, plan_id: str)| Parameter | Type and default | Usage |
|---|---|---|
plan_id |
str (required) |
Saved Coordinator plan ID returned by plan_overseer or coordinate. |
Returns: Updated OverseerPlan with reply_summary, replies, digest or summary_error.
Permissions, lifecycle and errors: Pending and missing replies must stay explicit. Summary is not an action or independent factual verification. Provider billing and the per-person rate limit apply.
Working Python example. Input/output fields are in the types reference.
coordinate
Section titled “coordinate”Let Coordinator choose specialists and dispatch permitted communication automatically.
coordinate(self, prompt: str, *, key: str | None=None, **options: Any)| Parameter | Type and default | Usage |
|---|---|---|
prompt |
str (required) |
Instruction to Coordinator. The engine supplies only currently permitted specialist context. |
key |
str | None (default None) |
Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation. |
**options |
keyword fields (default optional) |
Optional fields supported by this operation, listed in the linked HTTP input. Unknown fields are not a supported extension mechanism. |
Returns: OverseerPlan marked automatic, with attributed instructions/dispatches or a status answer.
Permissions, lifecycle and errors: No UI preview is required. Uses the caller’s current rights, not an operator override. It cannot approve business actions, change identities or grant permissions. Model execution is billed by the configured provider.
Working Python example. Input/output fields are in the types reference.
Example
Section titled “Example”Run this region after the shared setup. Assertions check the returned data; the full tour is a runnable program.
settings = owner.assistance()assert settings['overseer_configured'], 'Configure BEEPGRID_AI_PROVIDER and BEEPGRID_AI_MODEL on the engine first'owner.update_assistance(overseer=True, version=settings['version'])plan = owner.plan_overseer('Ask the available specialists whether staging is ready.')assert owner.overseer_plan(plan['id'])['id'] == plan['id']assert any(item['id'] == plan['id'] for item in owner.overseer_plans())confirmed = owner.confirm_overseer(plan['id'])assert confirmed['id'] == plan['id']time.sleep(1.1) # Assistance has a per-person rate limit.summary = owner.summarize_overseer(plan['id'])assert summary['id'] == plan['id']time.sleep(1.1)automatic = owner.coordinate('Ask the specialists to report any release blockers.', key=run_id + '/coordinate')assert automatic['id']