AgentNexus Docs

AgentNexus is a full-stack AI agent management platform that lets you create, train, deploy, and manage intelligent conversational AI agents.

Core features include: a visual agent builder, knowledge base management, multi-channel deployment, conversation history tracking, and the ancli CLI tool.

Whether you're a solo developer or an enterprise team, AgentNexus helps you launch a professional AI agent in minutes.

1. Sign Up: Visit AgentNexus and click 'Get Started Free'. Register with email, Google, or GitHub.

2. Create Agent: In the Dashboard, click 'Create Agent'. Use ✨ AI Builder for instant setup — just paste a URL or describe your business. Or set name, prompt, and model manually.

3. Add Knowledge: Go to agent details and upload documents, paste URLs, or type text into the knowledge base.

4. Test: Use the Sandbox chat to test conversations with your agent and fine-tune responses.

5. Deploy: Use the Publish tab to create an included OpenClaw or Hermes managed instance.

Each agent includes: name, description, system prompt, LLM model selection, temperature, and knowledge base config.

Supported LLM models: Connect to 100+ models via OpenRouter, including GPT-4o, Claude 3.5, Gemini, Kimi K2.5, and more.

✨ AI Builder: Click the AI Builder button on any agent page to get AI-guided setup. Paste a website URL, describe your business, or share documents — the AI will generate a complete AgentBlueprint and auto-fill your configuration with one click.

Agent configuration can be changed at any time — changes take effect immediately without redeployment.

Dashboard: Create, edit, delete, and clone agents. CLI: ancli agents list / create / get / update / delete.

The Knowledge Base lets your agent answer questions based on your content, instead of relying on generic AI knowledge.

Three knowledge sources are supported: text input, URL scraping, and file upload (PDF, TXT, CSV, etc.).

Under the hood, pgvector is used for semantic retrieval (RAG), ensuring accurate and contextual answers.

CLI: ancli knowledge list / add --text / add --url / add --file / delete.

The AgentNexus Harness Engine provides secure, efficient external tool invocation for your agents. It operates in two modes: BYOK (Bring Your Own Key) and Native OAuth.

Ecosystem Overview: We support 20+ native toolkits, including Google Workspace (Gmail, Drive, Sheets, Calendar), Notion, GitHub, Linear, and Jira.

BYOK Mode: User-provided API keys (like Slack Tokens or Tavily keys) are securely encrypted and stored using AES-256-GCM in our vault.

Native OAuth Mode: With a single click to authorize (e.g. Google or Notion), the system uses strongly-typed, strictly scoped JWTs for frictionless API calls.

JIT Token Refresh: Our proprietary 'Just-In-Time' token renewal architecture. When OAuth Access Tokens expire, the AgentNexus engine silently refreshes the token ms before the agent executes the action, saving you precious context length and LLM invocation costs.

Unlike traditional MCP (Model Context Protocol) solutions, AgentNexus Native Integrations avoid complex round-trips for token negotiation, achieving the lowest latency and highest reliability.

AgentNexus includes a comprehensive tool call observability system, enabling real-time monitoring of agent tool execution.

tool_call_logs table: Every tool call is automatically logged with tool ID, action ID, status (success/error/timeout/rate_limited), latency, request/response summaries, and error messages.

Activity Dashboard: The /dashboard/tool-logs page shows stats cards (total calls, success rate, avg latency, top tool) with status filters for quick debugging.

CLI Support: Run `ancli tools logs` for recent call logs, `ancli tools stats` for aggregate statistics.

Circuit Breaker: After 5 consecutive failures, the circuit opens for that tool, preventing cascade failures. Run `ancli tools health` to inspect circuit states.

Retry Logic: Built-in exponential backoff retry (max 2 retries), with automatic Retry-After header parsing for 429 rate-limited responses. 5xx server errors also trigger auto-retry.

Event-driven triggers let external services (GitHub, Slack, Gmail) automatically wake your agents via Webhooks.

Trigger Catalog: Supports github_push, github_issue, github_pr, slack_message, gmail_new_email, and more.

Creation Flow: Run `ancli triggers create --tool github --type github_push --agent <agentId>`. The system returns a Webhook URL and secret. Paste the URL into your GitHub repo's Webhook settings.

Security Verification: HMAC-SHA256 signature verification ensures only legitimate webhook requests are processed.

Event Processing: When a webhook fires, the payload is formatted as a user message and automatically sent to the target agent for processing.

Management Commands: `ancli triggers list` to view all triggers, `ancli triggers test <id>` to simulate a trigger event.

Custom Tool Import lets you integrate any third-party API into AgentNexus using an OpenAPI 3.x spec — no code required.

Import Flow: Prepare your OpenAPI JSON spec file and run `ancli tools import --spec ./my-api.json --name 'My CRM' --id my-crm`.

Auto-Parsing: The system automatically parses paths, methods, parameters (query/body), authentication schemes, and response mappings from the spec.

Auth Support: Automatically detects API Key, Bearer Token, and OAuth2 auth types, with manual override available.

Limits: Max 50 operations per spec, max file size 500KB, ensuring performance and security.

Management: `ancli tools custom list` to view imported tools, `ancli tools custom delete <id>` to remove.

All agent conversations are automatically saved, including user messages and AI responses.

In the Dashboard, you can filter by agent, view full conversation history, or delete specific conversations.

Conversation data is used to analyze agent performance and optimize prompts.

CLI: ancli conversations list / list --agent <id> / get / delete.

AgentNexus currently supports included OpenClaw and Hermes managed deployments. Starter includes 1 deploy slot; Advanced includes 10 deploy slots.

Flow: select OpenClaw or Hermes → choose preset → Deploy included instance → queued/provisioning/health checking/active.

