Exa SDK Patterns
Developmentexa-sdk-patternsExa SDK Patterns is an Agent Skill for development published in the Dicklesworthstone/pi_agent_rust repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Apply production-ready Exa SDK patterns for TypeScript and Python. Use when implementing Exa integrations, refactoring SDK usage, or establishing team coding standards for Exa. Trigger with phrases like "exa SDK patterns", "exa best practices", "exa code patterns", "idiomatic exa".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Dicklesworthstone/pi_agent_rust/blob/HEAD/tests/ext_conformance/artifacts/plugins-community/plugins/saas-packs/exa-pack/skills/exa-sdk-patterns/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/exa-sdk-patterns, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Exa SDK Patterns
Overview
Production-ready patterns for Exa SDK usage in TypeScript and Python.
Prerequisites
- Completed
exa-install-authsetup - Familiarity with async/await patterns
- Understanding of error handling best practices
Instructions
Step 1: Implement Singleton Pattern (Recommended)
// src/exa/client.ts
import { ExaClient } from '@exa/sdk';
let instance: ExaClient | null = null;
export function getExaClient(): ExaClient {
if (!instance) {
instance = new ExaClient({
apiKey: process.env.EXA_API_KEY!,
// Additional options
});
}
return instance;
}
Step 2: Add Error Handling Wrapper
import { ExaError } from '@exa/sdk';
async function safeExaCall<T>(
operation: () => Promise<T>
): Promise<{ data: T | null; error: Error | null }> {
try {
const data = await operation();
return { data, error: null };
} catch (err) {
if (err instanceof ExaError) {
console.error({
code: err.code,
message: err.message,
});
}
return { data: null, error: err as Error };
}
}
Step 3: Implement Retry Logic
async function withRetry<T>(
operation: () => Promise<T>,
maxRetries = 3,
backoffMs = 1000
): Promise<T> {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
return await operation();
} catch (err) {
if (attempt === maxRetries) throw err;
const delay = backoffMs * Math.pow(2, attempt - 1);
await new Promise(r => setTimeout(r, delay));
}
}
throw new Error('Unreachable');
}
Output
- Type-safe client singleton
- Robust error handling with structured logging
- Automatic retry with exponential backoff
- Runtime validation for API responses
Error Handling
| Pattern | Use Case | Benefit |
|---|---|---|
| Safe wrapper | All API calls | Prevents uncaught exceptions |
| Retry logic | Transient failures | Improves reliability |
| Type guards | Response validation | Catches API changes |
| Logging | All operations | Debugging and monitoring |
Examples
Factory Pattern (Multi-tenant)
const clients = new Map<string, ExaClient>();
export function getClientForTenant(tenantId: string): ExaClient {
if (!clients.has(tenantId)) {
const apiKey = getTenantApiKey(tenantId);
clients.set(tenantId, new ExaClient({ apiKey }));
}
return clients.get(tenantId)!;
}
Python Context Manager
from contextlib import asynccontextmanager
from exa import ExaClient
@asynccontextmanager
async def get_exa_client():
client = ExaClient()
try:
yield client
finally:
await client.close()
Zod Validation
import { z } from 'zod';
const exaResponseSchema = z.object({
id: z.string(),
status: z.enum(['active', 'inactive']),
createdAt: z.string().datetime(),
});
Resources
Next Steps
Apply patterns in exa-core-workflow-a for real-world usage.