Documentation
OpenAPIAgent index

Managed agents

Dharma-managed agents run as tenant-bound ADK revisions behind the organization API. The browser never calls the runtime or model provider directly.

Lifecycle

  1. Purchase or sponsored entitlement activates provisioning.
  2. Dharma creates or binds the organization runtime and budget controls.
  3. Create a managed agent.
  4. Create and deploy an immutable revision.
  5. Submit asynchronous multimodal runs.
  6. Inspect ordered events, trace references, and usage settlement.
  7. Evaluate trajectories and release a signed remediation revision.

The portal distinguishes provisioning, ready, and failed. Do not send production traffic until the runtime binding and active revision both report ready.

POST /api/orgs/{orgId}/managed-agents creates both the draft agent and revision 1. The response contains agent.id and revision.id; a separate source-repository upload is not required unless the organization deliberately binds its own immutable source provenance.

Set runtimeConfig.systemInstruction when creating the agent or a successor revision. It is the installed, immutable role and operating contract for that revision; the per-run prompt remains the customer request. Keep the instruction below 20,000 characters and do not place credentials in it.

# Read the agent and every immutable revision.
curl --fail-with-body \
  "https://www.dharma-ai.io/api/orgs/$DHARMA_ORG_ID/managed-agents/$AGENT_ID" \
  -H "Authorization: Bearer $DHARMA_API_TOKEN"

# Create another candidate revision.
curl --fail-with-body -X POST \
  "https://www.dharma-ai.io/api/orgs/$DHARMA_ORG_ID/managed-agents/$AGENT_ID/revisions" \
  -H "Authorization: Bearer $DHARMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data @revision.json

# Deploy the exact candidate returned by create-agent or create-revision.
curl --fail-with-body -X POST \
  "https://www.dharma-ai.io/api/orgs/$DHARMA_ORG_ID/managed-agents/$AGENT_ID/deploy" \
  -H "Authorization: Bearer $DHARMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data "{\"revisionId\":\"$REVISION_ID\"}"

The current managed runtime accepts Dharma-registered tool adapters and evidence declared in each run. It does not execute an arbitrary customer callback merely because a tool name appears in a prompt. Customer systems can execute their deterministic retrieval or mutation locally, pass bounded results as visible evidence, or use registered task/A2A endpoints. A customer-hosted callback tool contract requires a separately approved integration.

Submit a run

POST /api/orgs/{orgId}/agent-runs accepts a model-neutral managed-run request defined by the OpenAPI contract. A request can include text and approved multimodal artifacts. Large binary input should use the artifact mechanism defined by the current schema rather than embedding secrets or unbounded data.

curl --request POST \
  "https://www.dharma-ai.io/api/orgs/$DHARMA_ORG_ID/agent-runs" \
  --header "Authorization: Bearer $DHARMA_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: garment-appraisal-1847" \
  --data @request.json

The response is asynchronous. Use:

  • GET /api/orgs/{orgId}/agent-runs/{runId} for status and result;
  • GET /api/orgs/{orgId}/agent-runs/{runId}/events for ordered execution and trace events;
  • GET /api/orgs/{orgId}/managed-traces for customer-visible trace records;
  • GET /api/v1/orgs/{orgId}/agent-fabric/usage for settled credits.

Revisions and skills

Managed agents execute immutable revisions. A signed remediation bundle creates a new revision; it does not mutate an in-flight run. Existing work remains pinned to the revision and bundle present when it started.

The first organization release requires explicit approval after its gates. Subsequent low-risk releases may follow the organization's approved auto-update policy. High-risk or destructive changes remain approval-bound.

Failure behavior

A provider outage, budget rejection, missing active revision, or runtime deployment failure must return a controlled error or failed terminal state. It must not fall back to mock output or an unrelated provider silently.