Neonous

Operate the Neonous AI agent platform — create agents, chat, manage tools, run workflows.

# Neonous Skill

You can operate the **Neonous AI agent platform** on behalf of the user. Neonous lets users create, configure, and deploy AI agents through a web interface — with tools, MCP servers, workflows, templates, and more.

## When to Use API vs Web Interface

**Prefer suggesting the web interface** for complex or visual tasks:
- Creating/editing agents with detailed instructions → **Web UI** has a rich editor, AI-assisted instruction enhancement, and template gallery
- Building workflows → **Web UI** has a visual canvas editor (drag & drop)
- Browsing MCP catalog → **Web UI** has a searchable catalog with one-click install
- Managing MCP server environment variables → **Web UI** handles secrets securely
- Browsing community templates → **Web UI** has categories, previews, and one-click clone

**Use the API** for quick operations:
- Listing agents, tools, workflows (quick status checks)
- Chatting with an agent
- Executing a workflow
- Checking token balance
- Simple agent creation with known parameters
- Scripting and automation

The web interface is at `$NEONOUS_URL` — guide the user there for anything visual or complex.

## Authentication

All API requests require the user's API key:

```
-H "x-api-key: $NEONOUS_API_KEY"
```

Base URL: `$NEONOUS_URL` (e.g., `https://app.neonous-ai.com`).

### How to Get an API Key

Users generate API keys from the **Settings** page in Neonous. The key starts with `nn_` and is only shown once. If not set up yet:

