Agents Overview

Agents are AI-powered assistants configured with personas, tools, workflows, and security policies. They execute autonomously using the Agent Loop V4 (LangGraph).

Agent Types

Type	Description
assistant	General-purpose conversational agent
chatbot	Lightweight chat agent
workflow	Step-driven workflow agent
classifier	Intent classification agent

Agent Lifecycle

draft → published → archived
  ↑        │           │
  │        ▼           │
  │   📸 snapshot      │
  └────── restore ─────┘

Status	Behavior
draft	Can be executed (with warning in logs) — for builders testing
published	Normal execution. Creates an automatic version snapshot (see Versioning). All schemas are validated before publishing — invalid schemas block publication
archived	Execution blocked — returns error

Version Tracking

Every change to agents, schemas, triggers, and MCP servers is automatically versioned via PostgreSQL triggers. Publishing creates a full snapshot that can be used for rollback. See Versioning for details.

Authentication

Agent management endpoints support hybrid authentication:

Method	Access Level
JWT (Authorization: Bearer <jwt> + x-tenant-id)	Full access (read + write)
API Key (X-Api-Key: YOUR_API_KEY)	Read-only (GET operations only)

---

CRUD Endpoints

GET /api/agents

List all agents for the tenant.

Query Parameters:

Param	Type	Description
status	string	draft, published, archived
type	string	Agent type filter
includeArchived	boolean	Include archived agents
includeTelemetry	boolean	Include telemetry data (total_interactions, avg_response_time)
includeSchemasSummary	boolean	Include schemas summary (schemas_count, schema_types)

Parameter Convention

Parameters accept both camelCase and snake_case: includeTelemetry or include_telemetry.

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "sales-agent",
      "commercial_name": "Sales Assistant",
      "bio": "AI-powered sales assistant",
      "type": "assistant",
      "status": "published",
      "llm_config": {
        "model": "auto",
        "temperature": 0.7
      },
      "created_at": "2025-12-01T00:00:00.000Z"
    }
  ],
  "count": 5
}

---

GET /api/agents/:id

Get agent details by ID.

POST /api/agents

Create a new agent.

Request Body:

{
  "name": "my-agent",
  "commercial_name": "My AI Agent",
  "bio": "Description of the agent",
  "type": "assistant",
  "llm_config": {
    "model": "auto",
    "temperature": 0.7
  },
  "tags": ["tag1", "tag2"],
  "visibility": "tenant"
}

PATCH /api/agents/:id

Update an existing agent (partial fields).

DELETE /api/agents/:id

Archive an agent (soft delete).

---

Status Management

POST /api/agents/:id/publish

Publish an agent, making it available for execution. Automatically creates a version snapshot capturing the complete agent state (persona, schemas, triggers, MCP servers) for future rollback.

Schema Validation on Publish

Publishing validates all agent schemas before proceeding. If any schema is invalid (e.g., missing required fields, bad connection_id, unknown secret_ref), publishing is blocked and the response includes details of the invalid schemas. Fix the reported errors and retry.

POST /api/agents/:id/unpublish

Unpublish an agent (JWT only).

PATCH /api/agents/:id/status

Change agent status with unified method.

Request Body:

{
  "status": "draft | published | archived",
  "config": {}
}

POST /api/agents/:id/restore

Restore an archived agent to draft status.

---

GET /api/agents/:id/full

Get agent with all schemas, linked CSPs, triggers, and telemetry.

Response:

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "sales-agent",
    "status": "published",
    "llm_config": { "model": "auto", "temperature": 0.7 },
    "schemas": [
      {
        "id": "schema-uuid",
        "schema_type": "persona_config",
        "schema_data": {},
        "is_active": true
      }
    ],
    "schemas_count": 5,
    "active_schemas_count": 4,
    "schema_types": ["persona_config", "tools", "csp_config"],
    "linked_csps": [],
    "triggers": [],
    "total_interactions": 150,
    "avg_response_time": 1234.5
  }
}

---

Schema Types

