Agent integration

Status: Documented architecture pattern. NexoRouter does not publish a first-party Agent SDK yet.

An agent combines model calls with state, execution limits, and optionally tools. NexoRouter provides the model endpoint; your application or framework still controls the loop, memory, tool execution, and approvals.

What is available today

Layer	Status
Non-streaming Chat Completions	Stable and documented.
Multi-turn history in `messages`	Available through the Chat Completions request.
OpenAI SDK with the NexoRouter base URL	Stable for documented calls.
Tool calling	Model- and client-dependent; verification required.
Streaming	Not a verified stable public capability.
Responses API and Agent SDKs that require it	Not supported by the current public surface.
NexoRouter Agent SDK	Does not exist yet.

Recommended architecture

User
  -> your API
      -> validate identity, budget, and input
      -> load conversation state
      -> call POST /v1/chat/completions
      -> validate model output
      -> request human approval for sensitive actions
      -> execute allowlisted tools only
      -> store results and metrics
  <- response

The model should never receive direct access to credentials, databases, or irreversible actions.

Minimal multi-turn loop

This example keeps conversation history but does not execute tools. It is the stable starting point before adding agent behavior.

import OpenAI from "openai";
import type { ChatCompletionMessageParam } from "openai/resources/chat/completions";

const client = new OpenAI({
  apiKey: process.env.NEXOROUTER_API_KEY,
  baseURL: "https://api.nexorouter.com/v1",
  timeout: 60_000,
  maxRetries: 1,
});

const messages: ChatCompletionMessageParam[] = [
  {
    role: "system",
    content: "You are a support planner. Ask before any action and keep answers concise.",
  },
];

export async function nextTurn(userText: string) {
  messages.push({ role: "user", content: userText });

  const response = await client.chat.completions.create({
    model: "deepseek-v4-flash",
    messages,
    max_tokens: 400,
  });

  const answer = response.choices[0]?.message?.content ?? "";
  messages.push({ role: "assistant", content: answer });
  return { answer, usage: response.usage };
}

In production, store state by user or conversation in your backend, not in a global variable.

Before adding tools

Choose a model from Models and confirm a plain-text request.
Test one read-only tool call in an isolated environment.
Validate the tool name and arguments against a strict schema.
Reject any tool outside an allowlist.
Require human approval for payments, deletion, external messages, and permission changes.
Set max_steps, an overall timeout, budget, and concurrency.
Log every step and its request ID.
Only then enable that model/framework pair in production.

Read Tool Calling before assuming a model or client supports tools.

Minimum guardrails

Risk	Control
Infinite loop	Small `max_steps` and an overall deadline.
Unexpected spend	Per-key budget, token cap, and model allowlist.
Prompt injection	Separate instructions, data, and tool results; do not trust retrieved text.
Dangerous tool	Allowlist, strict schema, least privilege, and human approval.
Duplicate retries	Use idempotent operations in your own application.
Data leakage	Redact secrets, limit logs, and avoid sending unnecessary data.
Upstream failure	Bounded backoff, explicit fallback, and request-ID tracing.

Frameworks

Frameworks such as LangChain, Vercel AI SDK, LlamaIndex, Cline, or Roo Code are candidate integrations. Their basic chat path may work with a compatible base URL, but agent flows can require tool calling, streaming, embeddings, or Responses API.

Do not treat a generic framework guide as proof of full compatibility. Follow the candidate integration checklist.

Launch checklist

The key is scoped to this service and environment.
The model is marked available in Models.
The basic request works without streaming.
Every tool was tested with valid and invalid inputs.
Sensitive actions require approval.
The agent has step, time, token, and cost limits.
429, 502, and 504 errors have bounded recovery.
Usage Logs can reconstruct the flow without storing secrets.