AI Agents

Build autonomous AI agents that can use tools, maintain memory, and access knowledge bases to complete complex tasks.

AI Agents are available on Pro and higher plans. Access them in Dashboard → Agents or via the API.

Overview

NovaKit agents use a ReAct (Reasoning, Action, Observation) loop to autonomously solve tasks:

Receive a user input
Reason about what actions to take
Act by calling tools
Observe the results
Repeat until the task is complete

Agent Features

Feature	Description
Tools	Web search, image generation, document creation, and more
Memory	Persistent memory across sessions
Knowledge Base	Upload documents for RAG retrieval
Streaming	Real-time step-by-step execution updates
Sessions	Maintain conversation context
Templates	Pre-built agents for common use cases

Endpoints

Method	Endpoint	Description
`GET`	`/agents`	List agents
`POST`	`/agents`	Create agent
`GET`	`/agents/{id}`	Get agent details
`PATCH`	`/agents/{id}`	Update agent
`DELETE`	`/agents/{id}`	Delete agent
`POST`	`/agents/{id}/run`	Run agent (streaming)
`GET`	`/agents/{id}/runs`	List agent runs
`GET`	`/agents/{id}/runs/{runId}`	Get run details
`POST`	`/agents/{id}/duplicate`	Duplicate agent

Required scope: agents

Create Agent

POST /agents

Request Body

{
  "name": "Research Assistant",
  "description": "Helps with research tasks using web search",
  "icon": "search",
  "system_prompt": "You are a helpful research assistant. Search the web to find accurate, up-to-date information and cite your sources.",
  "model": "anthropic/claude-3.5-sonnet",
  "tools": ["web_search", "web_fetch", "create_document"],
  "temperature": 0.7,
  "max_tokens": 4000,
  "max_iterations": 10,
  "memory_enabled": true
}

Parameters

Parameter	Type	Required	Default	Description
`name`	string	Yes	-	Agent name (max 100 chars)
`description`	string	No	-	Agent description (max 500 chars)
`icon`	string	No	`bot`	Icon identifier
`system_prompt`	string	Yes	-	System instructions (max 10,000 chars)
`model`	string	No	`openai/gpt-4o`	LLM model to use
`tools`	array	No	`[]`	Tool IDs to enable
`temperature`	number	No	`0.7`	Response creativity (0-2)
`max_tokens`	number	No	`4000`	Max output tokens (100-8000)
`max_iterations`	number	No	`10`	Max reasoning loops (1-20)
`memory_enabled`	boolean	No	`false`	Enable persistent memory

Response

