---
title: "Agent SDK"
description: "TypeScript and Python SDKs for Agent Cloud APIs — agents, swarm, memory, graph, vectors, chat, files"
canonical: "https://docs.ainative.studio/docs/sdks/agent-sdk"
last-updated: "2026-10-03T21:47:10.764Z"
---

# Agent SDK

Source: https://docs.ainative.studio/docs/sdks/agent-sdk

> TypeScript and Python SDKs for Agent Cloud APIs — agents, swarm, memory, graph, vectors, chat, files

## Agent SDK

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

## TypeScript

```bash
npm install @ainative/agent-sdk
```

### Quick Start

```typescript
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

| Module | Description |
|--------|-------------|
| `client.agents` | Register, discover, manage agent cards |
| `client.swarm` | Create and manage agent swarms |
| `client.memory` | Remember, recall, forget, reflect, profile |
| `client.graph` | Entities, edges, traverse, GraphRAG |
| `client.vectors` | Vector upsert and search |
| `client.chat` | Chat completions |
| `client.files` | File upload and download |
| `client.tables` | NoSQL table operations |
| `client.threads` | Conversation threads |
| `client.events` | Event streaming |
| `client.billing` | Usage, budgets, alerts, credit balance |
| `client.registry` | Agent registry — publish, search, rate agents |

### Tables

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

```typescript
// 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>`.

```typescript
// 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

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

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

### Billing

```typescript
// 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.

```typescript
// 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

```typescript
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

```bash
pip install ainative-agent-sdk
```

### Quick Start

```python
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

```python
pip install ainative-agent-sdk[async]
```

```python
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:

| Error | Description |
|-------|-------------|
| `APIError` | Base error for all API failures |
| `AuthenticationError` | Invalid or expired API key |
| `RateLimitError` | Rate limit exceeded |
| `NetworkError` | Connection or timeout failure |

## Next Steps

- [Agent Runtime](/docs/sdks/agent-runtime) — Embeddable agent execution engine
- [Agent Cloud](/docs/agent-cloud/overview) — Deploy agents to the cloud
- [TypeScript SDK](/docs/sdks/typescript) — Full AINative SDK