---
title: "Agents"
description: "Create and manage AI agents with configurable tools, memory, and execution strategies"
canonical: "https://docs.ainative.studio/docs/agent-framework/agents"
last-updated: "2026-10-22T17:48:46.689Z"
---

# Agents

Source: https://docs.ainative.studio/docs/agent-framework/agents

> Create and manage AI agents with configurable tools, memory, and execution strategies

# Agents

This page covers the full lifecycle of a platform-level agent: registration, plugin management, durable state, and workspace snapshots.

**Base URL:** `https://api.ainative.studio`

---

## Agent Registration

### Register a Platform Agent

<span className="badge badge--post">POST</span> `/api/v1/public/agents/register`

Register a new platform-level agent. Returns a stable `agent_id` and a one-time `api_key` — store the key immediately, it cannot be retrieved again.

No authentication required.

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agent_name` | string | Yes | Human-readable label (1–128 chars) |
| `capabilities` | string[] | Yes | Capability slugs the agent claims (e.g. `"memory"`, `"search"`) |
| `callback_url` | string | Yes | HTTPS URL the platform will POST events to |

```bash
curl -X POST https://api.ainative.studio/api/v1/public/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "security-scanner",
    "capabilities": ["vulnerability_scan", "code_review"],
    "callback_url": "https://my-system.example.com/webhooks/agent"
  }'
```

```python
import httpx

resp = httpx.post(
    "https://api.ainative.studio/api/v1/public/agents/register",
    json={
        "agent_name": "security-scanner",
        "capabilities": ["vulnerability_scan", "code_review"],
        "callback_url": "https://my-system.example.com/webhooks/agent",
    },
)
data = resp.json()
agent_id = data["agent_id"]
api_key = data["api_key"]  # Store this — it will not be shown again
```

**Response**

```json
{
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "api_key": "pa_Xk3mN9p..."
}
```

| Field | Description |
|-------|-------------|
| `agent_id` | Stable UUID for the agent |
| `api_key` | Bearer token prefixed `pa_`. Shown once — store securely. |

---

## Plugins

Plugins are capability packages installed from the platform registry onto a specific agent. Each agent has its own isolated plugin list.

**Path prefix:** `/api/v1/agents/{agent_id}/plugins`

### Install a Plugin

<span className="badge badge--post">POST</span> `/api/v1/agents/{agent_id}/plugins`

Install a plugin from the registry onto the agent. The agent must exist and have `ACTIVE` status. Installing the same plugin twice returns `409 Conflict`.

**Auth required**

| Path param | Description |
|------------|-------------|
| `agent_id` | The target agent's ID |

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `plugin_id` | string | Yes | Plugin ID from the registry |

```bash
curl -X POST https://api.ainative.studio/api/v1/agents/550e8400-e29b-41d4-a716-446655440001/plugins \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "web-search-v2"}'
```

```python
import httpx

resp = httpx.post(
    "https://api.ainative.studio/api/v1/agents/{agent_id}/plugins",
    headers={"Authorization": "Bearer <your_api_key>"},
    json={"plugin_id": "web-search-v2"},
)
print(resp.json())
```

**Response** `201 Created`

```json
{
  "id": "inst-3f8a12bc4d90",
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "plugin_id": "web-search-v2",
  "plugin_name": "Web Search",
  "plugin_version": "2.1.0",
  "plugin_description": "Real-time web search with snippet extraction",
  "tools": [
    {"name": "search_web", "description": "Search the web for a query"}
  ],
  "installed_by": "user-uuid",
  "installed_at": "2026-04-25T10:00:00Z"
}
```

---

### List Installed Plugins

<span className="badge badge--get">GET</span> `/api/v1/agents/{agent_id}/plugins`

List all plugins installed on a specific agent, including metadata from the plugin registry.

**Auth required**

```bash
curl https://api.ainative.studio/api/v1/agents/{agent_id}/plugins \
  -H "Authorization: Bearer <your_api_key>"
