Agent onboarding & connection

An agent is the unit that policies latch onto. Onboarding registers the agent, declares the tools it can call, and connects your runtime to the PDP.

Three ways to onboard

Connect an existing agent
Import from GitHub
Fork from the Registry

akhara agents connect \
  --id health-ai \
  --name "Health Insights" \
  --base-url https://your-agent.internal.akhara.dev \
  --api-key "$AGENT_KEY" \
  --tools lab_trends,care_plan_update,renew_meds,member_record \
  --surface android

Provisions a sandbox runtime from a repo.

akhara agents add --github your-org/health-agent

Copy a catalog agent’s metadata and provision its tools/env.

akhara registry fork health-insights-baseline

The agent record

All read responses strip secrets, only a masked key is ever returned.

{
  "id": "health-ai",
  "name": "Health Insights",
  "source": "builtin",
  "status": "connected",
  "baseUrl": "https://…",
  "apiKeyMasked": "ak_live_••••4f2a",
  "categories": ["healthcare"],
  "tools": ["lab_trends", "care_plan_update", "renew_meds", "member_record"],
  "policyIds": ["healthcare-0", "latch-1", "reliability-3"],
  "runtime": {
    "status": "provisioned",
    "boundary": "android-emulator",
    "env": { "GATEWAY": "https://api.akhara.dev" }
  },
  "createdAt": 0,
  "updatedAt": 0
}

Field	Notes
`id`	Stable identifier; the PEP sends this as `agentId`. Must match `^[a-z-]+$`-style ids.
`source`	`builtin` · `url` · `github` · `fork`
`tools[]`	Declared tool names: used to match action latches (after normalization).
`policyIds[]`	Domain policies attached on top of the baseline. See Policies.
`runtime`	Present once provisioned; `env.GATEWAY` points the sandbox back at the PDP.

Unknown agentId on an authorize call returns 404 agent not found. Register the agent before pointing a PEP at it.

Connect your runtime (embed the PEP)

Add the PEP to your agent and point it at the PDP. Full language references live under SDK.

import { PolicyEnforcementPoint } from "@akhara/pep";

const pep = new PolicyEnforcementPoint({
  baseUrl: process.env.AKHARA_URL ?? "https://api.akhara.dev",
  agentId: "health-ai",
  session: sessionId,
});

val pep = PolicyEnforcementPoint(
  AkharaPolicyClient(
    baseUrl = "https://api.akhara.dev",
    agentId = "health-ai",
  )
)

Tool normalization

Declare tools using whatever your agent emits. Akhara canonicalizes names before matching latches:

Your agent emits	Akhara matches
`renew_medications`	`renew_meds`
`medication_renewal`	`renew_meds`
`view_lab_trends`	`lab_trends`
`care_task_update`	`care_plan_update`

Provision a runtime (optional)

For GitHub/forked agents, provision a sandbox boundary:

akhara agents provision health-ai

POST /api/agents/health-ai/provision

See Environments for the five-step provisioning flow.

Next: latch policies

Attach domain policies on top of the always-on enterprise baseline.

Get started

How it works

Enterprise onboarding

SDK

Agent onboarding & connection

Three ways to onboard

The agent record

Connect your runtime (embed the PEP)

Tool normalization

Provision a runtime (optional)

Next: latch policies

​Three ways to onboard

​The agent record

​Connect your runtime (embed the PEP)

​Tool normalization

​Provision a runtime (optional)

Next: latch policies

Three ways to onboard

The agent record

Connect your runtime (embed the PEP)

Tool normalization

Provision a runtime (optional)