AI Agents Documentation

Create custom AI assistants with multi-provider support, tool integration, and persistent conversations.

Overview

TPMJS Agents let you create custom AI assistants powered by any LLM provider. Build agents with custom system prompts, attach tools from the registry, and have persistent conversations through a streaming API.

๐Ÿค–

Multi-Provider

Support for OpenAI, Anthropic, Google, Groq, and Mistral - bring your own API keys

๐Ÿ”ง

Tool Integration

Attach individual tools or entire collections to give your agent capabilities

๐Ÿ’ฌ

Persistent Conversations

Full conversation history with streaming responses and tool call visualization

Agents are user-owned and require authentication. Each agent gets a unique UID that can be used in API calls.

API Keys Setup

Before creating agents, you need to add your AI provider API keys. Keys are encrypted using AES-256 and stored securely.

1. Navigate to API Keys Settings

Go to Dashboard โ†’ Settings โ†’ API Keys to manage your provider keys.

2. Add Your Provider Keys

Click "Add Key" for each provider you want to use:

OpenAI

GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo - Get key

Anthropic

Claude 3.5 Sonnet, Claude 3 Opus, Claude 3.5 Haiku - Get key

Google

Gemini 2.0 Flash, Gemini 1.5 Pro - Get key

Groq

Llama 3.3 70B, Llama 3.1 8B, Mixtral 8x7B - Get key

Mistral

Mistral Large, Mistral Small - Get key

Security

๐Ÿ” Encryption: Your API keys are encrypted using AES-256-GCM before being stored. Only you can use your keys, and they're never exposed in API responses - only a hint of the last 4 characters is shown.

Creating Agents

Create an agent to customize its behavior with a system prompt, choose the AI model, and configure execution parameters.

Basic Information

ParameterTypeRequiredDescription
Namestring
Yes
Display name for your agent (max 100 chars)
UIDstringNoURL-friendly identifier (auto-generated from name). Used in API calls.
DescriptionstringNoBrief description of what the agent does (max 500 chars)

Model Configuration

ParameterTypeRequiredDescription
Providerenum
Yes
AI provider (OpenAI, Anthropic, Google, Groq, Mistral)
Modelstring
Yes
Specific model ID (e.g., gpt-4o, claude-sonnet-4-20250514)
System PromptstringNoInstructions that define how the agent behaves (max 10,000 chars)
TemperaturenumberNoResponse randomness (0 = deterministic, 2 = creative). Default: 0.7

Execution Limits

ParameterTypeRequiredDescription
Max Tool CallsnumberNoMaximum tool calls per response turn. Prevents runaway loops. Default: 20
Context MessagesnumberNoNumber of recent messages included in context window. Default: 10

Example System Prompt

You are a helpful research assistant specializing in web scraping and data analysis.

When asked to research a topic:
1. Use available web scraping tools to gather information
2. Analyze and synthesize the data
3. Present findings in a clear, structured format

Always cite your sources and be transparent about limitations.

Attaching Tools

Give your agent capabilities by attaching tools from the TPMJS registry. You can attach individual tools or entire collections.

Adding Individual Tools

From your agent's detail page, use the "Add Tool" button to search and attach specific tools from the registry. Each tool appears with its name, description, and any required environment variables.

Example tools you might attach:
- @firecrawl/ai-sdk::scrapeTool - Web scraping
- @exalabs/ai-sdk::webSearch - Web search
- @tpmjs/hello::helloWorldTool - Simple test tool

Adding Collections

Collections let you attach multiple related tools at once. If you've created MCP collections, you can attach the entire collection to your agent.

Tool Order

Tools are presented to the AI model in the order they appear. You can drag to reorder tools to prioritize certain capabilities.

Required API Keys

Note: Some tools require API keys (e.g., Firecrawl, Exa). You'll need to add these keys in your API Keys settings. The required environment variables are shown on each tool's card.

Chat Interface

Interact with your agents through the built-in chat interface with streaming responses and tool call visualization.

Starting a Conversation

Click "Chat with Agent" from your agent's detail page or navigate directly to /dashboard/agents/[id]/chat.

