How do you build an AI agent with the Plugsky API in TypeScript?

Key facts

Endpoint	POST /v1/chat/completions on the live agent API
SDK	OpenAI Node SDK with a baseURL override, or fetch in edge runtimes
Types	TypeScript types for messages, tools and tool call arguments
Validation	Validate arguments with Zod or JSON Schema before executing a tool
Streaming	Token streaming is live for chat UIs and server-sent events
Runtime	Works in Node.js and serverless/edge functions that allow outbound fetch
Free plan	plugsky-micro and plugsky-lite, no card required
Roadmap	Assistants-style managed endpoints are coming soon

TL;DR

• Set baseURL to Plugsky and keep using the OpenAI Node SDK you already know.
• Type every tool with JSON Schema and validate arguments before execution.
• Run the loop server-side so keys never reach the browser.
• Stream tokens to the client and cap turns to bound cost and latency.
• Start free with plugsky-micro and plugsky-lite, then trial paid models.

How it works, step by step

1. Install the SDK with npm install openai and put the key in an environment variable.
2. Configure the client with baseURL: "https://api.plugsky.com/v1".
3. Define tool schemas and matching TypeScript handlers with validated arguments.
4. Send messages plus tools, then switch on message.tool_calls and dispatch to handlers.
5. Append tool results as messages and re-call until the model returns an answer.
6. Stream the final response to the client and log each turn for debugging.
7. Add approval gates for write tools before moving the agent to production.

Try it yourself

Open the SDK code converter →

Install and configure in TypeScript

The setup mirrors any OpenAI project: install the package, construct a client with your key and override the base URL. Plugsky speaks the same protocol, so types and helpers keep working. In edge runtimes where the SDK is inconvenient, a plain fetch to the same endpoint works, because the request body is standard JSON.

import OpenAI from "openai"
const client = new OpenAI({ apiKey: process.env.PLUGSKY_API_KEY, baseURL: "https://api.plugsky.com/v1" })

Keep the agent loop on the server. A browser-side key is a leaked key, and tool handlers usually need credentials the client must never hold.

A typed tool loop

TypeScript's advantage in agents is the boundary between model output and code. Model-generated arguments are untrusted input: parse them with Zod or validate against the JSON Schema you declared, and reject anything malformed. Then dispatch to a handler, return a compact result, and append it as a tool message before calling the endpoint again.

• One handler per tool with a narrow signature and typed returns.
• Timeouts around every network call the handler makes.
• Errors as data — return them to the model instead of throwing through the loop.
• Turn cap so a confused agent cannot bill indefinitely.

Streaming, memory and cleanup

Stream tokens to the client so long tool executions do not look like a frozen UI, and emit lightweight status events such as "searching orders" between turns. For memory, keep recent messages in the conversation state and persist longer-lived facts in your own store; agent memory is a product decision, not something to leave implicit in a growing prompt.

Before shipping, add scoped keys per agent, approval gates for write tools, audit logging and a regression set that runs on every prompt change. Plugsky offers 30+ models behind one endpoint, so A/B routing across cheap and frontier models is configuration rather than a rewrite. Chat, streaming, JSON mode, function calling, embeddings, RAG and agents are live; audio, images, moderation, files, batch, fine-tuning, assistants and responses are coming soon. See the live pricing page for plans.

Honest comparison

Step	TypeScript pattern	Why it matters	Common mistake
Client	new OpenAI({ baseURL })	Keeps SDK types and ergonomics	Calling OpenAI endpoints directly
Tools	JSON Schema plus Zod parsing	Untrusted arguments are validated	Trusting model output
Loop	switch on tool_calls, dispatch, append	Completes multi-step work	Losing tool call IDs
Delivery	Stream to client, run loop server-side	Keeps keys and tools safe	Exposing the key in the browser
Ops	Turn caps, timeouts, audit logs	Bounds cost and supports review	No trace of what the agent did

Frequently asked questions

Can I use the official OpenAI Node SDK?

Yes. Plugsky is OpenAI-compatible, so you set baseURL to the Plugsky endpoint and keep the rest of your code and types.

Does this work in serverless or edge runtimes?

If the runtime allows outbound HTTPS requests, yes. Use the SDK where it fits, or plain fetch against the same endpoint in constrained runtimes.

How do I validate tool arguments?

Parse model-generated JSON with Zod or a JSON Schema validator before running the handler. Treat every argument as untrusted input.

Where should the agent loop run?

Server-side. The loop needs the API key and tool credentials, and browser code cannot be trusted with either.

Is streaming available?

Yes, token streaming is live, and you can interleave status events between tool turns for a responsive interface.

Can I test from the browser first?

Yes. Open the OpenAI-compatible API tester or convert your existing request with the SDK code converter before writing the full loop.

What plan should I start on?

The free plan covers plugsky-micro and plugsky-lite with no card; a 14-day full-access trial covers paid models. Current plans are on the live pricing page.