Best Practices

​

Pick the right client for where your code runs

// Backend: both clients are fine
const management = new ApolloManagementClient({ organizationApiKey: process.env.AUI_ORG_API_KEY! });

// Browser: messaging only
const messaging = new ApolloMessagingClient({ publishableKey: 'pk_network_...' });

​

Reuse one client instance

// Good — module-level singleton
export const apollo = new ApolloMessagingClient({ publishableKey: PK });

// Bad — new client (and token exchange) per call
async function send(text: string) {
  const client = new ApolloMessagingClient({ publishableKey: PK });
  return client.messaging.sendMessage({ user_id, text });
}

​

Error handling

import { Apollo, ApolloError, ApolloTimeoutError } from '@aui.io/aui-client';

try {
  await client.agents.getAgent(agentId);
} catch (error) {
  if (error instanceof Apollo.NotFoundError) {
    // handle the specific case
  } else if (error instanceof ApolloTimeoutError) {
    // the request timed out — consider a longer timeoutInSeconds
  } else if (error instanceof ApolloError) {
    // any other API error: statusCode + the error envelope in body
    const body = error.body as { error?: { code?: string; request_id?: string } };
    console.error(error.statusCode, body?.error?.code, body?.error?.request_id);
  } else {
    throw error; // not an API error — don't swallow it
  }
}

​

Timeouts and retries

// Long-running list over a large window
await client.threads.listThreads({ project_id }, { timeoutInSeconds: 120 });

// Don't retry non-idempotent sends more than you must
await client.messaging.sendMessage(request, { maxRetries: 0 });

// Cancelable from the UI
const controller = new AbortController();
await client.messaging.sendMessage(request, { abortSignal: controller.signal });

​

Filter your thread lists

let page = await client.threads.listThreads({
  project_id,
  created: ['2026-07-01T00:00:00Z'],
  'page[size]': 50,
});

while (page.meta?.has_more) {
  page = await client.threads.listThreads({
    project_id,
    'page[after]': page.meta.after_cursor!,
  });
}

​

Streaming resilience

• Track seq and resume — every event and message frame carries a monotonic seq; keep the highest one you’ve processed and, if the connection drops, call streamMessage again with 'Last-Event-ID': String(lastSeq) instead of re-submitting the turn — the missed frames replay without a second billable turn (see Stream a message).
• Branch on error — a turn that fails mid-stream arrives as an error event; handle it in the same loop as the other frames.
• Persist thread_id — keep it across reconnects (and page reloads, if the conversation should survive them) to stay in the same conversation.
• Prefer REST for one-shot turns — if you don’t need live tokens, sendMessage is simpler to operate.
• Runtime v1 WebSocket sessions — for runtime v1 agents, the same rules apply to the socket: track seq, send { type: 'resume', resume_after: lastSeq } on reconnect, and register one on() handler per event (a second call replaces the first). See WebSocket.

​

Troubleshooting

​

Traces

• Branch on trace.runtime first. "v2" is the runtime’s own turn trace in your program’s vocabulary; "v1" is the typed runtime v1 record. The SDK narrows Apollo.Trace on that field — read nothing else before the branch.
• Ask inline when you need it with the reply. include_trace: true on sendMessage / streamMessage / rerun returns the trace as message.trace_info in the same request. Leave it off on hot paths — a trace is large — and fetch history through threadTrace instead.
• Keep the thread id next to the interaction id. A runtime v2 interaction is read by both (interactionTrace(id, { thread_id })); store them together when you store message.id.
• Sources for end users are citations_used, with passages_used as the fallback — not sources[].evidence, which is everything retrieval returned.
• Treat sections as additive. New sections and fields may appear; existing ones keep their names and types. Don’t parse narrative — it’s for reading.

​

Runtime v1 agents