Features

๐Ÿ’ฌ

Conversation History

Previous conversations appear in the sidebar. Click to resume any conversation.

โšก

Streaming Responses

Responses stream in real-time as the AI generates them.

๐Ÿ”ง

Tool Calls

When the agent uses a tool, you'll see the tool name and can expand to view parameters.

๐Ÿ“Š

Token Usage

Token counts are tracked and displayed for monitoring usage.

Keyboard Shortcuts

Enter - Send message

Shift + Enter - New line

Supported Providers

TPMJS Agents support multiple AI providers. Each provider offers different models with varying capabilities and pricing.

OpenAI

Industry-leading models with excellent tool use support.

gpt-4o
gpt-4o-mini
gpt-4-turbo
gpt-3.5-turbo

Anthropic

Claude models known for nuanced understanding and safety.

claude-sonnet-4-20250514
claude-3-5-haiku-20241022
claude-3-opus-20240229

Google

Gemini models with multimodal capabilities.

gemini-2.0-flash-exp
gemini-1.5-pro
gemini-1.5-flash

Groq

Ultra-fast inference for open-source models.

llama-3.3-70b-versatile
llama-3.1-8b-instant
mixtral-8x7b-32768

Mistral

European AI models with strong multilingual support.

mistral-large-latest
mistral-small-latest

Conversation API

Integrate agent conversations into your own applications using the streaming API.

Endpoint

POST /api/{username}/agents/{agent-uid}/conversation/{conversationId}

username: The agent owner's username

agent-uid: The agent's unique identifier (slug)

conversationId: Unique ID for the conversation (create your own or use a new ID to start a new conversation)

Authentication Required: Include the header Authorization: Bearer YOUR_TPMJS_API_KEY in all requests. Get your API key from the dashboard.

Request Body

ParameterTypeRequiredDescription
messagestring
Yes
The user message to send to the agent
envobjectNoAdditional environment variables for tool execution

Example: JavaScript Client

const username = 'ajax';  // Agent owner's username
const agentUid = 'research-assistant';  // Agent UID
const conversationId = 'conv-' + Date.now();
const apiKey = 'tpmjs_sk_...';  // Your TPMJS API key

const response = await fetch(
  `https://tpmjs.com/api/${username}/agents/${agentUid}/conversation/${conversationId}`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`,
    },
    body: JSON.stringify({ message: 'Search for AI tools' }),
  }
);

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

while (true) {
  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('event: ')) {
      const event = line.slice(7);
      console.log('Event:', event);
    }
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      console.log('Data:', data);
    }
  }
}

SSE Events

The conversation API uses Server-Sent Events (SSE) for streaming responses.

chunk

Streaming text content from the AI response.

{ "text": "Here is my response..." }
tool_call

Indicates the agent is calling a tool.

{ "toolCallId": "call_abc123", "toolName": "webSearch", "input": { "query": "AI news" } }
tool_result

The result returned from a tool execution.

{ "toolCallId": "call_abc123", "result": { "results": [...] } }
complete

Signals the response is complete with token usage.

{ "conversationId": "conv-123", "inputTokens": 150, "outputTokens": 300 }
error

An error occurred during processing.

{ "message": "Failed to execute tool" }

All Endpoints

Complete reference of all agent-related API endpoints.

POST
/api/[username]/agents/[uid]/conversation/[conversationId]

Send a message and stream the AI response via SSE. Requires TPMJS API key.

GET
/api/[username]/agents/[uid]/conversation/[conversationId]

Get the full conversation history with all messages. Requires TPMJS API key.

GET
/api/[username]/agents/[uid]/conversations

List all conversations for an agent. Requires TPMJS API key.

GET
/api/agents

List all your agents.

POST
/api/agents

Create a new agent.

GET
/api/agents/[id]

Get agent details by ID.

PATCH
/api/agents/[id]

Update an agent's configuration.

DELETE
/api/agents/[id]

Delete an agent and all its conversations.

Ready to Build?

Create your first AI agent and start building custom assistants.