{
  "agent": {
    "id": "agent_abc123",
    "name": "Research Assistant",
    "description": "Helps with research tasks using web search",
    "icon": "search",
    "system_prompt": "You are a helpful research assistant...",
    "model": "anthropic/claude-3.5-sonnet",
    "tools": ["web_search", "web_fetch", "create_document"],
    "temperature": 0.7,
    "max_tokens": 4000,
    "max_iterations": 10,
    "memory_enabled": true,
    "is_template": false,
    "is_public": false,
    "run_count": 0,
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

Available Tools

Tool ID	Credit Cost	Description
`web_search`	5	Search the web using Serper API
`web_fetch`	3	Fetch and parse webpage content
`generate_text`	0*	Generate text (uses LLM tokens)
`generate_image`	15	Generate images via Fal AI
`analyze_image`	5	Analyze images using vision models
`generate_chart`	2	Create chart visualizations
`create_document`	3	Create PDF, Markdown, or CSV files

*generate_text uses your token quota, not fixed credits

Tool Categories

Category	Tools
Search	`web_search`, `web_fetch`
Generation	`generate_text`, `generate_image`, `generate_chart`
Analysis	`analyze_image`
Documents	`create_document`

Run Agent

Execute an agent with streaming response.

POST /agents/{id}/run

Request Body

{
  "input": "Research the latest developments in quantum computing and create a summary document",
  "attachments": [
    {
      "type": "image",
      "url": "https://example.com/diagram.png",
      "name": "architecture.png"
    }
  ],
  "conversation_history": [
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi! How can I help?"}
  ],
  "session_id": "session_xyz789"
}

Parameters

Parameter	Type	Required	Description
`input`	string	Yes	User input (max 10,000 chars)
`attachments`	array	No	Files to include
`conversation_history`	array	No	Previous messages for context
`session_id`	string	No	Session ID for continuity

Streaming Response

The endpoint returns a Server-Sent Events (SSE) stream:

data: {"type":"start","run_id":"run_abc123","session_id":"session_xyz789"}

data: {"type":"step","run_id":"run_abc123","step":{"step_number":1,"type":"thinking","content":"Analyzing the request..."}}

data: {"type":"step","run_id":"run_abc123","step":{"step_number":2,"type":"tool_call","tool":"web_search","tool_input":{"query":"quantum computing 2025 developments"}}}

data: {"type":"step","run_id":"run_abc123","step":{"step_number":3,"type":"tool_result","tool":"web_search","tool_output":{"results":[...]}}}

data: {"type":"step","run_id":"run_abc123","step":{"step_number":4,"type":"response","content":"Based on my research..."}}

data: {"type":"done","run_id":"run_abc123","output":"Based on my research...","credits_used":25,"tokens_used":1500}

Event Types

Type	Description
`start`	Run started, includes run_id and session_id
`step`	Execution step (thinking, tool_call, tool_result, response)
`done`	Run completed successfully
`error`	Run failed with error message

Step Types

Step Type	Description
`thinking`	Agent reasoning about next action
`tool_call`	Agent calling a tool
`tool_result`	Tool execution result
`response`	Final response to user
`error`	Error during execution

Examples

import requests
import json

API_KEY = "sk_your_api_key"
BASE_URL = "https://www.novakit.ai/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Create an agent
agent_response = requests.post(
    f"{BASE_URL}/agents",
    headers=headers,
    json={
        "name": "Research Assistant",
        "system_prompt": "You are a helpful research assistant.",
        "tools": ["web_search", "web_fetch"],
        "model": "anthropic/claude-3.5-sonnet"
    }
)
agent_id = agent_response.json()["agent"]["id"]

# Run the agent with streaming
response = requests.post(
    f"{BASE_URL}/agents/{agent_id}/run",
    headers=headers,
    json={"input": "What are the latest AI developments?"},
    stream=True
)

for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('data: '):
            event = json.loads(line[6:])
            print(f"[{event['type']}]", event.get('step', {}).get('content', ''))

# Create agent with memory enabled
agent = requests.post(
    f"{BASE_URL}/agents",
    headers=headers,
    json={
        "name": "Personal Assistant",
        "system_prompt": "You are a personal assistant that remembers user preferences.",
        "tools": ["web_search"],
        "memory_enabled": True
    }
).json()["agent"]

# First conversation
run1 = run_agent(agent["id"], "My name is Alex and I prefer Python")

# Later conversation - agent remembers
run2 = run_agent(agent["id"], "What's my name and favorite language?")
# Agent will remember: "Your name is Alex and you prefer Python"

# Upload knowledge file
files = {"file": open("company_docs.pdf", "rb")}
upload = requests.post(
    f"{BASE_URL}/agents/{agent_id}/knowledge",
    headers=headers,
    files=files
).json()

# Wait for processing
file_id = upload["file"]["id"]
while True:
    status = requests.get(
        f"{BASE_URL}/agents/{agent_id}/knowledge/{file_id}",
        headers=headers
    ).json()
    if status["file"]["status"] == "completed":
        break
    time.sleep(2)

# Now run - agent will use knowledge base
run_agent(agent_id, "What does our company policy say about remote work?")

TypeScript Example

async function runAgent(agentId: string, input: string) {
  const response = await fetch(
    `https://www.novakit.ai/api/v1/agents/${agentId}/run`,
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer sk_your_api_key",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ input }),
    }
  );

  const reader = response.body?.getReader();
  const decoder = new TextDecoder();

  while (reader) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const event = JSON.parse(line.slice(6));

        switch (event.type) {
          case 'step':
            console.log(`[${event.step.type}]`, event.step.content || event.step.tool);
            break;
          case 'done':
            console.log('Final output:', event.output);
            console.log('Credits used:', event.credits_used);
            break;
          case 'error':
            console.error('Error:', event.error);
            break;
        }
      }
    }
  }
}

