Creating and using Agents through the API

Agents are reusable AI configurations that combine capabilities, datasets, published Rules, and presentation metadata. Create and configure an Agent once, then invoke it through the AIPrompt service by passing its agent_id .

This guide walks through the complete server-side flow:

1. Create an Agent with your Luzmo API credentials.

2. Associate the datasets it may use.

3. Optionally link published Rules.

4. Create an Embed authorization for an application user.

5. Invoke the Agent through AIPrompt.

Before you begin

You need:

• A Luzmo API key and token. Keep these credentials on your server.

• A Designer or Owner role in the Luzmo organization to create or configure Agents.

• Luzmo IQ access for users who invoke a saved Agent through AIPrompt.

• The IDs of any datasets you want to associate. See Retrieving Luzmo resource IDs .

Create an Agent

Call the Create Agent endpoint with a localized name and the capabilities the Agent may use.

curl https://api.luzmo.com/0.1.0/agent \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "version": "0.1.0",
    "key": "<your-api-key>",
    "token": "<your-api-token>",
    "properties": {
      "name": { "en": "Revenue assistant" },
      "description": {
        "en": "Answers revenue questions and creates supporting charts."
      },
      "capabilities": ["data_analysis", "chart_creation"],
      "theme_id": "default"
    }
  }'

The response contains the Agent's id . Store this value; you use it both to configure the Agent and as agent_id in AIPrompt requests.

Capabilities

Capabilities determine which kinds of work automatic routing may choose:

An empty capabilities array enables every capability available to the authenticated user. Specify a non-empty list when the Agent should have a narrower purpose.

Associate datasets

Associate each permitted dataset with the Agent using the Securables role. Only Securables with type: "dataset" are accepted.

curl https://api.luzmo.com/0.1.0/agent \
  -H "Content-Type: application/json" \
  -d '{
    "action": "associate",
    "version": "0.1.0",
    "key": "<your-api-key>",
    "token": "<your-api-token>",
    "id": "<agent-id>",
    "resource": {
      "role": "Securables",
      "id": "<dataset-id>"
    }
  }'

When an Agent has associated datasets, they form an allowlist:

• If an AIPrompt request omits dataset inputs, the Agent starts with its associated datasets.

• If the request supplies dataset inputs, only datasets that are also associated with the Agent are considered.

• In both cases, Luzmo removes datasets the authenticated application user cannot access.

• Dataset associations from earlier conversation messages are not reused to bypass the Agent's allowlist.

If the Agent has no associated datasets, normal AIPrompt selection applies: explicit dataset inputs are used when present; otherwise the conversation and datasets accessible to the user can be considered.

Link Rules

You can optionally link a Rule using the linked_rules association role. Create and publish the Rule in Luzmo first, then associate its ID with the Agent.

curl https://api.luzmo.com/0.1.0/agent \
  -H "Content-Type: application/json" \
  -d '{
    "action": "associate",
    "version": "0.1.0",
    "key": "<your-api-key>",
    "token": "<your-api-token>",
    "id": "<agent-id>",
    "resource": {
      "role": "linked_rules",
      "id": "<rule-id>"
    }
  }'

Only a linked Rule's currently published version is applied. A Rule without a published version does not add instructions to the Agent.

Create an Embed authorization

Your server should invoke the Agent on behalf of each application user with an Embed key-token pair. The Embed authorization determines which datasets that user may access and applies their multitenancy configuration, such as Embed filters and connection overrides.

Create the authorization with your private Luzmo API credentials. Grant it use access to every dataset the user may query, including any datasets associated with the Agent.

curl https://api.luzmo.com/0.1.0/authorization \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "version": "0.1.0",
    "key": "<your-api-key>",
    "token": "<your-api-token>",
    "properties": {
      "type": "embed",
      "username": "<unique-application-user-id>",
      "name": "<application-user-name>",
      "email": "<application-user-email>",
      "access": {
        "datasets": [
          { "id": "<dataset-id>", "rights": "use" }
        ]
      }
    }
  }'

See Generating an authorization token for the full authorization flow and Handling multi-tenant data for row-level access controls.

Invoke the Agent with AIPrompt

Pass the saved Agent's ID as agent_id . Do not combine agent_id with agent , task , or capabilities ; those values come from the saved Agent configuration.

curl https://api.luzmo.com/0.1.0/aiprompt \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "version": "0.1.0",
    "key": "<embed-key>",
    "token": "<embed-token>",
    "properties": {
      "agent_id": "<agent-id>",
      "stream": false,
      "response_mode": "mixed",
      "text_format": "markdown",
      "locale_id": "en",
      "input": [
        {
          "type": "text",
          "text": "How is revenue trending, and can you visualize it?"
        }
      ]
    }
  }'

The Agent uses automatic routing across its enabled capabilities. The returned user_message.agent is therefore auto . As with any AIPrompt request, omit conversation_id to start a conversation or pass a previous response's conversation_id to continue it. Set stream: true to receive Server-Sent Events instead of waiting for the complete result.

An Agent must belong to the same Luzmo organization as the authenticated user. An unknown, deleted, or different-organization agent_id returns 404 Not Found .

Apply the Agent theme in your client

theme_id is presentation metadata. AIPrompt does not load the saved Agent's theme or apply it to returned chart and dashboard assets. If your application wants Agent-specific presentation, retrieve the Agent and its Theme configuration and apply that theme when rendering the returned assets.

Maintain the Agent

Use the remaining Agent endpoints to manage its lifecycle:

• Search Agents to retrieve configuration and include linked datasets or Rules.

• Update Agent to change its name, description, capabilities, or theme.

• Associate Agent and Dissociate Agent to manage datasets and Rules.

• Delete Agent to remove it. Deleted Agents can no longer be used by AIPrompt.

Updating, associating, or dissociating requires both a Designer or Owner organization role and modifier access to the Agent. Deleting requires the organization role and owner access.