Behavior & Edge Cases

​

Retries and rate limits

• The SDK reads the response’s Retry-After header (seconds), waits that long, and retries.
• If Retry-After is absent, it falls back to a 1-second wait.
• This repeats up to maxRetries times (default 2) before giving up and throwing a PersonaApiError with statusCode: 429.
• The wait is a fixed per-attempt wait, not exponential backoff — it matches the API’s own Retry-After contract rather than guessing at a backoff curve.

const patientClient = new PersonaClient({
  baseUrl: '...',
  credential: '...',
  maxRetries: 5, // retry up to 5 times on 429 before throwing
});

​

Pagination

const { items, pagination } = await persona.agents.list({ page: 1, limit: 20 });
// pagination: { total, page, limit, pages }

• pagination.total — the real total across all pages. Use this, not items.length.
• pagination.pages — total page count. Check this to know whether there’s a next page, rather than inferring it from items.length vs. limit.
• pagination.page/pagination.limit — echo back what you requested (or the defaults 1/20).

​

Exceptions to the envelope

​

Walking all pages

let page = 1;
const all: Agent[] = [];
for (;;) {
  const { items, pagination } = await persona.agents.list({ page, limit: 100 });
  all.push(...items);
  if (page >= pagination.pages) break;
  page += 1;
}

​

Idempotency keys

const skill = await persona.skills.create(
  { name: 'Resume Reviewer', description: '...', instructions: '...' },
  'a-key-you-generate-once-per-logical-create', // e.g. crypto.randomUUID()
);

• Use it when a create() might get retried after an ambiguous failure — a network timeout or dropped connection where you can’t tell whether the original request reached the server.
• Retrying with the same key returns the exact original response instead of creating a second resource; a different (or omitted) key creates a new one as normal.
• Keys are scoped per (domain, credential, external user if asserted) and expire after 24 hours.
• Fully opt-in — omitting the argument is identical to previous versions, no behavior change.

​

Cancellation (AbortSignal)

const controller = new AbortController();
setTimeout(() => controller.abort(), 30_000); // give up after 30s

await userClient.chat.sendMessage(agent._id, {
  messages: [{ role: 'user', content: '...' }],
  signal: controller.signal,
});

​

Async behavior

• Every method is async (or an async generator for chat.stream()/architect.stream()).
• knowledge.uploadDocuments() is synchronous server-side: it returns only once embedding finishes — expect it to take longer for larger/more files.
• There is no background/queue behavior in the SDK itself — one call = one (or several retried) HTTP request. No internal caching, no connection pooling, no state.

​

The _id vs id quirk

​

Populated vs. bare id fields

​

Empty values

• providers.list() on a runtime-plane client → empty array (not an error).
• auditLogs.list() on a runtime-plane client → empty PaginatedResult (not an error).
• mcps.testConnection()-driven tools/resources/resourceTemplates → empty arrays until testConnection() has been called at least once.
• knowledge.search() score → null if the underlying store didn’t return one.
• MemoryAgentGroup.agentName → null if the Agent no longer exists.

​

Null / undefined behavior

• undefined query params are omitted entirely — safe to pass a partial params object.
• Optional fields on input types (description?, tagline?, …) are sent only when defined.
• Array-replacing fields (skills, mcps, knowledgeBases, storeMounts, interruptOn, Skill files, Provider apiKey on update) — passing a value replaces; omitting leaves untouched. They never merge/append.

​

Ordering

• threads.list() — most recently active first (lastMessageAt descending). No other list/discover method guarantees an ordering; don’t rely on it.
• bulkDelete(ids) — best-effort; deleted/failed arrays are not guaranteed to preserve input order.

​

Validation

• Client construction validates baseUrl/credential synchronously (plain Error).
• Request validation happens server-side and surfaces as PersonaValidationError (400). Notable server-side rules: contextOverride ≤ 4000 chars (rejected, not truncated); bulkDelete ≤ 100 ids; Knowledge uploads ≤ 10 files, ≤ 20MB each, PDF/TXT/MD/JSON/CSV only; scope: 'mine' requires externalUserId.
• Mcp create() with authType: 'oauth' probes the target’s OAuth discovery endpoints synchronously — a URL that doesn’t implement OAuth discovery fails the create() itself.

​

Ownership and existence-hiding

• get()/update()/delete() on a resource your credential’s scope can’t see → 404 PersonaApiError, whether the id exists or not.
• Runtime-plane clients get empty lists/404s for control-plane-only resources (Providers) rather than loud errors.
• bulkDelete().failed[].reason is generic for the same reason — don’t try to distinguish failure kinds from it.

​

Idempotency of non-create calls

​

Context override semantics (chat)

• Never persisted to any memory file.
• Never visible to later turns.
• Capped at 4000 characters — longer values get a 400 (rejected, not truncated).

​

Thread identity

• Chat without a threadId uses an implicit deterministic thread — one conversation per Agent per user, resumed automatically across calls.
• Thread.threadId (the AG-UI id used for streaming) is distinct from Thread._id (the document id used for CRUD). Don’t mix them up.

​

No caching