Agent Setup Guide

Complete walkthrough for creating a functional AI agent from scratch. By the end of this guide, you'll have an agent configured with tools, traits, and team membership, ready to process conversations.

Prerequisites

API Access: JWT token or API key
Account ID: Your account identifier
Base URL: API endpoint (e.g., https://api.gnosari.com or http://localhost:8001)

Step 1: Create an Agent

Start with a basic agent configuration:

bash

curl -X POST "https://api.gnosari.com/api/v1/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Bot",
    "identifier": "support-bot",
    "description": "Handles customer inquiries and provides product information",
    "instructions": "You are a helpful customer support agent. Be professional, empathetic, and solution-oriented. If you cannot answer a question, escalate to a human agent.",
    "model": "gpt-4o-mini",
    "temperature": 0.7,
    "response_format": {
      "type": "text"
    }
  }'

Response:

json

{
  "id": 42,
  "identifier": "support-bot",
  "name": "Customer Support Bot",
  "description": "Handles customer inquiries and provides product information",
  "instructions": "You are a helpful customer support agent...",
  "model": "gpt-4o-mini",
  "temperature": 0.7,
  "created_at": "2025-02-15T10:00:00Z"
}

Key fields:

identifier: URL-safe slug for accessing the agent (e.g., joina.chat/support-bot)
instructions: System prompt defining the agent's behavior
model: LLM model (gpt-4o, gpt-4o-mini, claude-3-5-sonnet-20241022, etc.)
temperature: Creativity level (0.0 = deterministic, 1.0 = creative)

Step 2: Add Tools

Tools enable agents to perform actions beyond text generation:

bash

# Add web search capability
curl -X POST "https://api.gnosari.com/api/v1/agents/42/tools/web-search" \
  -H "Authorization: Bearer $TOKEN"

# Add knowledge retrieval
curl -X POST "https://api.gnosari.com/api/v1/agents/42/tools/knowledge-retrieval" \
  -H "Authorization: Bearer $TOKEN"

Response:

json

{
  "id": 42,
  "identifier": "support-bot",
  "tools": [
    {
      "tool_identifier": "web-search",
      "name": "Web Search",
      "description": "Search the web for current information"
    },
    {
      "tool_identifier": "knowledge-retrieval",
      "name": "Knowledge Retrieval",
      "description": "Search knowledge bases for relevant information"
    }
  ]
}

Available tools:

web-search: Search the web
knowledge-retrieval: Search configured knowledge sources
calculator: Perform mathematical calculations
code-interpreter: Execute Python code

See: Tools API Reference

Step 3: Add Traits

Traits define personality characteristics and behavioral constraints:

bash

# Add empathy trait
curl -X POST "https://api.gnosari.com/api/v1/agents/42/traits/empathetic" \
  -H "Authorization: Bearer $TOKEN"

# Add conciseness trait
curl -X POST "https://api.gnosari.com/api/v1/agents/42/traits/concise" \
  -H "Authorization: Bearer $TOKEN"

Response:

json

{
  "id": 42,
  "identifier": "support-bot",
  "traits": [
    {
      "trait_identifier": "empathetic",
      "name": "Empathetic",
      "description": "Shows understanding and emotional awareness"
    },
    {
      "trait_identifier": "concise",
      "name": "Concise",
      "description": "Brief, to-the-point responses"
    }
  ]
}

Available traits:

empathetic: Emotionally aware responses
concise: Brief, direct answers
professional: Formal, business-appropriate tone
friendly: Casual, approachable tone
technical: Uses technical terminology
creative: Generates novel ideas

See: Traits API Reference

Step 4: Create a Team

Agents must belong to a team to process conversations:

bash

curl -X POST "https://api.gnosari.com/api/v1/teams" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Team",
    "identifier": "support-team",
    "description": "Team for handling customer inquiries",
    "agent_ids": [42]
  }'

Response:

json

{
  "id": 10,
  "identifier": "support-team",
  "name": "Customer Support Team",
  "description": "Team for handling customer inquiries",
  "agents": [
    {
      "id": 42,
      "identifier": "support-bot",
      "name": "Customer Support Bot"
    }
  ],
  "created_at": "2025-02-15T10:05:00Z"
}

Team features:

Multi-agent teams: Add multiple agents for complex workflows
Shared resources: Tools, traits, and knowledge shared across team
Orchestration: Agents can delegate to teammates

See: Teams API Reference

Step 5: Test via WebSocket Chat

Connect to the agent via WebSocket for real-time conversations:

javascript

const ws = new WebSocket(
  'wss://api.gnosari.com/ws/chat/support-bot?token=' + TOKEN
);