1. Log in to Neonous at `$NEONOUS_URL`
2. Go to **Settings** > **API Keys**
3. Click **Create API Key**, give it a name
4. Copy the key (won't be shown again) and set it as `NEONOUS_API_KEY`

---

## Agents

### List Agents

```bash
curl -s "$NEONOUS_URL/custom/builder/agents" \
  -H "x-api-key: $NEONOUS_API_KEY" | jq '.[]| {id, name, model, enabled}'
```

### Get Agent Details

```bash
curl -s "$NEONOUS_URL/custom/builder/agents/<AGENT_ID>" \
  -H "x-api-key: $NEONOUS_API_KEY" | jq .
```

Returns full config including `instructions`, `predefined_tools`, `custom_tools`, `mcp_servers`.

### List Available Models

Always fetch models before creating an agent — do not hardcode model IDs:

```bash
curl -s "$NEONOUS_URL/custom/builder/agents/available-models" \
  -H "x-api-key: $NEONOUS_API_KEY" | jq '.models[]| {id, provider, display_name, is_default}'
```

Use the model marked `is_default: true` unless the user requests a specific one.

### List Available Tools

```bash
curl -s "$NEONOUS_URL/custom/builder/agents/available-tools" \
  -H "x-api-key: $NEONOUS_API_KEY" | jq '.tools[]| {id, name, description}'
```

Returns pre-defined tools that can be assigned to agents via `predefined_tools`.

### Create an Agent

For complex agents, recommend the web UI — it has AI-assisted generation and a template gallery. For simple agents via API:

```bash
curl -s -X POST "$NEONOUS_URL/custom/builder/agents" \
  -H "x-api-key: $NEONOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "description": "A helpful assistant",
    "instructions": "You are a helpful assistant that...",
    "model": "<MODEL_ID from available-models>",
    "enabled": true,
    "predefined_tools": [],
    "custom_tools": [],
    "mcp_servers": []
  }' | jq .
```

### AI-Generate Agent Config

Let Neonous AI generate a full agent config from a name and description:

```bash
curl -s -X POST "$NEONOUS_URL/custom/builder/agents/generate" \
  -H "x-api-key: $NEONOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Reviewer",
    "description": "Reviews pull requests and suggests improvements"
  }' | jq .
```

Returns a complete agent config (name, instructions, model, tools) ready to use with the create endpoint.

### AI-Enhance Instructions

Improve existing agent instructions with AI:

```bash
curl -s -X POST "$NEONOUS_URL/custom/builder/enhance-instructions" \
  -H "x-api-key: $NEONOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions": "You help with code"}' | jq '.enhanced'
```

### Update an Agent

```bash
curl -s -X PUT "$NEONOUS_URL/custom/builder/agents/<AGENT_ID>" \
  -H "x-api-key: $NEONOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "instructions": "Updated instructions..."
  }' | jq .
```

Only include fields you want to change.

### Delete an Agent

```bash
curl -s -X DELETE "$NEONOUS_URL/custom/builder/agents/<AGENT_ID>" \
  -H "x-api-key: $NEONOUS_API_KEY" | jq .
```

---

## Chat

### Chat with an Agent

Non-streaming generate endpoint — returns a complete JSON response:

```bash
curl -s -X POST "$NEONOUS_URL/custom/builder/chat/generate" \
  -H "x-api-key: $NEONOUS_API_KEY" \
  -H "x-agent-id: <AGENT_ID>" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello, what can you do?"}]}' | jq .
```

Response:
```json
{
  "response": "Hi! I can help you with...",
  "usage": { "inputTokens": 42, "outputTokens": 18, "totalTokens": 60 }
}
```

For multi-turn conversations, include the full message history:
```bash
curl -s -X POST "$NEONOUS_URL/custom/builder/chat/generate" \
  -H "x-api-key: $NEONOUS_API_KEY" \
  -H "x-agent-id: <AGENT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is 2+2?"},
      {"role": "assistant", "content": "4"},
      {"role": "user", "content": "Multiply that by 10"}
    ]
  }' | jq .
```

### List Chat Sessions

```bash
curl -s "$NEONOUS_URL/custom/builder/chat/sessions" \
  -H "x-api-key: $NEONOUS_API_KEY" | jq '.sessions[]| {id, title, agentId, created_at}'
```

Filter by agent: append `?agentId=<AGENT_ID>`.

### Get Chat Session (with Messages)

```bash
curl -s "$NEONOUS_URL/custom/builder/chat/sessions/<SESSION_ID>" \
  -H "x-api-key: $NEONOUS_API_KEY" | jq .
```

### Create a Chat Session

```bash
curl -s -X POST "$NEONOUS_URL/custom/builder/chat/sessions" \
  -H "x-api-key: $NEONOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "<AGENT_ID>", "title": "My Session"}' | jq .
```

### Delete a Chat Session

```bash
curl -s -X DELETE "$NEONOUS_URL/custom/builder/chat/sessions/<SESSION_ID>" \
  -H "x-api-key: $NEONOUS_API_KEY" | jq .
```

---

## MCP Servers

For adding MCP servers, recommend the **web UI** — it has a searchable catalog with one-click install and secure environment variable management.

### List MCP Servers

```bash
curl -s "$NEONOUS_URL/custom/builder/mcp" \
  -H "x-api-key: $NEONOUS_API_KEY" | jq '.[]| {id, name, type, enabled}'
```

### Get MCP Server Details

```bash
curl -s "$NEONOUS_URL/custom/builder/mcp/<MCP_ID>" \
  -H "x-api-key: $NEONOUS_API_KEY" | jq .
```

### List Tools from an MCP Server

```bash
curl -s "$NEONOUS_URL/custom/builder/mcp/<MCP_ID>/tools" \
  -H "x-api-key: $NEONOUS_API_KEY" | jq '.tools[]| {name, description}'
```

### Add an MCP Server (stdio)

```bash
curl -s -X POST "$NEONOUS_URL/custom/builder/mcp" \
  -H "x-api-key: $NEONOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-mcp",
    "name": "My MCP Server",
    "description": "Provides extra tools",
    "config": {
      "connectionType": "stdio",
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "envVars": []
    }
  }' | jq .
```

### Add an MCP Server (http)

```bash
curl -s -X POST "$NEONOUS_URL/custom/builder/mcp" \
  -H "x-api-key: $NEONOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-http-mcp",
    "name": "My HTTP MCP",
    "config": {
      "connectionType": "http",
      "url": "https://mcp.example.com/sse",
      "headers": {}
    }
  }' | jq .
```

### Delete an MCP Server

```bash
curl -s -X DELETE "$NEONOUS_URL/custom/builder/mcp/<MCP_ID>" \
  -H "x-api-key: $NEONOUS_API_KEY" | jq .
```

Add `?force=true` to delete even if agents are using it.

### Test MCP Server Connection

```bash
curl -s -X POST "$NEONOUS_URL/custom/builder/mcp/<MCP_ID>/test" \
  -H "x-a