Skip to main content

Agent SDK

Dedicated SDK for Agent Cloud APIs. Available in TypeScript and Python.

TypeScript​

npm install @ainative/agent-sdk

Quick Start​

import { AINativeClient } from '@ainative/agent-sdk';

const client = new AINativeClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.ainative.studio',
});

// Register an agent
const agent = await client.agents.register({
  name: 'my-agent',
  capabilities: ['summarization', 'web_search'],
  protocols: ['a2a/1.0'],
});

// Store memory
await client.memory.remember({
  content: 'Important context from this conversation',
  entityId: 'session-123',
  importance: 0.9,
});

// Recall memory
const memories = await client.memory.recall({
  query: 'conversation context',
  entityId: 'session-123',
  limit: 5,
});

// Vector search
const results = await client.vectors.search({
  query: 'machine learning',
  limit: 10,
});

// Graph traversal
const graph = await client.graph.traverse({
  entity: 'Alice',
  maxHops: 3,
  predicates: ['works_at', 'uses'],
});

// Chat completions
const response = await client.chat.create({
  model: 'meta-llama/llama-3.3-70b-instruct',
  messages: [{ role: 'user', content: 'Hello' }],
});

Modules​

ModuleDescription
client.agentsRegister, discover, manage agent cards
client.swarmCreate and manage agent swarms
client.memoryRemember, recall, forget, reflect, profile
client.graphEntities, edges, traverse, GraphRAG
client.vectorsVector upsert and search
client.chatChat completions
client.filesFile upload and download
client.tablesNoSQL table operations
client.threadsConversation threads
client.eventsEvent streaming
client.billingUsage, budgets, alerts, credit balance
client.registryAgent registry — publish, search, rate agents

Tables​

All table methods require projectId as the first argument — it is never set on the constructor.

// Insert a row — body key is `row_data` (not `data`)
await client.tables.insert('my-project-id', 'users', {
  name: 'Alice',
  email: 'alice@example.com',
  plan: 'pro',
});

// Query rows
const rows = await client.tables.query('my-project-id', 'users', { plan: 'pro' }, { limit: 10 });

// Update a row by ID
await client.tables.update('my-project-id', 'users', 'row-uuid', { plan: 'business' });

// Delete a row by ID
await client.tables.deleteRow('my-project-id', 'users', 'row-uuid');

Response Shape​

@ainative/agent-sdk methods return the raw API payload directly — no wrapper envelope. This differs from @ainative/sdk (ZeroDBClient) which wraps responses in ApiResponse<T>.

// agent-sdk — direct payload
const memories = await client.memory.recall({ query: 'context', entityId: 'user-1', limit: 5 });
console.log(memories[0].content); // ✅ direct access

// @ainative/sdk (ZeroDBClient) — must unwrap .data
const result = await db.vectors.search('my-project', { queryVector: [...], topK: 5 });
console.log(result.data.vectors); // ✅ must access .data first

Task Classification​

import { classifyTask } from '@ainative/agent-sdk';

const classification = classifyTask('Analyze this dataset and find trends');
// { category: 'analysis', confidence: 0.92 }

Billing​

// Get usage breakdown by agent
const usage = await client.billing.getUsage({ period: '7d', agentId: 'agent-abc' });
console.log(usage.total_cost_usd, usage.breakdown);

// Set a spending budget
await client.billing.setBudget({
  agentId: 'agent-abc',
  limitUsd: 50,
  period: 'monthly',
});

// Set a cost alert
await client.billing.setAlert({
  agentId: 'agent-abc',
  thresholdPercent: 80,
  email: 'ops@mycompany.com',
});

// Get current credit balance
const balance = await client.billing.getCreditBalance();
console.log(balance.available_credits, balance.plan);

// Full billing dashboard
const dashboard = await client.billing.getDashboard();

Agent Registry​

Publish agents to the AINative agent registry so they can be discovered by other developers.

// Publish an agent to the registry
const entry = await client.registry.create({
  name: 'research-agent',
  description: 'Searches the web and synthesizes findings',
  agent_type: 'research',
  capabilities: ['web_search', 'summarization'],
  version: '1.0.0',
  tags: ['research', 'open-source'],
});

// Search the registry
const results = await client.registry.search('summarization', 10);

// Publish / unpublish
await client.registry.publish(entry.id);
await client.registry.unpublish(entry.id);

// Rate an agent
await client.registry.rate(entry.id, 5, 'Excellent summarization quality');

// List versions
const versions = await client.registry.listVersions(entry.id);

OAuth PKCE Auth​

import { generateCodeVerifier, generateCodeChallenge, buildAuthUrl } from '@ainative/agent-sdk';

const verifier = generateCodeVerifier();
const challenge = await generateCodeChallenge(verifier);
const authUrl = buildAuthUrl({ clientId: 'my-app', codeChallenge: challenge });

Python​

pip install ainative-agent-sdk

Quick Start​

from ainative import AINativeClient

client = AINativeClient(api_key="your-api-key")

# Register an agent
agent = client.agents.register(
    name="my-agent",
    capabilities=["summarization", "web_search"],
)

# Store and recall memory
client.memory.remember(
    content="User is building a RAG pipeline",
    entity_id="user-123",
    importance=0.8,
)

memories = client.memory.recall(query="user project", entity_id="user-123")

# Vector search
results = client.vectors.search(query="machine learning", limit=10)

# Chat
response = client.chat.create(
    model="meta-llama/llama-3.3-70b-instruct",
    messages=[{"role": "user", "content": "Hello"}],
)

Async Support​

pip install ainative-agent-sdk[async]
import asyncio
from ainative import AINativeClient

async def main():
    client = AINativeClient(api_key="your-api-key")
    # All methods support async via httpx
    memories = await client.memory.recall_async(query="context", entity_id="user-123")

asyncio.run(main())

Error Handling​

Both SDKs export the same error hierarchy:

ErrorDescription
APIErrorBase error for all API failures
AuthenticationErrorInvalid or expired API key
RateLimitErrorRate limit exceeded
NetworkErrorConnection or timeout failure

Next Steps​