Elaras/

Skills

Skills let your agent take actions during a conversation — not just answer questions, but actually do things. When a visitor asks about their order, books an appointment, or fills in a support request, the agent calls the relevant skill to get real data or complete the action.

There are two types of skill:

TypeWhat it does
Instant skillCalls your system once and returns a result. Use for lookups — order status, availability, account details.
FlowWalks the visitor through a structured multi-step process. Use for booking, intake forms, lead qualification.

Instant skills

How instant skills work

Instant skills are built on AI function calling:

  1. You define a skill in the Elaras dashboard with a name, description, parameter schema, and your endpoint URL.
  2. When the AI decides to use a skill, Elaras sends a POST request to your endpoint with the extracted parameters.
  3. Your endpoint processes the request and returns a JSON response.
  4. Elaras injects the response into the conversation context and the AI continues generating its reply.

The AI decides when to call a skill — you do not call it manually. The description you write tells the AI what the skill does and when to use it.

Adding a skill

Go to Skills in the left nav and click Add skill (or use POST /api/v1/skills from the Developer API). Give it a name, describe what it does, and point it at your endpoint. The description is the most important part — the agent reads it to decide when to call the skill, so be specific about what it does and what questions it answers.

FieldDescription
NameLowercase snake_case identifier, e.g. get_order_status. This is what the AI sees.
DescriptionPlain English explanation of what the skill does and when to use it. The AI reads this to decide when to call it.
Input schemaJSON Schema object describing the parameters the AI must extract from the conversation before calling.
Output schema (optional but recommended)JSON Schema describing the shape your endpoint returns. Lets the AI reason about the response reliably.
Endpoint URLThe URL Elaras will POST to when the skill is called. Must be publicly reachable. Private IPs and non-standard ports are blocked.
API keyA secret you generate. Elaras sends this as Authorization: Bearer <api_key> on every call so your endpoint can authenticate the request. Not retrievable after save — only overwrite is supported.

The request Elaras sends

Elaras is the HTTP client — your endpoint is the server. When the AI calls a skill, Elaras POSTs to the URL you registered. Build it like any REST API endpoint you'd expose for a trusted client to consume.

POST https://your-endpoint.com/skills/get-order-status
Authorization: Bearer your_api_key_here
Content-Type: application/json

{
  "skill": "get_order_status",
  "params": {
    "order_id": "12345"
  },
  "session": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "lead_name": "Jordan",
    "lead_email": "jordan@example.com"
  }
}
FieldDescription
skillThe skill name as registered in the dashboard
paramsThe parameters the AI extracted from the conversation, matching your JSON Schema
session.idThe current session UUID
session.lead_nameLead name if captured, otherwise null
session.lead_emailLead email if captured, otherwise null

Authentication

Authentication is a single Bearer token — the api_key you set when creating the skill. Elaras sends it on every request as Authorization: Bearer <api_key>. Your endpoint checks the header and rejects anything that doesn't match.

// Node.js / Express
app.post('/skills/get-order-status', express.json(), (req, res) => {
  const auth = req.headers['authorization'] ?? '';
  const expected = `Bearer ${process.env.ELARAS_SKILL_API_KEY}`;
  if (auth !== expected) {
    return res.status(401).json({error: 'Unauthorized'});
  }

  const {params} = req.body;
  const order    = getOrder(params.order_id);

  res.json({
    order_id:           order.id,
    status:             order.status,
    estimated_delivery: order.estimated_delivery,
  });
});
<?php
// PHP
$auth    = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
$expected = 'Bearer ' . getenv('ELARAS_SKILL_API_KEY');
if (!hash_equals($expected, $auth)) {
    http_response_code(401);
    echo json_encode(['error' => 'Unauthorized']);
    exit;
}

$body   = json_decode(file_get_contents('php://input'), true);
$order  = getOrder($body['params']['order_id']);

header('Content-Type: application/json');
echo json_encode([
    'order_id'           => $order['id'],
    'status'             => $order['status'],
    'estimated_delivery' => $order['estimated_delivery'],
]);

Use hash_equals / crypto.timingSafeEqual for the comparison — avoids timing-based attacks on token guessing. TLS protects the token in transit, so make sure your endpoint is HTTPS.

Rotating your token: generate a new one, update it on the skill via the dashboard or PUT /api/v1/skills/{id} with api_key, update your server's env var. There's no built-in grace window — rotate during low-traffic time or deploy both values momentarily.

Expected response

