The NexAgent Agent Contract

Overview

NexAgent is the platform. Your agent is the service. The platform does not care what language your agent is built in, what model it uses, or how it works internally. It only cares that your agent implements the three required endpoints below.

When a user sends a message, the platform calls your /run endpoint, streams the response back to the user, and saves the conversation. You never touch the user's billing, auth, or UI.

Required endpoints

Authentication

Every request from the platform includes your agent's secret token:

Authorization: Bearer <your_agent_token>

Validate this on every request. Return HTTP 401 for invalid tokens. You set this token when you register your agent and configure it on your service.

POST /run — Request

{
  "message":         "The user's message text",
  "conversation_id": "uuid-v4",
  "history": [
    { "role": "user",      "content": "Previous message" },
    { "role": "assistant", "content": "Previous response" }
  ],
  "user_context": {
    "user_id": "uuid",
    "integrations": {
      "gmail_token":  "oauth_token_or_null",
      "slack_token":  "oauth_token_or_null",
      "notion_token": "oauth_token_or_null"
    }
  },
  "stream": true
}

POST /run — Streamed response (SSE)

data: { "type": "text_delta", "content": "partial text..." }
data: { "type": "text_delta", "content": "more text..." }
data: { "type": "done", "tokens_used": 312 }

// On error:
data: { "type": "error", "message": "Description of error" }

If stream: false, return a plain JSON response:

{
  "content":     "The agent's full response",
  "tokens_used": 312,
  "metadata":    { "sources": [], "actions_taken": [] }
}

Action requests (human-in-the-loop)

Instead of silently executing actions, your agent can request human approval first. Emit an action_request SSE event and the platform surfaces a confirmation card in the chat UI. The user approves, edits, or skips the action before it runs.

// Send before (or instead of) executing:
data: {
  "type":        "action_request",
  "action_id":   "uuid-v4",
  "action_type": "send_email",
  "summary":     "Reply to John about Tuesday's meeting",
  "params": {
    "to":      "john@example.com",
    "subject": "Re: Tuesday meeting",
    "body":    "Hi John, ..."
  }
}

The platform executes the approved action using the user's stored OAuth tokens — your agent never handles credentials directly.

GET /manifest

{
  "name":                  "My Agent",
  "slug":                  "my-agent",
  "version":               "1.0.0",
  "description":           "What your agent does",
  "author":                "Your Name",
  "tier":                  "pro",
  "integrations_required": [],
  "integrations_optional": ["gmail", "notion"],
  "capabilities":          ["content_generation"],
  "max_history_turns":     20
}

Revenue split

NexAgent retains a 30% platform commission. You earn 70% of all subscription revenue generated by your agents. Payouts are processed monthly to your registered payout email.