Agents

Standalone Agents via API key — an orchestration layer that composes Intents/Workflows/Tools/Knowledge as capabilities. This is the same resource as the dashboard's Agent Runtime page and the same underlying service — creating or deploying an agent here shows up in the dashboard immediately, and vice versa.

List agents

GET https://api.liyaengine.ai/v1/agents
Authorization: Bearer liya_xxxxxxxxxxxx

Returns the flat catalog of this tenant's active agents, each with its callable endpoint — not the full agent config. Use GET /v1/agents/{agentKey} for that.

{
  "success": true,
  "data": {
    "agents": [
      {
        "agent": "support-triage",
        "displayName": "Support Triage",
        "description": null,
        "goal": "Triage incoming support tickets",
        "status": "active",
        "endpoint": "/v1/agents/support-triage/run",
        "method": "POST",
        "inputSchema": { "...": "..." }
      }
    ],
    "total": 1
  }
}

Create an agent

POST https://api.liyaengine.ai/v1/agents
Authorization: Bearer liya_xxxxxxxxxxxx
Content-Type: application/json

{
  "agent_key": "support-triage",
  "name": "Support Triage",
  "goal": "Triage incoming support tickets and route them to the right team.",
  "intent_ids": [],
  "workflow_ids": [],
  "knowledge_domain_keys": []
}

agent_key must be lowercase letters, numbers, hyphens, or underscores. Created in draft status — use the deploy endpoint below to activate it for execution. Returns 201 with { "data": { "agent": {...} } }, or 409 AGENT_KEY_TAKEN if the key is already used in this tenant, or 403 FEATURE_NOT_ENABLED if agentic tool-calling isn't enabled on your plan.

tools_config, memory_config, and behavior_config are optional nested objects — see Agent Orchestration for what each controls.

Get an agent

GET https://api.liyaengine.ai/v1/agents/{agentKey}
Authorization: Bearer liya_xxxxxxxxxxxx

Returns the full agent config, including effective_runtime_config — configured values merged with platform defaults, with each field's source (agent | platform_default | provider_default).

Update an agent

PATCH https://api.liyaengine.ai/v1/agents/{agentKey}
Authorization: Bearer liya_xxxxxxxxxxxx
Content-Type: application/json

{
  "name": "Support Triage v2",
  "model": "gpt-4o-mini"
}

All fields optional — only what you pass gets changed. Setting "status": "active" directly is rejected (409 DEPLOY_REQUIRED) — use the deploy endpoint instead.

Deploy an agent

POST https://api.liyaengine.ai/v1/agents/{agentKey}/deploy
Authorization: Bearer liya_xxxxxxxxxxxx

Activates the agent for execution — a deliberate, separately audited transition distinct from an ordinary update, so you can tell routine edits apart from publishing an agent live.

Delete an agent

DELETE https://api.liyaengine.ai/v1/agents/{agentKey}
Authorization: Bearer liya_xxxxxxxxxxxx

Soft delete — sets status to inactive. There's no separate active flag; inactive doubles as both "deleted" and "manually paused."

Run an agent

POST https://api.liyaengine.ai/v1/agents/{agentKey}/run
Authorization: Bearer liya_xxxxxxxxxxxx
Content-Type: application/json

{
  "input": { "message": "My order hasn't arrived yet." }
}

{
  "success": true,
  "data": {
    "run_id": "run_01HZ...",
    "session_id": "ses_01HZ...",
    "status": "completed",
    "output": "I've looked into your order...",
    "steps": 2,
    "total_cost": 0.0043,
    "total_latency_ms": 480
  }
}

Pass session_id to continue a prior conversation with this agent instead of starting a new one. Only an agent in active status can be run.

Run and session history

GET https://api.liyaengine.ai/v1/agents/{agentKey}/runs
GET https://api.liyaengine.ai/v1/agents/{agentKey}/runs/{runId}
GET https://api.liyaengine.ai/v1/agents/{agentKey}/sessions
GET https://api.liyaengine.ai/v1/agents/{agentKey}/sessions/{sessionId}/transcript

runs is a paginated list (page, pageSize, status, session_id query params); runs/{runId} returns one run's full step-by-step trace. sessions is one row per real conversation, not per turn; sessions/{sessionId}/transcript returns every turn of one conversation in chronological order.

Using an SDK

import { LiyaEngine } from '@liyaengine/sdk';

const client = new LiyaEngine({ apiKey: process.env.LIYA_API_KEY! });

const agent = await client.agents.create({
  agent_key: 'support-triage',
  name: 'Support Triage',
  goal: 'Triage incoming support tickets.',
});

await client.agents.deploy(agent.agent_key);

const result = await client.agents.run(agent.agent_key, {
  input: { message: "My order hasn't arrived yet." },
});

Related