perform.chat
Agents

Get Agent

Retrieve a specific agent by ID

Endpoint

GET https://api.perform.chat/rest/v1/agents/:id

Request Body

{
  "keyId": "your-key-id",
  "keySecret": "your-key-secret"
}

Path Parameters

ParameterTypeDescription
idstringAgent ID to retrieve

Response

{
  "id": "agent_123",
  "name": "Customer Support Agent",
  "prompt_template": "You are a helpful customer support assistant...",
  "active": true,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Response Fields

FieldTypeDescription
idstringUnique agent identifier
namestringAgent display name
prompt_templatestringAgent's system prompt
activebooleanWhether the agent is active
created_atstringISO 8601 timestamp of creation
updated_atstringISO 8601 timestamp of last update

Example Request

const axios = require('axios')

async function getAgent(agentId) {
  const response = await axios.get(
    `https://api.performchat.com/rest/v1/v1/agents/${agentId}`,
    {
      data: {
        keyId: process.env.API_KEY_ID,
        keySecret: process.env.API_KEY_SECRET
      }
    }
  )
  return response.data
}

// Usage
const agent = await getAgent('agent_123')
console.log(`Agent: ${agent.name}`)
console.log(`Active: ${agent.active}`)

Error Responses

StatusDescription
404Agent not found or doesn't belong to company
401Invalid API credentials
400Invalid agent ID format
500Internal server error

Use Cases

Display Agent Information

async function displayAgentInfo(agentId) {
  const agent = await getAgent(agentId)

  return {
    name: agent.name,
    isAvailable: agent.active,
    lastUpdated: new Date(agent.updated_at).toLocaleDateString()
  }
}

Verify Agent Exists

async function verifyAgent(agentId) {
  try {
    const agent = await getAgent(agentId)
    return agent.active
  } catch (error) {
    if (error.response?.status === 404) {
      return false
    }
    throw error
  }
}

Get Agent Details for Token Generation

async function generateTokenWithAgent(userId, agentId) {
  // Verify agent exists and is active
  const agent = await getAgent(agentId)

  if (!agent.active) {
    throw new Error(`Agent ${agent.name} is not active`)
  }

  // Generate token
  return await generateToken(userId, agentId)
}

Compare Agents

async function compareAgents(agentId1, agentId2) {
  const [agent1, agent2] = await Promise.all([
    getAgent(agentId1),
    getAgent(agentId2)
  ])

  return {
    agent1: {
      name: agent1.name,
      active: agent1.active,
      promptLength: agent1.prompt_template.length
    },
    agent2: {
      name: agent2.name,
      active: agent2.active,
      promptLength: agent2.prompt_template.length
    }
  }
}

Best Practices

  1. Verify agent status - Check active: true before using the agent
  2. Cache agent details - Agent data rarely changes
  3. Handle 404 errors - Agent may not exist or may not belong to your company
  4. Use list endpoint for discovery - Use /rest/v1/agents to find available agents

Security Notes

  • You can only access agents that belong to your company
  • The prompt_template field is only included when retrieving a specific agent
  • API credentials must match the company that owns the agent