Documentation
OpenAPIAgent index

Organization control agent

The organization control agent is a managed Agent Fabric agent that can answer questions about the account and propose bounded operations. It uses the same organization, role, scopes, usage ledger, traces, evaluation, and remediation controls as other agents.

Portal use

Open the control-agent drawer from the authenticated portal dashboard. Conversation history, run progress, tool details, approvals, resulting resources, and usage remain organization-scoped.

Examples:

  • summarize recent runtime failures and link their traces;
  • explain a Failure Atlas family and its active remediation;
  • draft a rubric or request an evaluation;
  • propose an environment run;
  • request a bounded A2A handoff to an authorized local endpoint;
  • show credit usage or rollout state.

Reads can execute under the current user's scopes. Paid or mutating actions become explicit tool proposals. Approval and rejection require an authenticated organization decision and are recorded as durable receipts.

CLI use

An enrolled device can use the same agent without a bearer token in the prompt:

dharma assistant chat --message "Show failed runs from the last analysis window" --confirm
dharma assistant history
dharma assistant status --session-id <session-id>

Approval commands open the exact proposal in the portal. The user must still be authenticated and authorized there.

API use

  • GET/POST /api/v1/orgs/{orgId}/control-agent/sessions
  • POST /api/v1/orgs/{orgId}/control-agent/sessions/{sessionId}/messages
  • GET /api/v1/orgs/{orgId}/control-agent/sessions/{sessionId}/events?afterSequence=<n>
  • POST /api/v1/orgs/{orgId}/control-agent/tool-calls/{toolCallId}/approve
  • POST /api/v1/orgs/{orgId}/control-agent/tool-calls/{toolCallId}/reject

Messages are asynchronous and usage-metered. Event cursors support interrupted-stream recovery. Tool approval and rejection use the Clerk portal session because a copied URL or organization token must not become approval authority.

Authority boundary

The control agent cannot obtain provider credentials, unrestricted shell access, arbitrary local files, or authority beyond the user's role and the target endpoint policy. Local tasks retain workspace containment, expiry, leases, registered commands, path restrictions, and read-only/no-network defaults.

The control agent's own trajectories are eligible for evaluation and remediation. It is not exempt from the controls it operates.