Ultra SDK Guide

5-Minute Quickstart

import { UltraClient } from '@ultra/sdk'

const ultra = new UltraClient({
  baseUrl: 'https://ultra.egomonk.com',
  agentKey: 'agk_<keyId>.<secret>'
})

const up = await ultra.uploadFile({
  file: new Blob(['hello from ultra']),
  filename: 'hello.txt',
  ttlSeconds: 120,
  authMode: 'agent',
  allowedAgentIds: ['agent-receiver'],
  metadata: { channel: 'demo' }
})

const share = await ultra.resolveShare(up.shareId)
const grant = await ultra.requestGrant(share.id)
const file = await ultra.downloadWithGrant(grant.targetId, grant.accessToken)

Authentication Model

• agk_...: root agent credential (store server-side only).
• aat_...: short-lived access token minted automatically.
• agrt_...: one-time grant token to fetch one target.

Primitive API Mapping

• uploadFile → POST /api/upload
• resolveShare → GET /api/share/{shareId}
• requestGrant → POST /api/agent/grants
• downloadWithGrant → GET /api/dl/{id}

Cookbook

Agent Handoff (A → B)

await ultra.handoff({
  toAgentId: 'agent-b',
  file,
  filename: 'artifact.bin',
  ttlSeconds: 120
})

Channel Fan-Out

await ultra.channelSend({
  channel: 'research',
  file,
  filename: 'result.json',
  allowedAgentIds: ['agent-a', 'agent-b', 'agent-c']
})

Open Share

{
  "mode": "open",
  "allowedAgentIds": [],
  "maxUses": 0,
  "metadata": {}
}

Agent-Gated Share

{
  "mode": "agent",
  "allowedAgentIds": ["agent-a", "agent-b"],
  "maxUses": 0,
  "metadata": { "workflow": "review" }
}

One-Time Handoff

{
  "mode": "agent",
  "allowedAgentIds": ["agent-receiver"],
  "maxUses": 1,
  "metadata": { "step": "handoff" }
}

Channel Fan-Out Policy

{
  "mode": "agent",
  "allowedAgentIds": ["agent-a", "agent-b", "agent-c"],
  "maxUses": 0,
  "metadata": { "channel": "research" }
}

Production Guidance

• Retries: treat grants as one-use and reissue grants for each retry attempt.
• Idempotency: store caller-side operation IDs and short-circuit duplicate upload/grant requests.
• TTL Strategy: map TTL to workflow stage duration plus safety margin, not a single global value.
• Observability: log shareId, targetId, agentId, errorCode, and latency per step (resolve/grant/fetch).

Common Agent Workflows

Secure Handoff (A → B)

const up = await ultra.uploadFile({
  file,
  filename: 'artifact.bin',
  authMode: 'agent',
  allowedAgentIds: ['agent-b'],
  ttlSeconds: 120
})
const grant = await ultra.requestGrant(up.shareId)
await ultra.downloadWithGrant(grant.targetId, grant.accessToken)

Fan-Out to Channel Workers

await ultra.channelSend({
  channel: 'research',
  file,
  filename: 'task.json',
  allowedAgentIds: ['agent-a', 'agent-b', 'agent-c']
})

Grant Failure Recovery

try {
  await ultra.downloadWithGrant(targetId, accessToken)
} catch (err) {
  if (String(err).includes('invalid_grant') || String(err).includes('grant_already_used')) {
    const nextGrant = await ultra.requestGrant(shareId)
    await ultra.downloadWithGrant(nextGrant.targetId, nextGrant.accessToken)
  }
}