Knowledge Base

Upload documents for the agent to reference using RAG (Retrieval Augmented Generation).

Upload File

POST /agents/{id}/knowledge
Content-Type: multipart/form-data

Supported formats: PDF, Markdown, TXT, CSV, DOCX

List Knowledge Files

GET /agents/{id}/knowledge

Delete Knowledge File

DELETE /agents/{id}/knowledge/{fileId}

File Processing

Uploaded files are processed asynchronously:

pending - File uploaded, waiting for processing
processing - Extracting text and creating embeddings
completed - Ready for use
failed - Processing failed (check error_message)

Agent Runs

List Runs

GET /agents/{id}/runs
GET /agents/{id}/runs?status=completed&limit=10

Get Run Details

GET /agents/{id}/runs/{runId}

Returns the full run including all execution steps:

{
  "run": {
    "id": "run_abc123",
    "agent_id": "agent_xyz",
    "status": "completed",
    "input": "Research quantum computing",
    "output": "Based on my research...",
    "total_steps": 5,
    "tokens_used": 1500,
    "credits_used": 25,
    "duration_ms": 12500,
    "created_at": "2025-01-15T10:00:00Z",
    "completed_at": "2025-01-15T10:00:12Z",
    "steps": [
      {
        "step_number": 1,
        "step_type": "thinking",
        "content": "I need to search for recent quantum computing developments"
      },
      {
        "step_number": 2,
        "step_type": "tool_call",
        "tool_name": "web_search",
        "tool_input": {"query": "quantum computing 2025"}
      }
    ]
  }
}

Quota & Pricing

Agent runs use the agent_runs quota bucket plus token consumption:

Agent Run Quota

Plan	Agent Runs/Month
Pro	100
Business	500
CLI Pro	Unlimited
CLI Team	Unlimited

Credit Calculation

Agent runs are charged based on:

Base cost: 2 credits per run
Token usage: Standard chat token pricing
Tool calls: Per-tool credit costs (see tool table above)

Example calculation:

Base: 2 credits
1,500 tokens with Claude Sonnet: ~2 credits
2x web_search calls: 10 credits
1x generate_image: 15 credits
Total: ~29 credits

Top-up Pricing

Agent runs: $0.25 per run

Plan Limits

Feature	Pro	Business	CLI Pro	CLI Team
Max agents	5	20	10	50
Max tools per agent	4	7	7	7
Max iterations	10	20	20	20
Knowledge files	5 per agent	20 per agent	10 per agent	50 per agent
Max file size	10MB	25MB	25MB	50MB

Templates

Get started quickly with pre-built agent templates:

GET /agents?include_templates=true&template_category=research

Template Categories

Category	Description
`research`	Research and information gathering
`content`	Content creation and writing
`coding`	Code assistance and review
`analysis`	Data analysis and insights
`support`	Customer support and FAQ
`productivity`	Task management and automation

Error Handling

Status	Error	Solution
400	`name is required`	Provide agent name
400	`Invalid tools`	Check tool IDs are valid
402	`Agent limit reached`	Delete agents or upgrade plan
402	`Agent run quota exceeded`	Wait for reset or upgrade
403	`AI Agents are not available`	Upgrade to Pro or higher
404	`Agent not found`	Check agent ID

Best Practices

1. Write Clear System Prompts

Be specific about the agent's role, capabilities, and constraints:

You are a research assistant specialized in technology news.

When asked to research a topic:
1. Search for recent, authoritative sources
2. Summarize key findings with citations
3. Highlight any conflicting information

Always cite your sources with URLs.

2. Choose Appropriate Tools

Only enable tools the agent actually needs. More tools = more complexity.

3. Set Reasonable Limits

Start with lower max_iterations (5-10)
Increase if the agent consistently runs out of steps

4. Use Sessions for Conversations

Maintain context across multiple turns:

session_id = str(uuid.uuid4())

# Turn 1
run_agent(agent_id, "Search for AI news", session_id=session_id)

# Turn 2 - references previous context
run_agent(agent_id, "Tell me more about the first result", session_id=session_id)

5. Enable Memory for Personalization

For agents that should remember user preferences across sessions, enable memory_enabled.

Agents

On this page