API Agents and Agent Tools

Reference for the current agent-related endpoints in SolutionEngine, including agent CRUD, provider/model discovery, edge sync, and built-in tool registry APIs.

The current backend splits agent functionality across three areas:

agent CRUD and provider/model discovery
edge agent synchronization
built-in tool registry and installation

Some tool endpoints still use /api/mcp/... in the path. In the current product docs, these are better understood as agent tool endpoints.

Agent CRUD And Model Discovery

These endpoints back the current project agent UI.

GET /api/agents/llm/providers
GET /api/agents/llm/providers/:provider_id/models
GET /api/agents
GET /api/agents/:agent_id
POST /api/agents
PUT /api/agents/:agent_id
DELETE /api/agents/:agent_id

Current create and update payloads include fields such as:

name
description
project_id
provider
model
apiKey
baseUrl
system_prompt
max_steps
toolsets

Notes:

Ollama currently requires a baseUrl
toolset configs are validated against the registered tool schema before save

Edge Agent Sync Endpoints

These endpoints are used by the runtime agent that syncs workflows and environment state.

GET /api/agent/sync/:device_id
POST /api/agent/sync/:device_id/status

The sync response can include:

assigned workflows
datasources
pending commands
referenced connections
referenced agents
environment attributes and secrets

This is runtime synchronization for environments, not the same thing as the user-facing AI agent CRUD endpoints.

Agent Tool Registry Endpoints

These endpoints expose the current built-in capability registry and installed tool instances.

GET /api/mcp/registry
GET /api/mcp/builtin
GET /api/mcp/server/:server_id
POST /api/mcp/validate/:server_id
GET /api/mcp/installed
POST /api/mcp/install/:template_name
DELETE /api/mcp/installed/:instance_id

Even though the path uses mcp, these endpoints currently serve the built-in agent tools system used by the app.

Example: Create An Agent

POST /api/agents
Content-Type: application/json

{
  "name": "Ops Assistant",
  "description": "Checks APIs and summarizes status",
  "project_id": "prj_1707456789",
  "provider": "ollama",
  "model": "llama3.1:8b",
  "baseUrl": "http://localhost:11434",
  "system_prompt": "Check services and summarize issues briefly.",
  "max_steps": 20,
  "toolsets": [
    {
      "server": "builtin-http-server",
      "config": {
        "timeout": 30
      }
    }
  ]
}

Example: List Built-In Agent Tools

GET /api/mcp/builtin

Use this to populate the list of built-in tools available for agent attachment.

Common Errors

400 invalid agent payload or invalid tool configuration
401 unauthorized access
404 agent, tool definition, or sync target not found
500 backend error while listing providers, models, or registry data

Operational guidance:

validate tool config before saving an agent
do not assume model discovery works without provider credentials
treat edge sync APIs and user-facing agent CRUD APIs as different surfaces

PreviousAI Agents

NextPreview Node