Return any JSON object. The response is passed directly to the AI as the skill result:

{
  "order_id": "12345",
  "status": "shipped",
  "estimated_delivery": "2026-07-26",
  "tracking_url": "https://track.example.com/12345"
}

The AI then incorporates this data into its next reply to the user.

Authentication and access control

Elaras authenticates itself to your endpoint with the Authorization: Bearer header. Verify it before processing any request.

For user-level access control — subscription status, account standing, feature entitlements — use session.lead_email or an external_user_id you passed when creating the session to look up the user on your side. Return a plain error message and the AI will relay it to the user:

{ "error": "Your subscription has expired. Please renew at example.com/billing to continue." }

The skill runs on every message, so if the user re-subscribes and sends another message the check passes automatically and the conversation continues — no session reset needed.

ScenarioWhat to return
Subscription expired, access revoked{ "error": "Subscription expired. Please renew to continue." }
Action not allowed for this plan{ "error": "Your plan doesn't include X. Upgrade to access this." }
Temporary issue (rate limit, data not ready){ "error": "..." } with a message the AI can relay
Valid request, user foundNormal response payload

Never use HTTP status codes for business logic. A 401 or 403 from your endpoint tells Elaras the call itself failed (network/infrastructure issue) — not that the user lacks access. Return JSON with a clear message instead so the AI can handle it gracefully inline.

Error handling

Return descriptive errors as JSON — do not return a 4xx or 5xx HTTP status. A non-2xx response signals an infrastructure failure (the call itself didn't land), which Elaras treats differently from a business logic error.

Good:

{ "error": "Order 99999 not found. Please check the order number and try again." }

Bad (treated as a failed invocation, not a missing order):

HTTP 404 Not Found

Rich content in the reply

Skills can optionally return a top-level _blocks key alongside the normal response payload. Blocks are structured UI elements the widget renders inline — buttons, forms, cards, carousels, ratings, banners — instead of plain markdown.

Elaras strips _blocks from the payload before handing it to the AI (so the model doesn't try to reason about the UI structure) and passes them to the widget on the same message.

See the Blocks page for the full catalog of types, how to render them in a custom UI via @elaras/chat-sdk, and how to add your own block types.

Parameter schema example

Here is a complete skill definition for an order status lookup:

Name: get_order_status

Description: Look up the status of a customer order. Call this when the user asks about their order, delivery, or tracking information.

Parameters schema:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order ID or order number mentioned by the user."
    }
  },
  "required": ["order_id"]
}

The AI extracts order_id from the conversation (e.g. "my order 12345") and passes it in params.order_id.

Declaring an output schema

If you provide output_schema, the AI understands the exact shape of your response and composes follow-up turns more reliably against it. Also enables typed clients.

{
  "type": "object",
  "properties": {
    "order_id":           { "type": "string" },
    "status":             { "type": "string", "enum": ["pending", "shipped", "delivered", "cancelled"] },
    "estimated_delivery": { "type": "string", "format": "date" },
    "tracking_url":       { "type": "string", "format": "uri" }
  },
  "required": ["order_id", "status"]
}

If your endpoint returns something that doesn't match the schema, the skill invocation still succeeds — but the mismatch is recorded on the message trace so you can catch it in scenario runs.

Testing a skill

Dashboard: Click Test on the skill's config page — send a payload with custom params, see your endpoint's exact response, response time, and any error.

Developer API: Use this endpoint to fire a live test call from your own tooling — CI pipelines, Postman, or a simple curl. It calls your endpoint with the same signing and timeout rules that the AI uses.

POST /api/developer/v1/skills/{skill_id}/test
Authorization: Bearer sk_live_your_key_here
Content-Type: application/json

Request body:

{
  "params": {
    "order_id": "ORD-123"
  },
  "session": {
    "id": "test-session-abc",
    "lead_name": "Jane Smith",
    "lead_email": "jane@example.com"
  }
}

params must be an object. Pass the same params your skill expects from the AI.

session is optional. If omitted, your endpoint receives "session": null — the same as a skill call before any lead data has been captured. Include it when your skill uses session.lead_email or session.id for access control or personalisation so you can test that path without needing a live chat session.

Response:

{
  "data": {
    "success": true,
    "status_code": 200,
    "response": { "status": "shipped", "tracking_url": "https://..." },
    "latency_ms": 143
  }
}

On failure (non-2xx from your endpoint):

{
  "data": {
    "success": false,
    "status_code": 404,
    "response": { "error": "Order not found" },
    "latency_ms": 89
  }
}