```

**Response**

```json
{
  "plugins": [
    {
      "id": "inst-3f8a12bc4d90",
      "agent_id": "550e8400-e29b-41d4-a716-446655440001",
      "plugin_id": "web-search-v2",
      "plugin_name": "Web Search",
      "plugin_version": "2.1.0",
      "tools": [...],
      "installed_by": "user-uuid",
      "installed_at": "2026-04-25T10:00:00Z"
    }
  ],
  "total": 1
}
```

---

### Uninstall a Plugin

<span className="badge badge--delete">DELETE</span> `/api/v1/agents/{agent_id}/plugins/{plugin_id}`

Remove a plugin from an agent. Decrements the plugin's install count in the registry.

**Auth required**

Returns `204 No Content` on success, `404` if the plugin is not installed.

```bash
curl -X DELETE \
  https://api.ainative.studio/api/v1/agents/{agent_id}/plugins/web-search-v2 \
  -H "Authorization: Bearer <your_api_key>"
```

---

## Durable State

Each agent has isolated, ZeroDB-backed NoSQL tables. State persists between agent invocations and survives process restarts.

**Path prefix:** `/api/v1/cloud/agents/{agent_id}`

Default storage limit: `MAX_AGENT_STORAGE_BYTES` (see `/state/info` for current value).

### Query Agent State

<span className="badge badge--post">POST</span> `/api/v1/cloud/agents/{agent_id}/sqlite/execute`

Query rows from an agent's durable state table with optional key-value filters.

**Request body**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `table_name` | string | `"default"` | Table name within agent namespace (max 128 chars) |
| `filter` | object | null | MongoDB-style key-value filter on row data |
| `limit` | integer | 100 | Max rows to return (1–1000) |
| `offset` | integer | 0 | Pagination offset |

```bash
curl -X POST \
  https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/sqlite/execute \
  -H "Content-Type: application/json" \
  -d '{
    "table_name": "session_cache",
    "filter": {"status": "active"},
    "limit": 50
  }'
```

**Response**

```json
{
  "status": "success",
  "rows": [
    {"id": "row-1", "status": "active", "data": {...}}
  ],
  "total": 1
}
```

---

### Get State Info

<span className="badge badge--get">GET</span> `/api/v1/cloud/agents/{agent_id}/sqlite/info`

Get table list, row counts, and storage usage for an agent's durable state.

```bash
curl https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/sqlite/info
```

**Response**

```json
{
  "status": "success",
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "tables": ["default", "session_cache"],
  "table_count": 2,
  "size_bytes": 204800,
  "max_size_bytes": 10485760,
  "usage_percent": 1.95,
  "total_rows": 312
}
```

---

### Destroy Agent State

<span className="badge badge--delete">DELETE</span> `/api/v1/cloud/agents/{agent_id}/sqlite`

Permanently delete all ZeroDB tables and rows for an agent. **This action is irreversible.**

```bash
curl -X DELETE \
  https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/sqlite
```

---

### Get Storage Usage Breakdown

<span className="badge badge--get">GET</span> `/api/v1/cloud/agents/{agent_id}/state/usage`

Detailed breakdown by storage category: KV store, NoSQL tables, memory records, and snapshots.

---

### Set State TTL

<span className="badge badge--put">PUT</span> `/api/v1/cloud/agents/{agent_id}/state/ttl`

Configure how long durable state is retained before garbage collection. Default is 30 days.

**Request body**

| Field | Type | Description |
|-------|------|-------------|
| `ttl_days` | integer | TTL in days (1–365) |

```bash
curl -X PUT \
  https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/state/ttl \
  -H "Content-Type: application/json" \
  -d '{"ttl_days": 90}'
```

---

### List Expiring Agents

<span className="badge badge--get">GET</span> `/api/v1/cloud/state/expiring`

List agents whose durable state will expire within the next 7 days. Useful for monitoring dashboards.

---

### Trigger Garbage Collection

<span className="badge badge--post">POST</span> `/api/v1/cloud/state/gc`

Immediately delete all expired agent state (KV stores, tables, memory records, snapshots past their TTL).

---

## Workspace Snapshots

Snapshots are atomic, point-in-time captures of all agent state. Use them for checkpointing, rollback, and forking agents into parallel branches.

### Create Snapshot

<span className="badge badge--post">POST</span> `/api/v1/cloud/agents/{agent_id}/snapshot`

Captures memory, KV store, NoSQL database, and conversation history atomically.

**Request body** (optional)

| Field | Type | Description |
|-------|------|-------------|
| `label` | string | Human-readable label (max 255 chars) |
| `metadata` | object | Arbitrary key-value metadata |

```bash
curl -X POST \
  https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/snapshot \
  -H "Content-Type: application/json" \
  -d '{"label": "pre-refactor-checkpoint", "metadata": {"branch": "feature/auth"}}'