Schemas define the agent's configuration and are stored in builder_agent_schemas.schema_data.

Type	Purpose
persona_config	Agent identity, role, tone, language, constraints
api_config	HTTP tool definitions (external APIs)
db_config	Database query tool definitions
workflow_config	Step-driven execution workflows
policy	Behavior rules and restrictions
knowledge	Knowledge base content

Schema CRUD

Endpoint	Method	Auth
GET /api/agents/:id/schemas	List schemas	JWT or API Key
GET /api/agents/:agentId/schemas/:schemaId	Get schema	JWT or API Key
POST /api/agents/:id/schemas	Create schema	JWT only
PATCH /api/agents/:agentId/schemas/:schemaId	Update schema	JWT only
DELETE /api/agents/:agentId/schemas/:schemaId	Deactivate schema	JWT only

---

Persona Config

The persona defines the agent's identity and behavior. Path: schema_data.editor_schema.persona

Key Fields:

Field	Required	Description
role	Yes	Agent role (heading in system prompt)
objective	Yes	Agent objective
tone	No	Communication tone (default: "professional")
language	No	Language (default: "pt-BR")
expertise	No	Areas of expertise
constraints	No	Mandatory rules
response_style	No	Format, rules, max_response_length
custom_guidelines	No	Free-form key/value guidelines

Example:

{
  "editor_schema": {
    "persona": {
      "role": "Sales Assistant",
      "objective": "Help buyers request quotes for agricultural supplies.",
      "tone": "professional",
      "language": "pt-BR",
      "expertise": ["Agricultural products"],
      "constraints": ["Never invent products", "Always query the database first"],
      "response_style": {
        "format": "markdown",
        "rules": ["Use lists when there are more than 2 items"],
        "max_response_length": 2000
      }
    }
  }
}

Template Variables

The system prompt supports dynamic template variables that are interpolated at runtime:

Variable	Description	Example Output
{{current_date}}	Today's date (pt-BR)	02/03/2026
{{current_time}}	Current time (pt-BR)	14:30:00
{{current_weekday}}	Day of the week (pt-BR)	segunda-feira
{{agent_name}}	Agent's name	Sales Assistant

Unrecognized variables (e.g., {{custom_var}}) are kept intact in the output.

Example usage in persona objective:

"objective": "Help users with purchases. Today is {{current_date}} ({{current_weekday}})."

---

Schema Validation

All schemas are validated on creation and update. Invalid schemas are rejected with detailed error messages.

Validation Rules by Type

Schema Type	Validated Fields
persona_config	role (min 3 chars), objective (min 10 chars), tone (warning), language (warning)
api_config	tool_definition (name, description, input_schema), editor_schema.api (base_url, endpoints, auth)
db_config	connection_id (exists, active), tool_definition, query_template, parameter_mapping
knowledge	Basic structure check
workflow_config	Basic structure check
policy	Basic structure check

Validation Response

When a schema fails validation, the response includes detailed error and warning information:

{
  "success": false,
  "error": "Invalid schema",
  "validation": {
    "errors": ["persona.role is required (minimum 3 characters)"],
    "warnings": ["persona.tone not defined"]
  }
}

Dry-run Validation

Use the MCP tool validate_schema_data to validate a schema without saving it. This is useful for testing schema structures before creating or updating.

---

Authentication Summary

Endpoint	Method	JWT	API Key
/api/agents	GET	Yes	Yes
/api/agents/:id	GET	Yes	Yes
/api/agents/:id/full	GET	Yes	Yes
/api/agents/:id/schemas	GET	Yes	Yes
/api/agents	POST	Yes	No
/api/agents/:id	PATCH	Yes	No
/api/agents/:id	DELETE	Yes	No
/api/agents/:id/publish	POST	Yes	No
/api/agents/:id/unpublish	POST	Yes	No
/api/agents/:id/status	PATCH	Yes	No
/api/agents/:id/restore	POST	Yes	No
/api/agents/:id/schemas	POST	Yes	No