The outer HTTP status is always 200 — success and status_code inside data tell you whether your endpoint responded correctly. Use this to diagnose a failing skill before the AI ever touches it:

# Without session (skill receives session: null)
curl -X POST "https://ask-api.elaras.ai/api/developer/v1/skills/SKILL_ID/test" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"params": {"order_id": "ORD-123"}}'

# With a mock session (test session-bound logic)
curl -X POST "https://ask-api.elaras.ai/api/developer/v1/skills/SKILL_ID/test" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"params": {"order_id": "ORD-123"}, "session": {"id": "test-abc", "lead_name": "Jane Smith", "lead_email": "jane@example.com"}}'

You can find your skill_id from GET /api/developer/v1/skills.

Best practices

  • Verify the Bearer token on every request. Anyone who guesses the URL can POST to it anonymously otherwise. Use a timing-safe compare.
  • Write a precise description. The AI uses it to decide when to call the skill. Be specific about what data it provides and what questions it answers.
  • Keep responses concise. Return only the data the AI needs to answer the question. Large payloads consume more context window and credits.
  • Validate params server-side. The AI extracts params from natural language — always validate and sanitise them before using them in database queries.
  • Return actionable error messages. If something goes wrong, return a message the AI can relay to the user ("I could not find that order — could you double-check the number?").
  • Respond within 10 seconds. Elaras times out skill calls after 10 seconds. For long-running operations, fetch the data asynchronously before the conversation starts or cache recent results.
  • Don't host on sleep-prone infrastructure. Replit dev URLs, free Heroku dynos, and similar sleep after inactivity. Visitors who hit a cold skill will see "temporarily unavailable" responses while it wakes.

Flows

A flow guides the visitor through a fixed sequence of steps — collecting information turn by turn — before completing an action at the end.

Creating a flow

Go to Skills > Flows > New flow. The visual builder lets you add steps, write the messages the agent delivers at each step, and set up branches based on how the visitor responds.

Attaching a flow to an agent

Open the agent's Skills tab and attach the flow. You can set a trigger phrase — a word or phrase that causes the agent to start the flow when the visitor says it. Without a trigger phrase, you control when the flow starts through the flow's own step logic.

Updating a flow

curl -X PUT "https://ask-api.elaras.ai/api/developer/v1/flows/{flow_id}" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead capture v2",
    "steps": [...]
  }'

Deleting a flow

curl -X DELETE "https://ask-api.elaras.ai/api/developer/v1/flows/{flow_id}" \
  -H "Authorization: Bearer sk_live_your_key_here"

Deleting a flow detaches it from all agents automatically.

Tips

  • Keep flows short. More than five or six steps starts to feel like filling in a form.
  • Flows work well combined with instant skills — collect the details in a flow, then use a skill to act on them.

Built-in skills

Built-in skills are provided by Elaras and require no endpoint configuration. Enable them from the agent's Skills tab.

Search Web

Skill name: web_search

Lets the agent search the web in real time during a conversation. When a visitor asks a question your knowledge base doesn't cover, the agent can run a live search and incorporate the results into its reply.

Cost: 10 credits per search.

Enabling it:

Open the agent's Settings tab and scroll to the Search Web section. Toggle it on. Optionally restrict searches to specific domains — useful if you only want the agent to pull from your own site or a set of trusted sources.

How it works:

  • The agent decides when to call the skill based on the question — you don't need to configure a trigger
  • Results are wrapped in an <untrusted_source> block before being passed to the agent, protecting against prompt injection from external content
  • The agent reasons over the results and composes a reply; it does not paste raw search results into the chat

Settings:

SettingDescription
Domain restrictionComma-separated list of domains to limit searches to (e.g. yoursite.com, docs.yoursite.com). Leave blank to search the open web.
Verification modeWhen enabled, the agent attempts to verify factual claims against the search results before responding.

Controlling when the agent searches

The agent decides when to call web_search based on the conversation. You cannot trigger it directly — instead, tell the agent when to use it in your personality instructions.

A broad instruction:

Use web_search whenever the user asks about something that may have changed recently — news, prices, schedules, live events, or anything time-sensitive.

A narrow instruction for a specific use case:

Use web_search only when the user asks about fixture results, league tables, or transfer news. For all other questions, answer from your knowledge base.

The more specific your instruction, the more predictable the agent's behaviour. If you find the agent searching when it shouldn't (or not searching when it should), tighten the instruction and re-test in the preview panel.