ws.onopen = () => {
  // Send a message
  ws.send(JSON.stringify({
    message: "What's your return policy?"
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
};

Event types received:

json

{"event_type": "agent_started", "agent_id": 42, "agent_name": "Customer Support Bot"}
{"event_type": "token", "content": "Our"}
{"event_type": "token", "content": " return"}
{"event_type": "token", "content": " policy..."}
{"event_type": "agent_completed", "session_id": "sess_abc123"}

See: WebSocket Chat Guide

Step 6: Verify Configuration

Check the agent's complete configuration:

bash

curl "https://api.gnosari.com/api/v1/agents/42" \
  -H "Authorization: Bearer $TOKEN"

Response:

json

{
  "id": 42,
  "identifier": "support-bot",
  "name": "Customer Support Bot",
  "instructions": "You are a helpful customer support agent...",
  "model": "gpt-4o-mini",
  "temperature": 0.7,
  "tools": [
    {"tool_identifier": "web-search", "name": "Web Search"},
    {"tool_identifier": "knowledge-retrieval", "name": "Knowledge Retrieval"}
  ],
  "traits": [
    {"trait_identifier": "empathetic", "name": "Empathetic"},
    {"trait_identifier": "concise", "name": "Concise"}
  ],
  "teams": [
    {"id": 10, "identifier": "support-team", "name": "Customer Support Team"}
  ],
  "created_at": "2025-02-15T10:00:00Z"
}

Common Patterns

Multi-Agent Teams with Specialization

bash

# Create specialized agents
curl -X POST "$API/agents" -H "Authorization: Bearer $TOKEN" -d '{
  "name": "Billing Specialist",
  "identifier": "billing-agent",
  "instructions": "Expert in billing, payments, and subscriptions",
  "model": "gpt-4o-mini"
}'

curl -X POST "$API/agents" -H "Authorization: Bearer $TOKEN" -d '{
  "name": "Technical Support",
  "identifier": "tech-agent",
  "instructions": "Expert in technical troubleshooting",
  "model": "gpt-4o-mini"
}'

# Add both to team
curl -X POST "$API/teams" -H "Authorization: Bearer $TOKEN" -d '{
  "name": "Support Team",
  "identifier": "support",
  "agent_ids": [42, 43, 44]
}'

Agent with Knowledge Base

bash

# 1. Create agent
curl -X POST "$API/agents" -H "Authorization: Bearer $TOKEN" -d '{
  "name": "Docs Agent",
  "identifier": "docs",
  "model": "gpt-4o-mini"
}'

# 2. Add knowledge retrieval tool
curl -X POST "$API/agents/50/tools/knowledge-retrieval" \
  -H "Authorization: Bearer $TOKEN"

# 3. Create knowledge source (auto-loads)
curl -X POST "$API/knowledge" -H "Authorization: Bearer $TOKEN" -d '{
  "name": "Product Documentation",
  "data_type": "confluence",
  "paths": ["https://docs.example.com"]
}'

# Agent can now search the knowledge base

See: Knowledge Loading Guide

Public vs Private Agents

bash

# Public agent (no authentication required)
curl -X POST "$API/agents" -H "Authorization: Bearer $TOKEN" -d '{
  "name": "Demo Bot",
  "identifier": "demo",
  "access_level": "PUBLIC"
}'

# Password-protected agent
curl -X POST "$API/agents" -H "Authorization: Bearer $TOKEN" -d '{
  "name": "Internal Bot",
  "identifier": "internal",
  "access_level": "PASSWORD_PROTECTED",
  "access_password": "secret123"
}'
# Access: ws://api/ws/chat/internal?password=secret123

# Private agent (requires authentication)
curl -X POST "$API/agents" -H "Authorization: Bearer $TOKEN" -d '{
  "name": "Admin Bot",
  "identifier": "admin",
  "access_level": "PRIVATE"
}'
# Access: ws://api/ws/chat/admin?token=$TOKEN

See: Authentication Reference

Troubleshooting

Agent not responding

Check:

Agent belongs to a team: GET /api/v1/agents/42
Team has at least one agent: GET /api/v1/teams/10
WebSocket authentication is correct
OpenAI/Anthropic API keys are configured (server-side)

Tools not working

Check:

Tool is added to agent: GET /api/v1/agents/42/tools
Tool requires specific configuration (e.g., knowledge sources for knowledge-retrieval)
Server logs for tool execution errors

Rate limiting

Agents inherit rate limits from the underlying LLM provider:

OpenAI: ~10,000 RPM (requests per minute)
Anthropic: ~4,000 RPM

Solution: Implement exponential backoff in client code.

Next Steps

Add data collection: Data Collection Guide
Set up event automation: Event-Driven Automation
Load knowledge sources: Knowledge Loading Guide
Deploy to production: Configuration Reference

Agent Setup Guide ​

Prerequisites ​

Step 1: Create an Agent ​

Step 2: Add Tools ​

Step 3: Add Traits ​

Step 4: Create a Team ​

Step 5: Test via WebSocket Chat ​

Step 6: Verify Configuration ​

Common Patterns ​

Multi-Agent Teams with Specialization ​

Agent with Knowledge Base ​

Public vs Private Agents ​

Troubleshooting ​

Agent not responding ​

Tools not working ​

Rate limiting ​

Next Steps ​

Related References ​

Agent Setup Guide

Prerequisites

Step 1: Create an Agent

Step 2: Add Tools

Step 3: Add Traits

Step 4: Create a Team

Step 5: Test via WebSocket Chat

Step 6: Verify Configuration

Common Patterns

Multi-Agent Teams with Specialization

Agent with Knowledge Base

Public vs Private Agents

Troubleshooting

Agent not responding

Tools not working

Rate limiting

Next Steps

Related References