Skip to main content

Single Agent & LLM Invocation

Sometimes you need a quick answer from an AI without starting a session, managing conversation history, or saving anything to the database.
For example:

  • A one-off query in a dashboard widget.
  • Generating text for a form field on the fly.
  • Running a tool through an agent in a background job.
  • Quickly checking market data or running a calculation.

For these scenarios, Nexus provides two stateless endpoints:

  • /chat/invoke-agent — invokes a specific agent, with full tool-calling support, returning traceability data for all steps.
  • /chat/invoke-llm — invokes a specific LLM configuration directly, without tool usage.

These invocations do not:

  • Create a session.
  • Store conversation history.
  • Save the response anywhere in Nexus.

If you lose the response from these endpoints, it cannot be retrieved again.

Invoke an Agent​

POST /chat/invoke-agent

Executes an agent once, optionally calling any tools it's configured with.
Returns the final output and all trace steps so you can inspect the run in detail.

Payload example:

{
  "agent_id": "f1abff34-xxx",
  "prompt": "What's the current price of gold?",
  "system_message": "You are a helpful assistant"
}

Response example:

{
  "status": "ok",
  "data": {
    "content": "The current price of gold (XAU-USD) is $3,353.51.",
    "type": "dia",
    "status": "ok",
    "trace": [
      {
        "run_id": "d045397e-1833-4e0a-af2c-48427f9d728e",
        "step_id": 1,
        "agent_name": "get_commodity_price",
        "input": {
          "commodity_symbol": "XAU-USD"
        },
        "output": {
          "Ticker": "XAU-USD",
          "Name": "Gold Spot / US Dollar",
          "Price": 3353.51,
          "Timestamp": "2025-08-11T09:16:00Z"
        },
        "status": "ok",
        "created_at": "2025-08-11T09:18:58.707359Z"
      },
      {
        "run_id": "d045397e-1833-4e0a-af2c-48427f9d728e",
        "step_id": 2,
        "agent_name": "final_response",
        "input": null,
        "output": {
          "content": "The current price of gold (XAU-USD) is $3,353.51."
        },
        "status": "ok",
        "created_at": "2025-08-11T09:18:58.707359Z"
      }
    ]
  }
}

Invoke an LLM​

POST /chat/invoke-llm

Sends a single prompt to a specific LLM configuration without any tool calls or history.

Payload example:

{
  "model_config_id": 2,
  "prompt": "Write a short welcome message for a new customer.",
  "system_message": "You are a friendly assistant"
}

Response example:

{
  "status": "ok",
  "data": {
    "content": "Welcome! We're excited to have you on board and look forward to helping you succeed."
  }
}

When to Use Stateless Invocations​

These endpoints are perfect when:

  • You need speed — no need to load or maintain conversation context.
  • You don't need persistence — you just want the answer, not stored history.
  • You want full control over storage — you'll save or process the result in your own system.
  • You're running scheduled or backend jobs — e.g., daily reports or automated alerts.
  • You want isolated runs — each call is fresh, with no risk of leaking prior conversation data.

If you need continuity, session history, or persona context, use the Chat and Session endpoints instead.