Skip to main content

Agent API

GeniSpace provides two agent invocation protocols to meet different integration scenarios:

  1. OpenAI Chat Completions Compatible API - Fully compatible with the OpenAI chat completion standard for easy migration
  2. Agent Execution Protocol - GeniSpace custom protocol offering richer parameter configuration and agent-specific features

OpenAI Chat Completions Compatible API​

Endpoint​

POST /v1/agents/{agentId}/chat

Description​

Fully compatible with the OpenAI Chat Completions API specification, allowing developers to interact with GeniSpace agents using existing OpenAI SDKs and code.

Request Parameters​

ParameterTypeRequiredDescription
messagesarray✓Conversation message array, same format as the OpenAI API
modelstring✗Model name (optional; the agent uses its configured default model)
temperaturenumber✗Controls output randomness, range 0-2, default 0.7
max_tokensinteger✗Maximum output tokens, default 2000
top_pnumber✗Nucleus sampling parameter, range 0-1, default 1.0
frequency_penaltynumber✗Frequency penalty, range -2.0 to 2.0, default 0
presence_penaltynumber✗Presence penalty, range -2.0 to 2.0, default 0
streamboolean✗Whether to stream results, default false

Message Format​

{
  "role": "system|user|assistant",
  "content": "Message content"
}

Request Examples​

Non-streaming Request​

curl -X POST "https://api.genispace.cn/v1/agents/agt_123456/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "system",
        "content": "You are a professional data analyst"
      },
      {
        "role": "user", 
        "content": "Please analyze this month'\''s sales data trends"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 1500
  }'

Streaming Request​

curl -X POST "https://api.genispace.cn/v1/agents/agt_123456/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Please help me write a market analysis report"
      }
    ],
    "stream": true
  }'

Response Format​

Non-streaming Response​

{
  "id": "chat_123456789",
  "object": "chat.completion",
  "created": 1710835200,
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Based on your requirements, I will analyze this month's sales data trends..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 256,
    "total_tokens": 298
  }
}

Streaming Response​

data: {"id":"chat_123456789","object":"chat.completion.chunk","created":1710835200,"model":"gpt-4","choices":[{"index":0,"delta":{"role":"assistant","content":"Based"},"finish_reason":null}]}

data: {"id":"chat_123456789","object":"chat.completion.chunk","created":1710835200,"model":"gpt-4","choices":[{"index":0,"delta":{"content":" on your"},"finish_reason":null}]}

data: {"id":"chat_123456789","object":"chat.completion.chunk","created":1710835200,"model":"gpt-4","choices":[{"index":0,"delta":{"content":" requirements"},"finish_reason":null}]}

data: [DONE]

Agent Execution Protocol​

Endpoint​

POST /v1/agents/{agentId}/execute

Description​

GeniSpace's custom agent execution protocol, providing more flexible parameter configuration and agent-specific features such as memory management and context retention.

Request Parameters​

ParameterTypeRequiredDescription
inputsobject✓Agent input parameters, including query content and feature toggles
settingsobject✗Model parameter settings

inputs Parameters​

The inputs object contains the input parameters and feature configuration required by the agent:

FieldTypeRequiredDescription
querystring✓User query content
memoryboolean✗Whether to enable memory, default false
contextboolean✗Whether to enable knowledge base context retrieval, default false
internetboolean✗Whether to enable internet search, default false
{
  "inputs": {
    "query": "User query content",
    "memory": true,
    "context": true,
    "internet": false
  }
}

settings Parameters​

{
  "settings": {
    "temperature": 0.7,
    "maxTokens": 2000,
    "topP": 1.0,
    "presencePenalty": 0,
    "frequencyPenalty": 0,
    "model": "gpt-4"  // Override the agent's default model
  }
}

Request Examples​

Basic Query​

curl -X POST "https://api.genispace.cn/v1/agents/agt_123456/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "query": "Hello",
      "memory": true,
      "context": false,
      "internet": false
    },
    "settings": {
      "temperature": 0.7,
      "maxTokens": 2000
    }
  }'

Enable All Features​

curl -X POST "https://api.genispace.cn/v1/agents/agt_123456/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "query": "Help me analyze customer satisfaction data",
      "memory": true,
      "context": true,
      "internet": true
    },
    "settings": {
      "temperature": 0.3,
      "maxTokens": 1500
    }
  }'

Response Format​

Success Response​

{
  "answer": "Hello! I'm happy to help. Could you please specify what area you'd like to consult about? For example, is it about developing your child's learning habits, improving social skills, or other educational topics? This way I can provide a more accurate and comprehensive plan including theoretical basis, implementation steps, and expected outcomes.",
  "agent_id": "1299af56-ca52-4498-a0fd-b3da8ad77daf",
  "execution_time": 6.454147815704346,
  "token_usage": {
    "prompt_tokens": 168,
    "completion_tokens": 85,
    "total_tokens": 253
  }
}

Response Field Descriptions​

FieldTypeDescription
answerstringThe response content generated by the agent
agent_idstringID of the executed agent
execution_timenumberExecution time (seconds)
token_usageobjectToken usage statistics
token_usage.prompt_tokensintegerInput token count
token_usage.completion_tokensintegerOutput token count
token_usage.total_tokensintegerTotal token count

Error Handling​

Both APIs follow the same error handling format:

{
  "error": {
    "code": "agent_not_found",
    "message": "The specified agent does not exist",
    "details": {
      "agent_id": "agt_123456"
    }
  }
}

Common Error Codes​

Error CodeDescription
agent_not_foundAgent does not exist
agent_inactiveAgent is deactivated
invalid_inputInvalid input parameters
quota_exceededQuota limit exceeded
model_unavailableSpecified model is unavailable
context_too_longContext length exceeds the limit

Best Practices​

Choosing the Right Protocol​

  • Use the Chat Completions API when:

    • You need to quickly migrate existing OpenAI code
    • Building a simple chatbot
    • You don't need advanced agent features (memory, knowledge base, web search)
    • You need full compatibility with OpenAI SDKs

  • Use the Agent Execution Protocol when:

    • You need to leverage the agent's memory feature
    • You need to integrate knowledge bases for context retrieval
    • You need web search capabilities
    • You need detailed execution statistics (execution time, token usage, etc.)
    • Building enterprise-grade intelligent applications

Performance Optimization​

  • Selectively enable features based on requirements: memory, context, internet
  • Set maxTokens appropriately to control response length and cost
  • Adjust the temperature parameter based on task complexity
  • Regularly clean up unnecessary memory data to improve retrieval efficiency

Security Considerations​

  • Always validate user input to prevent injection attacks
  • Limit agent permission scope in production environments
  • Regularly review agent execution logs
  • Apply appropriate data masking for sensitive data

SDK Support​

JavaScript SDK​

The official GeniSpace JavaScript SDK supports agent chat and execution. See Developer Resources for details.

import GeniSpace from 'genispace';

const client = new GeniSpace({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.genispace.cn'
});

// OpenAI-compatible Chat API
const chatResponse = await client.agents.chat('agt_123456', {
  messages: [{ role: 'user', content: 'Analyze sales data' }],
  temperature: 0.7
});

// Agent Execution Protocol
const execResponse = await client.agents.execute('agt_123456', {
  inputs: {
    query: 'Analyze sales data',
    memory: true,
    context: true,
    internet: false
  },
  settings: {
    temperature: 0.7,
    maxTokens: 2000
  }
});