Skip to main content

Managing AI Agents

In Nexus, AI Agents combine a configured LLM with zero or more tools, allowing them to interact intelligently with your data and external services.

You can create, update, and manage agents programmatically using the API.

Create an Agent​

POST /agent

To create an agent, specify a name, description, a previously created model_config_id, and a list of tools (both built-in and MCP tools). You'll need the returned agent_id for the creation of a new chat session.

Payload example:

{
  "name": "My Data Scientist",
  "description": "An agent that can query data and generate visualizations",
  "model_config_id": 2,
  "tools": [
    {
      "tool_name": "find_metadata",
      "tool_server_id": "nexus",
      "properties": []
    },
    {
      "tool_name": "create_graph",
      "tool_server_id": "nexus",
      "properties": []
    },
    {
      "tool_name": "get-forecast",
      "tool_server_id": "@mcp-examples/weather",
      "properties": []
    },
    {
      "tool_name": "query",
      "tool_server_id": "@uday210/salesforce-mcp-server",
      "properties": [
        {
          "key": "sfUsername",
          "value": "example_user@example.com",
          "datatype": "string"
        },
        {
          "key": "sfPassword",
          "value": "secret-password",
          "datatype": "string"
        },
        {
          "key": "sfSecurityToken",
          "value": "XYZ123TOKEN456",
          "datatype": "string"
        }
      ]
    }
  ]
}

Response example:

{
  "status": "ok",
  "data": {
    "agent_id": "ed4a919d-b763-4320-8298-99dd3c3a3b1c"
  }
}

Get an Agent​

GET /agent/{agent_id}

Retrieves the details of a specific agent.

Response example:

{
  "status": "ok",
  "data": {
    "id": "ed4a919d-b763-4320-8298-99dd3c3a3b1c",
    "user_id": "0x00..",
    "name": "My Data Scientist",
    "description": "An agent that can query data and generate visualizations",
    "model_config_id": 2,
    "tools": [
      {
        "tool_name": "find_metadata",
        "tool_server_id": "nexus",
        "properties": []
      },
      {
        "tool_name": "create_graph",
        "tool_server_id": "nexus",
        "properties": []
      },
      {
        "tool_name": "get-forecast",
        "tool_server_id": "@mcp-examples/weather",
        "properties": []
      },
      {
        "tool_name": "query",
        "tool_server_id": "@uday210/salesforce-mcp-server",
        "properties": [
          {
            "key": "sfUsername",
            "value": "example_user@example.com",
            "datatype": "string"
          },
          {
            "key": "sfPassword",
            "value": "secret-password",
            "datatype": "string"
          },
          {
            "key": "sfSecurityToken",
            "value": "XYZ123TOKEN456",
            "datatype": "string"
          }
        ]
      }
    ]
  }
}

Update an Agent​

PATCH /agent/{agent_id}

You can update any of the agent's properties, including name, description, LLM config, and tools.

Payload example:

{
  "name": "My Video Data Scientist",
  "description": "An agent that can query data and generate videos",
  "model_config_id": 2,
  "tools": [
    {
      "tool_name": "find_metadata",
      "tool_server_id": "nexus",
      "properties": []
    },
    {
      "tool_name": "create_graph",
      "tool_server_id": "nexus",
      "properties": []
    },
    {
      "tool_name": "get-forecast",
      "tool_server_id": "@mcp-examples/weather",
      "properties": []
    },
    {
      "tool_name": "query",
      "tool_server_id": "@uday210/salesforce-mcp-server",
      "properties": [
        {
          "key": "sfUsername",
          "value": "example_user@example.com",
          "datatype": "string"
        },
        {
          "key": "sfPassword",
          "value": "secret-password",
          "datatype": "string"
        },
        {
          "key": "sfSecurityToken",
          "value": "XYZ123TOKEN456",
          "datatype": "string"
        }
      ]
    }
  ]
}

Response example:

{
  "status": "ok",
  "data": {}
}

Delete an Agent​

DELETE /agent/{agent_id}

Removes an agent permanently.

Response example:

{
  "status": "ok",
  "data": {}
}

List all Agents​

GET /agent

Lists all agents associated with the authenticated user.

Response example:

{
  "status": "ok",
  "data": {
    "agents": [
      {
        "id": "322b181d-b247-41ce-8164-e6220bf09f4b",
        "name": "My Data Scientist",
        "description": "An agent that can query data and generate visualizations",
        "model_config_id": 2,
        "tool_count": 4
      }
    ]
  }
}