Onboard an agent in ten minutes.

Before you start

You need a Heroa workspace (free or paid) and a machine with Node 18+, Python 3.10+, or Go 1.21+ for the SDK commands. API keys and vault tokens are workspace-scoped; each workspace is independently isolated.

If you have not yet created a workspace, start at the sign-up flow. The free tier supports one agent and one region.

Step 1 — Register agent identity

Every Heroa agent has a stable identity: a UUID issued at registration, a human-readable name, and an optional description. The identity persists across restarts, deployments, and region migrations.

# TypeScript
import { HeroaClient } from "@heroa/sdk";

const client = new HeroaClient({ apiKey: process.env.HEROA_API_KEY });

const agent = await client.agents.register({
  name: "lead-research-v1",
  description: "Enriches CRM leads with firmographic data. Runs nightly.",
  runtime: "r1",           // R1 is the only supported runtime
  region: "us-east"        // see step 2 for region options
});

console.log(agent.id);    // e.g. ag_01hzxk...

The returned agent.id is stable. Store it; you reference it in every subsequent API call.

Step 2 — Choose a region

Five regions are available. Choose based on data residency requirements and latency to your users. For sovereign BC-Canadian tenancy, see the Sovereign page and the bc-sovereign region docs.

• us-east — Virginia, AWS-zone-equivalent latency to east-coast NA
• us-west — Oregon, best for west-coast NA and Asian traffic
• eu-west — Dublin, GDPR-residency eligible
• asia-pacific — Singapore, lowest latency for SEA and AU
• bc-sovereign — BC Canada, single-tenant, Canadian-entity MSA, PIPEDA and BC PIPA aligned

Region is set at registration and cannot be changed in-place. To migrate a live agent to a different region, register a new identity in the target region and drain the old one.

Step 3 — Bind credentials to the vault

Heroa agents access external services through the R1 credential vault. Credentials are encrypted at rest, decrypted only inside the skill sandbox, and never written to logs or returned to callers.

# Bind a HubSpot token to the vault under a named key
const vaultEntry = await client.vault.put({
  agentId: agent.id,
  key: "hubspot_token",
  value: process.env.HUBSPOT_PRIVATE_APP_TOKEN,
  description: "HubSpot private-app token for lead-research agent"
});

// The agent reads it at runtime via the R1 vault primitive:
//   const token = await heroa.vault.get("hubspot_token");
console.log(vaultEntry.fingerprint); // SHA-256 of the value, for rotation tracking

Vault entries are scoped to a single agent by default. To share a credential across multiple agents in the same workspace, set scope: "workspace". Workspace-scoped credentials require the Team tier or higher.

Step 4 — Define the policy envelope

A policy envelope limits what the agent is permitted to do during a run. Policies are Cedar-syntax documents evaluated before every skill call. The simplest policy is a spend ceiling and an allow-list of skill names.

const policy = await client.policies.create({
  agentId: agent.id,
  document: `
    permit(principal, action == Action::"skill:invoke", resource)
    when {
      resource.name in ["hubspot:contact:read", "hubspot:contact:enrich"]
      && context.run_cost_usd < 0.50
    };
  `
});

console.log(policy.id); // po_01hzxm...

Policy documents are versioned. Any policy violation during a run is logged as a blocked action and the run is marked partial. No spend is charged for blocked calls. See the regions overview for per-region policy evaluation latency.

Step 5 — Set the promotion level

Promotion levels control how much autonomy the agent has. Start at L0 (shadow) for the first few runs; nothing happens in the real world but you get a full audit trace. Promote only once you trust the output.

• L0 shadow — runs fully, writes nothing, no external calls. Audit-only.
• L1 notify — runs and writes, sends a notification to the workspace inbox after each run. No approvals needed.
• L2 approve — holds before any write action; a workspace member must approve within the approval window (default 24 h) or the action is skipped.
• L3 autonomous — full autonomy within the policy envelope. No approval needed for individual actions.
• L4 trusted — same as L3 plus eligible for vault-scope expansion without re-approval. Requires SOC 2 report acceptance on Enterprise tier.

await client.agents.setPromotion({
  agentId: agent.id,
  level: "L0_shadow"
});

// To promote after reviewing audit logs:
await client.agents.setPromotion({
  agentId: agent.id,
  level: "L1_notify"
});

Step 6 — Run the agent

Trigger the first run manually to verify the full stack before setting a schedule.

const run = await client.agents.run({
  agentId: agent.id,
  input: { hubspot_list_id: "hs-list-007" }
});

// Poll until complete (or use a webhook — see step 7)
const result = await client.runs.wait(run.id, { timeoutMs: 120_000 });

console.log(result.status);     // "complete" | "partial" | "blocked" | "failed"
console.log(result.cost_usd);
console.log(result.audit_url);  // link to the immutable audit record

Step 7 — Set a schedule and webhook

Once the test run looks right, add a cron schedule and a completion webhook so your systems hear the result without polling.

await client.agents.update({
  agentId: agent.id,
  schedule: "0 3 * * *",   // 03:00 UTC daily
  webhook: {
    url: "https://your-service.example.com/heroa-events",
    signingSecret: process.env.HEROA_WEBHOOK_SECRET
  }
});

The webhook receives a signed POST with the run result. Verify the signature with the HMAC-SHA256 of the raw body using your signing secret before processing.