```

**Response**

```json
{
  "status": "success",
  "snapshot_id": "snap-abc123",
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "label": "pre-refactor-checkpoint",
  "created_at": "2026-04-25T10:00:00Z"
}
```

---

### Restore from Snapshot

<span className="badge badge--post">POST</span> `/api/v1/cloud/agents/{agent_id}/restore/{snapshot_id}`

Restore all agent state from a snapshot. **Current state is overwritten.**

```bash
curl -X POST \
  https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/restore/snap-abc123
```

---

### Fork Agent from Snapshot

<span className="badge badge--post">POST</span> `/api/v1/cloud/agents/{agent_id}/fork/{snapshot_id}`

Create a new agent with a full copy of state from an existing snapshot. Useful for running parallel experiments.

**Request body**

| Field | Type | Description |
|-------|------|-------------|
| `new_agent_id` | string | ID for the forked agent (1–255 chars) |

```bash
curl -X POST \
  https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/fork/snap-abc123 \
  -H "Content-Type: application/json" \
  -d '{"new_agent_id": "security-scanner-fork-1"}'
```

---

### List Snapshots

<span className="badge badge--get">GET</span> `/api/v1/cloud/agents/{agent_id}/snapshots`

List available snapshots with pagination.

**Query parameters**

| Param | Default | Description |
|-------|---------|-------------|
| `limit` | 20 | Max snapshots to return (1–100) |
| `offset` | 0 | Pagination offset |

```bash
curl "https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/snapshots?limit=10"
```

---

## Trust Scores

Trust scores quantify agent reliability on a 0–100 scale using three sub-dimensions: reliability, responsiveness, and compliance.

### Get Trust Score

<span className="badge badge--get">GET</span> `/api/v1/agents/{agent_id}/trust`

**Auth required**

```bash
curl https://api.ainative.studio/api/v1/agents/{agent_id}/trust \
  -H "Authorization: Bearer <your_api_key>"
```

**Response**

```json
{
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "score": 87,
  "reliability": 92,
  "responsiveness": 85,
  "compliance": 84
}
```

---

### Trust Leaderboard

<span className="badge badge--get">GET</span> `/api/v1/agents/trust/leaderboard`

Top N active agents ranked by trust score.

**Query parameters**

| Param | Default | Description |
|-------|---------|-------------|
| `limit` | 50 | Max agents to return (1–100) |

---

### Trust History

<span className="badge badge--get">GET</span> `/api/v1/agents/{agent_id}/trust/history`

Daily trust score history for an agent.

**Query parameters**

| Param | Default | Description |
|-------|---------|-------------|
| `days` | 30 | History window in days (1–365) |

---

### Trust Distribution

<span className="badge badge--get">GET</span> `/api/v1/agents/trust/distribution`

Platform-wide distribution of trust scores across 10 decile buckets.

---

### Trust Recommendations

<span className="badge badge--get">GET</span> `/api/v1/agents/{agent_id}/trust/recommendations`

Actionable tips to improve an agent's trust score.

---

## MCP Trust Gate

Control which agents are allowed to use an MCP server instance by enforcing a minimum trust score.

### Set Trust Gate

<span className="badge badge--put">PUT</span> `/api/v1/mcp/instances/{instance_id}/trust-gate`

Set the minimum trust score required to access an MCP server. Only the instance owner can set the gate.

**Request body**

| Field | Type | Description |
|-------|------|-------------|
| `min_trust_score` | integer | Minimum score (0–100) |

```bash
curl -X PUT \
  https://api.ainative.studio/api/v1/mcp/instances/{instance_id}/trust-gate \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"min_trust_score": 75}'
```

---

### Get Trust Gate

<span className="badge badge--get">GET</span> `/api/v1/mcp/instances/{instance_id}/trust-gate`

Get the current trust threshold configuration for an MCP server instance.

**Response**

```json
{
  "instance_id": "mcp-instance-uuid",
  "min_trust_score": 75,
  "has_gate": true
}
```