Ask AI
All Categories
Building with Sapience
System Agents & On-the-Fly Agents for Builders

System Agents & On-the-Fly Agents for Builders

Sapience has utility Agents you can use, or you can create your own on-the-fly for use in n8n, Make etc.

Last updated on January 30, 2026

Invoking System Agents from Automations

Last Updated: 2026.01.30

Overview

Sapience provides a System Agents API that lets you execute pre-built or custom AI agents via simple HTTP calls. This is perfect for automation platforms like n8n, Make.com, Zapier, and Power Automate.

Two ways to use the API:

Endpoint
Use Case
/execute
Run a pre-configured agent from the database (e.g., translation, summarization)
/execute-custom
Define your own agent on-the-fly with custom instructions

Base URL: https://your-sapience-instance/api/v2/system-agents

Authentication

Who can call these endpoints? Any authenticated user with a valid JWT token.

There are no special permissions required beyond having a valid Sapience account. If you can log in, you can use system agents.

Getting a JWT Token

Before calling the System Agents API, you need a JWT token. Get one by authenticating:

POST https://your-sapience-instance/api/user/authenticateUser
Content-Type: application/json

{
  "username": "your@email.com",
  "password": "your-password"
}

Response:

{
  "success": true,
  "data": {
    "jwt_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Use this token in all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiry: Tokens expire after 24 hours. Refresh before expiry or catch 401 errors and re-authenticate.

Available System Agents

These pre-configured agents are ready to use. Just reference them by agent_uid:

Agent UID
Name
Model
What It Does
sys-agent-task-breakdown
Task Breakdown Agent
gpt-4.1
Converts natural language into structured task objects with priority, status, and metadata
sys-agent-translate
Translation Agent
gpt-4o
Professional translation for 100+ languages with cultural nuance preservation
sys-agent-summarize
Summarization Agent
gpt-4o
Creates concise summaries in bullet, paragraph, or executive summary format
sys-agent-extract-entities
Entity Extraction Agent
gpt-4.1
Extracts people, organizations, locations, dates, and other named entities from text
sys-agent-build-agent
Agent Builder Assistant
gpt-5.1
Generates agent configurations (instructions + descriptions) from natural language

Using Pre-Configured Agents (/execute)

Use this endpoint when you want to run one of the built-in system agents.

Endpoint

POST /api/v2/system-agents/execute

Request Format

{
  "agent_uid": "sys-agent-translate",
  "user_query": "Translate this to French: Hello, how are you today?",
  "output_type": null,
  "context": {}
}
Field
Required
Description
agent_uid
Yes
The system agent identifier (see table above)
user_query
Yes
Your prompt/question for the agent
output_type
No
"task", "project", "goal", "generic", or null for plain text
context
No
Variables to inject into the agent's instructions (see Context Injection below)

Complete n8n/Make.com Example

HTTP Request Node Configuration:

Method: POST
URL: https://your-sapience-instance/api/v2/system-agents/execute
Headers:
  Authorization: Bearer {{your_jwt_token}}
  Content-Type: application/json

Body (JSON):
{
  "agent_uid": "sys-agent-summarize",
  "user_query": "Summarize this article: {{article_text}}"
}

Response:

{
  "success": true,
  "message": "Successfully executed system agent: sys-agent-summarize",
  "status_code": 200,
  "data": "## Key Points\n\n- First main takeaway from the article\n- Second important finding\n- Third critical insight\n- Conclusion and next steps"
}

Agent-by-Agent Examples

Task Breakdown Agent

Use case: Convert a project description into actionable tasks.

{
  "agent_uid": "sys-agent-task-breakdown",
  "user_query": "Plan a product launch: create landing page, write press release, schedule social media posts, prepare demo video",
  "output_type": "task",
  "context": {
    "username": "automation-user",
    "user_id": 123
  }
}

Response:

{
  "success": true,
  "data": [
    {
      "uid": "task-a1b2c3",
      "display_name": "Create landing page",
      "status": "todo",
      "priority": "high",
      "metadata_type": "task",
      "creator_username": "automation-user",
      "user_id": 123
    },
    {
      "uid": "task-d4e5f6",
      "display_name": "Write press release",
      "status": "todo",
      "priority": "high",
      "metadata_type": "task",
      "creator_username": "automation-user",
      "user_id": 123
    }
    // ... more tasks
  ]
}

Translation Agent

Use case: Translate customer messages for a multilingual support system.

{
  "agent_uid": "sys-agent-translate",
  "user_query": "Translate to Spanish: Thank you for your order. Your package will arrive within 3-5 business days."
}

Response:

{
  "success": true,
  "data": "Gracias por su pedido. Su paquete llegará en 3-5 días hábiles."
}

Summarization Agent

Use case: Summarize long documents or meeting transcripts.

{
  "agent_uid": "sys-agent-summarize",
  "user_query": "Create an executive summary of this report:\n\n{{long_document_text}}"
}

Entity Extraction Agent

Use case: Extract contacts and companies from emails or documents.

{
  "agent_uid": "sys-agent-extract-entities",
  "user_query": "Extract all entities from: John Smith from Acme Corporation called about the $50,000 contract. Meeting scheduled for March 15, 2026 in New York."
}

Response:

{
  "success": true,
  "data": "PERSON: John Smith (high confidence)\nORGANIZATION: Acme Corporation (high confidence)\nMONEY: $50,000 (high confidence)\nDATE: March 15, 2026 (high confidence)\nLOCATION: New York (high confidence)"
}

Agent Builder Assistant

Use case: Generate agent configurations from descriptions (for developers building new agents).

{
  "agent_uid": "sys-agent-build-agent",
  "user_query": "Create an agent that helps HR teams write job descriptions. It should be professional but friendly, and always include required qualifications and benefits sections.",
  "output_type": "agent_instructions"
}

Creating Custom On-the-Fly Agents (/execute-custom)

This is the most powerful feature for automation builders. Define any agent behavior without pre-registering it in the database.

Endpoint

POST /api/v2/system-agents/execute-custom

Request Format

{
  "model": "gpt-4o",
  "system_instructions": "You are a customer sentiment analyzer...",
  "user_query": "Analyze this review: ...",
  "temperature": 0.3,
  "output_type": null,
  "context": {}
}
Field
Required
Description
model
Yes
OpenAI model: gpt-4o, gpt-4.1, o3-mini, gpt-5.2
system_instructions
Yes
Complete system prompt for the agent
user_query
Yes
The user's input/question
temperature
No
0.0-2.0 (ignored for reasoning models like o3)
output_type
No
For structured output: "task", "project", "goal", "generic"
context
No
Variables to inject into instructions (replaces {variable} placeholders)

Example 1: Sentiment Analyzer

Create a custom sentiment analysis agent:

{
  "model": "gpt-4o",
  "system_instructions": "You are a sentiment analyzer. For each input, respond with exactly one word: POSITIVE, NEGATIVE, or NEUTRAL. Do not explain, just classify.",
  "user_query": "The product arrived late but the quality was excellent and support was very helpful.",
  "temperature": 0.1
}

Response:

{
  "success": true,
  "data": "POSITIVE"
}

Example 2: JSON Formatter

Create an agent that outputs structured JSON:

{
  "model": "gpt-4.1",
  "system_instructions": "You are a data extraction assistant. Extract contact information from the text and return ONLY valid JSON in this format: {\"name\": \"...\", \"email\": \"...\", \"phone\": \"...\", \"company\": \"...\"}. Use null for missing fields.",
  "user_query": "Hi, I'm Sarah Chen from TechCorp. You can reach me at sarah.chen@techcorp.com or 555-0123.",
  "temperature": 0
}

Response:

{
  "success": true,
  "data": "{\"name\": \"Sarah Chen\", \"email\": \"sarah.chen@techcorp.com\", \"phone\": \"555-0123\", \"company\": \"TechCorp\"}"
}

Example 3: Using Context Injection

Personalize responses with context variables:

{
  "model": "gpt-4o",
  "system_instructions": "You are a customer service agent for {company_name}. Always greet the customer by name ({customer_name}) and mention their membership level ({membership_level}). Be helpful and professional.",
  "user_query": "I need to return an item I bought last week.",
  "context": {
    "company_name": "SuperStore",
    "customer_name": "Maria",
    "membership_level": "Gold"
  }
}

Result: The {company_name}, {customer_name}, and {membership_level} placeholders are replaced before the agent runs. The agent sees:

"You are a customer service agent for SuperStore. Always greet the customer by name (Maria) and mention their membership level (Gold)..."

Context Injection Deep Dive

Context injection lets you personalize agent behavior without changing the base instructions. Use {variable_name} placeholders in your system_instructions, then pass values via the context object.

How It Works

  1. You include placeholders like {username} or {project_name} in system_instructions
  1. You pass actual values in the context object
  1. Before execution, all placeholders are replaced with their values

Automatic Context Values

These values are automatically added to context (you don't need to pass them):

Variable
Description
{user_id}
The authenticated user's numeric ID
{username}
The authenticated user's username/email
{org_id}
The user's organization ID

Best Practice: Template Agents

Design reusable agent templates with placeholders:

{
  "model": "gpt-4o",
  "system_instructions": "You are a {role} for {department}. Your job is to {primary_task}. Always respond in {language} and maintain a {tone} tone.",
  "user_query": "Help me draft an announcement about the new policy.",
  "context": {
    "role": "communications specialist",
    "department": "Human Resources",
    "primary_task": "help draft internal communications",
    "language": "English",
    "tone": "professional but approachable"
  }
}

Output Types

When you need structured data instead of plain text, use the output_type parameter:

output_type
Returns
Use Case
null (default)
Plain text string
General responses, summaries, translations
"task"
List of task objects
Breaking down work into actionable items
"project"
List of project objects
Creating project structures
"goal"
List of goal objects
Defining objectives
"generic"
List of generic objects
Flexible structured data
"agent_instructions"
Agent configuration
Building new agents
"document_translation"
Translation with metadata
Translations with source/target language info

Error Handling

Common Error Responses

401 - Unauthorized:

{
  "success": false,
  "message": "Authentication required",
  "status_code": 401
}

Solution: Check your JWT token is valid and not expired.

404 - Agent Not Found:

{
  "success": false,
  "message": "Agent 'sys-agent-nonexistent' not found in database",
  "status_code": 404
}

Solution: Check the agent_uid spelling. Use /list to see available agents.

500 - Internal Error:

{
  "success": false,
  "message": "Internal server error in services:API_system_agents:execute_custom_agent(). Please report this to your administrator.",
  "status_code": 500
}

Solution: Check your request format. If the issue persists, contact support.

Best Practices for Automations

  1. Always check success field - Don't assume the request worked
  1. Handle 401 errors - Re-authenticate and retry
  1. Set reasonable timeouts - Agent calls may take 5-30 seconds
  1. Log the full response - For debugging failed workflows

Listing Available Agents

To discover what system agents are available:

GET /api/v2/system-agents/list
Authorization: Bearer {{your_jwt_token}}

Response:

{
  "success": true,
  "data": [
    {
      "uid": "sys-agent-task-breakdown",
      "display_name": "Task Breakdown Agent",
      "description": "Converts natural language queries into structured SOTask objects",
      "model": "gpt-4.1"
    },
    {
      "uid": "sys-agent-translate",
      "display_name": "Translation Agent",
      "description": "Professional multilingual translator supporting 100+ languages",
      "model": "gpt-4o"
    }
    // ... more agents
  ]
}

Complete n8n Workflow Example

Here's a complete workflow that processes incoming support tickets:

Node 1: Webhook Trigger

Receives incoming support ticket

Node 2: Authenticate (HTTP Request)

Method: POST
URL: https://sapience.example.com/api/user/authenticateUser
Body: {"username": "automation@company.com", "password": "{{$env.SAPIENCE_PASSWORD}}"}

Node 3: Analyze Sentiment (HTTP Request)

Method: POST
URL: https://sapience.example.com/api/v2/system-agents/execute-custom
Headers:
  Authorization: Bearer {{$node["Authenticate"].json.data.jwt_token}}
Body:
{
  "model": "gpt-4o",
  "system_instructions": "Classify support ticket urgency as: CRITICAL, HIGH, MEDIUM, or LOW. Consider customer tone, issue severity, and business impact. Respond with ONLY the classification word.",
  "user_query": "{{$node["Webhook"].json.ticket_text}}",
  "temperature": 0.1
}

Node 4: Create Tasks (HTTP Request)

Method: POST
URL: https://sapience.example.com/api/v2/system-agents/execute
Headers:
  Authorization: Bearer {{$node["Authenticate"].json.data.jwt_token}}
Body:
{
  "agent_uid": "sys-agent-task-breakdown",
  "user_query": "Create tasks to resolve this support issue: {{$node["Webhook"].json.ticket_text}}",
  "output_type": "task",
  "context": {
    "priority": "{{$node["Analyze Sentiment"].json.data}}"
  }
}

Node 5: Route Based on Urgency

IF node that routes CRITICAL tickets differently

Make.com Scenario Example

Module 1: Webhook

Catch hook receives data

Module 2: HTTP - Get JWT

URL: https://sapience.example.com/api/user/authenticateUser
Method: POST
Body type: JSON
Request content:
{
  "username": "automation@company.com",
  "password": "your-password"
}

Module 3: HTTP - Execute Agent

URL: https://sapience.example.com/api/v2/system-agents/execute-custom
Method: POST
Headers:
  Authorization: Bearer {{2.data.jwt_token}}
  Content-Type: application/json
Request content:
{
  "model": "gpt-4o",
  "system_instructions": "You are a helpful assistant...",
  "user_query": "{{1.message}}"
}

Module 4: Parse JSON

Parse the data field from the response

Tips for Automation Builders

1. Cache Your JWT Token

Don't authenticate on every request. Store the token and refresh only when you get a 401 error.

2. Use Low Temperature for Consistency

For classification, extraction, or formatting tasks, use temperature: 0 or 0.1 for consistent results.

3. Be Explicit in Instructions

The more specific your system_instructions, the more reliable the output:

  • Bad: "Summarize this"
  • Good: "Create a 3-bullet summary. Each bullet should be one sentence. Focus on action items."

4. Test with Simple Queries First

Before building complex workflows, test the endpoint manually with a tool like Postman or curl.

5. Handle Long-Running Requests

Some agent calls (especially with large inputs) may take 10-30 seconds. Set your HTTP timeout accordingly.

Quick Reference: cURL Examples

Execute pre-configured agent:

curl -X POST https://sapience.example.com/api/v2/system-agents/execute \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_uid": "sys-agent-translate",
    "user_query": "Translate to German: Good morning!"
  }'

Execute custom on-the-fly agent:

curl -X POST https://sapience.example.com/api/v2/system-agents/execute-custom \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "system_instructions": "You are a haiku poet. Respond only in haiku format (5-7-5 syllables).",
    "user_query": "Write about automation",
    "temperature": 0.9
  }'

List available agents:

curl -X GET https://sapience.example.com/api/v2/system-agents/list \
  -H "Authorization: Bearer YOUR_JWT"

Summary

The System Agents API gives automation builders two powerful options:

  1. Pre-configured agents (/execute) - Use battle-tested agents for common tasks like translation, summarization, and task breakdown
  1. Custom agents (/execute-custom) - Define any agent behavior on-the-fly with your own model selection, instructions, and context

Both require only a valid JWT token - no special permissions needed. Start with the pre-configured agents to get familiar with the API, then graduate to custom agents for specialized workflows.

 
Did this answer your question?
😞
😐
🤩
HTTP POST Tool for Web Hooks Coming Soon!