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:
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
| Parameter | Type | Required | Description |
|---|---|---|---|
| Name | string | Yes | Display name for your agent (max 100 chars) |
| UID | string | No | URL-friendly identifier (auto-generated from name). Used in API calls. |
| Description | string | No | Brief description of what the agent does (max 500 chars) |
Model Configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
| Provider | enum | Yes | AI provider (OpenAI, Anthropic, Google, Groq, Mistral) |
| Model | string | Yes | Specific model ID (e.g., gpt-4o, claude-sonnet-4-20250514) |
| System Prompt | string | No | Instructions that define how the agent behaves (max 10,000 chars) |
| Temperature | number | No | Response randomness (0 = deterministic, 2 = creative). Default: 0.7 |
Execution Limits
| Parameter | Type | Required | Description |
|---|---|---|---|
| Max Tool Calls | number | No | Maximum tool calls per response turn. Prevents runaway loops. Default: 20 |
| Context Messages | number | No | Number 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 toolAdding 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.
Anthropic
Claude models known for nuanced understanding and safety.
Gemini models with multimodal capabilities.
Groq
Ultra-fast inference for open-source models.
Mistral
European AI models with strong multilingual support.
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
| Parameter | Type | Required | Description |
|---|---|---|---|
| message | string | Yes | The user message to send to the agent |
| env | object | No | Additional 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.
chunkStreaming text content from the AI response.
{ "text": "Here is my response..." }tool_callIndicates the agent is calling a tool.
{ "toolCallId": "call_abc123", "toolName": "webSearch", "input": { "query": "AI news" } }tool_resultThe result returned from a tool execution.
{ "toolCallId": "call_abc123", "result": { "results": [...] } }completeSignals the response is complete with token usage.
{ "conversationId": "conv-123", "inputTokens": 150, "outputTokens": 300 }errorAn error occurred during processing.
{ "message": "Failed to execute tool" }All Endpoints
Complete reference of all agent-related API endpoints.
/api/[username]/agents/[uid]/conversation/[conversationId]Send a message and stream the AI response via SSE. Requires TPMJS API key.
/api/[username]/agents/[uid]/conversation/[conversationId]Get the full conversation history with all messages. Requires TPMJS API key.
/api/[username]/agents/[uid]/conversationsList all conversations for an agent. Requires TPMJS API key.
/api/agentsList all your agents.
/api/agentsCreate a new agent.
/api/agents/[id]Get agent details by ID.
/api/agents/[id]Update an agent's configuration.
/api/agents/[id]Delete an agent and all its conversations.
Ready to Build?
Create your first AI agent and start building custom assistants.