In-slot deployments do not create a second Stripe subscription; over-limit users are shown upgrade or destroy-existing-deployment paths.

CLI: ancli deploy generate (preview config) / ancli deploy fly --engine openclaw|hermes --token <FLY_API_TOKEN>.

ancli is the official AgentNexus CLI tool (current version: v0.1.0). It lets you manage the full lifecycle of your AI agents directly from the terminal.

━━━ 📦 Installation ━━━

Prerequisite: Node.js 18 or higher.

Install globally: npm install -g @agtnxai/cli

Verify installation: ancli --version

━━━ 🔐 Authentication (required on first use) ━━━

Step 1: Log in to AgentNexus Dashboard → Settings → Developer / CLI.

Step 2: Click "Generate CLI Token" and copy your personal token.

Step 3: In your terminal, run: ancli auth login --token <your_token>

Check login status: ancli auth status

Log out: ancli auth logout

━━━ 🤖 Agent Management (agents) ━━━

List all agents: ancli agents list

Create an agent: ancli agents create --name "Customer Support" --model gpt-4o

View details: ancli agents get <agent-id>

Update an agent: ancli agents update <agent-id> --name "New Name"

Delete an agent: ancli agents delete <agent-id>

━━━ 📚 Knowledge Base (knowledge) ━━━

List knowledge sources: ancli knowledge list --agent <agent-id>

Add text: ancli knowledge add --agent <agent-id> --text "Product costs $100"

Add a URL: ancli knowledge add --agent <agent-id> --url https://example.com/faq

Upload a file: ancli knowledge add --agent <agent-id> --file ./product-manual.pdf

Delete a source: ancli knowledge delete <knowledge-id>

━━━ 💬 Conversation History (conversations) ━━━

List conversations: ancli conversations list

Filter by agent: ancli conversations list --agent <agent-id>

View details: ancli conversations get <conversation-id>

Delete: ancli conversations delete <conversation-id>

━━━ 🔧 Tools & Triggers (tools / triggers) ━━━

View tool call logs: ancli tools logs

View tool statistics: ancli tools stats

Check circuit breaker health: ancli tools health

Import a custom API: ancli tools import --spec ./openapi.json --name "My CRM" --id my-crm

List custom tools: ancli tools custom list

Create a Webhook trigger: ancli triggers create --tool github --type github_push --agent <agent-id>

List triggers: ancli triggers list

Simulate a trigger event: ancli triggers test <trigger-id>

━━━ 🚀 Deployment (deploy) ━━━

Preview deployment config: ancli deploy generate

Deploy OpenClaw/Hermes: ancli deploy fly --engine openclaw|hermes --token <FLY_API_TOKEN>

━━━ ⚙️ Other Commands ━━━

Check credit balance: ancli credits

Manage billing: ancli billing

View analytics: ancli analytics

Manage Persona templates: ancli personas list

Manage safety constraints: ancli constraints list

Manage secret vault: ancli vault list

Set local config: ancli config set api-url https://agtnx.ai

━━━ 💡 Pro Tips ━━━

All commands support -o json output for scripting and CI/CD: ancli agents list -o json

Custom API URL: ancli --api-url https://your-server.com agents list

Disable colored output: ancli --no-color agents list

Exit codes: 0=success | 1=error | 2=bad args | 3=auth failed | 4=not found

Account: View and manage account information (email, username, User ID).

Developer / CLI: Get your CLI token and view quick start commands here.

Plans: Trial (one-time 7-day trial) / Starter ($29.90/mo, 2,000 credits) / Advanced ($299/mo, 20,000 credits) / Enterprise (contact sales).

Appearance: Supports light/dark/system theme switching.

Language: Switch between English, Chinese, and Spanish interface.

AgentNexus provides a complete REST API. All Dashboard features are available via API calls.

Authentication: Requests must include a valid Supabase Auth session cookie or API token.

Key endpoints:

We prioritize security at every stage of design, providing financial-grade protection for enterprise data.

Compliance Ready: Our system architecture is designed to meet SOC 2 Type II and GDPR standard requirements.

Tenant Isolation: All agent configurations, conversation histories, and knowledge base data are strictly isolated via Row Level Security (RLS) at the database level.

SSO & RBAC: Upcoming support for SAML SSO integrations with Okta, Google Workspace, and Azure AD. Workspaces enforce fine-grained Role-Based Access Control (Owner, Admin, Member).

Encryption: All data in transit utilizes TLS 1.3 encryption. Data at rest, including user-provided LLM and Tool keys, is encrypted using AES-256-GCM logic.

Audit Logging: Enterprise plans provide fully managed operational audit trails, supporting real-time log ingestion into your SIEM system via streaming webhooks.

AgentNexus operates on a globally distributed edge network, ensuring your agents are always online and responding with minimal latency.

99.99% Uptime: Enterprise customers benefit from an ironclad 99.99% SLA guarantee, backed by SLA credits.

Edge Computed Deployments: Our frontend and gateway routing are deployed on edge nodes worldwide, providing sub-50ms TTFB across regions.

Fault-Tolerant Architecture: The core Agent Harness Engine is fully stateless and auto-scales instantly to handle massive concurrent enterprise traffic.

As your team and operations scale, leverage the Workspace system for secure, multi-tenant collaboration.

Multiple Workspaces: A single developer account can create and hot-swap between multiple isolated Organization workspaces instantly.

Resource Isolation: Model limits, knowledge base storage, and billing cycles are perfectly isolated across workspaces, easing departmental chargebacks.

Team Invites & Roles: Invite team members effortlessly via unique links, granting Viewer roles for external vendors or Admin roles for senior developers.