OpenRouter Integration

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/src/modules/agent/infrastructure/agent.openrouter-model.ts
• apps/api/test/modules/agent/infrastructure/agent.openrouter-model.test.ts
• apps/api/src/infrastructure/http/routes/agent.router.ts
• apps/api/package.json
• apps/api/src/infrastructure/http/app-router.ts
• apps/api/test/infrastructure/http/agent.router.test.ts

OpenRouter Integration provides the primary Large Language Model (LLM) execution layer for the Thoth agent. It serves as an infrastructure implementation that connects the application's agent logic to external generative models via the OpenRouter API.

This module abstracts model communication using the LangChain framework. It enables the system to generate text replies based on a combination of system instructions and user message history.

Architecture and Infrastructure

The OpenRouterAgentModel class implements the AgentModel port. It encapsulates the ChatOpenRouter client provided by the @langchain/openrouter package.

Core Logic Flow

The implementation follows these steps when generating an answer:

1. Receives a ModelInput containing a system prompt and an array of conversation messages.
2. Prepends the system message to the conversation array.
3. Invokes the model with a defined timeout signal.
4. Returns the generated text or throws a specialized error if the service is unavailable.

Sources: apps/api/src/modules/agent/infrastructure/agent.openrouter-model.ts:14-36, apps/api/test/modules/agent/infrastructure/agent.openrouter-model.test.ts:35-47

HTTP Interface and Routing

OpenRouter capabilities are exposed through the AgentRouter. This router handles thread management and message submission.

• Thread Creation: POST /threads initiates a new conversation context related to a specific bio handle.
• Message Interaction: POST /threads/:threadId/messages accepts user input and triggers the model invocation.

Sources: apps/api/src/infrastructure/http/routes/agent.router.ts:21-65, apps/api/src/infrastructure/http/app-router.ts:52

Sequence of a Model Request

Configuration and Dependencies

The integration relies on specific environment variables and external libraries.

Element	Type	Description
@langchain/openrouter	Dependency	The bridge library between LangChain and OpenRouter.
OPENROUTER_API_KEY	Env Var	The authentication key for the OpenRouter service.
LLM_MODEL	Env Var	The specific model identifier (e.g., a Claude or GPT variant).
MODEL_TIMEOUT_MS	Constant	Set to 30,000ms to prevent hanging requests.

Sources: apps/api/package.json:20, apps/api/src/modules/agent/infrastructure/agent.openrouter-model.ts:11-18

Error Handling

The integration maps model-level failures to internal application errors to ensure consistent API responses.

1. 502 Bad Gateway: If the OpenRouter API call fails or times out, the system throws an AppError with the code AGENT_MODEL_UNAVAILABLE.
2. 429 Rate Limiting: Model-specific errors like rate limits are caught and treated as service unavailability.
3. Timeouts: Requests are forcibly aborted if they exceed 30 seconds, resulting in a 502 status.

Sources: apps/api/src/modules/agent/infrastructure/agent.openrouter-model.ts:11, apps/api/src/modules/agent/infrastructure/agent.openrouter-model.ts:38-43, apps/api/test/modules/agent/infrastructure/agent.openrouter-model.test.ts:49-57

Implementation Detail

// apps/api/src/modules/agent/infrastructure/agent.openrouter-model.ts:20-36

async answer({ system, messages }: ModelInput): Promise<string> {
    const systemMessage = { role: "system", content: system };
    const conversation = [systemMessage, ...messages];

    try {
        const reply = await this.model.invoke(conversation, {
            signal: AbortSignal.timeout(MODEL_TIMEOUT_MS),
        });

        return reply.text;
    } catch (err) {
        log.error("Model call failed", { err });
        throw new AppError(
            ErrorCode.AGENT_MODEL_UNAVAILABLE,
            BAD_GATEWAY,
            "The model is unavailable",
        );
    }
}

This snippet shows the core implementation of the model invocation and error handling.

OpenRouter Integration enables the Thoth agent to process natural language by offloading LLM execution to the OpenRouter platform while maintaining a controlled, timed-out interface within the API infrastructure.