Basic Text Generation

Simple Question/Answer

typescript

import { Connector, Agent, Vendor } from 'oneringai';

// Setup
Connector.create({
  name: 'anthropic',
  vendor: Vendor.Anthropic,
  auth: { type: 'api_key', apiKey: process.env.ANTHROPIC_API_KEY! },
});

const agent = Agent.create({
  connector: 'anthropic',
  model: 'claude-fable-5-1',
});

// Ask a question
const response = await agent.run('Explain quantum computing in simple terms.');
console.log(response.output_text);

Multi-Turn Conversations

Agents maintain conversation history automatically:

typescript

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-5.6-terra',
});

// First turn
await agent.run('My favorite color is blue.');

// Second turn (agent remembers)
const response = await agent.run('What is my favorite color?');
console.log(response.output_text);
// Output: "Your favorite color is blue."

Configuration Options

typescript

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',

  // Optional settings
  temperature: 0.7,          // Randomness (0.0 - 1.0)
  maxIterations: 50,         // Max tool calling rounds (default: 50)

  instructions: `You are a helpful assistant.
                 Always be concise and professional.`,
});

Runtime Configuration

Change settings during execution:

typescript

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-5.6-terra',
});

// Change to a model that supports sampling controls.
agent.setModel('gpt-4.1');

// Change temperature
agent.setTemperature(0.9);

// Get current settings
console.log(agent.getTemperature()); // 0.9

Structured Output (JSON)

Request JSON output with one vendor-agnostic option, responseFormat. The library translates it to each vendor's native structured-output mechanism where the model supports it — OpenAI (text.format), current supported Anthropic models (output_config.format), and Google/Vertex (responseJsonSchema) — and falls back to a strict prompt instruction otherwise. It then parses (and, on parse failure, re-asks once for) the output and attaches the result to response.output_parsed. The raw JSON string is still available on response.output_text.

Validation contract: on the native path the vendor enforces its supported schema subset server-side. Provider adapters may move unsupported constraints into descriptions so the native request remains portable; Anthropic uses its official SDK transformer for this normalization. On the prompt-fallback path the library guarantees valid, parseable JSON but does not itself validate schema conformance. Validate output_parsed against the original schema when you need every constraint enforced. (This is a deliberate choice to avoid a JSON-schema-validator dependency.)

Two modes:

{ type: 'json_object' } — any valid JSON value.
{ type: 'json_schema', schema, name?, description?, strict? } — JSON constrained to a JSON Schema.

typescript

const agent = Agent.create({ connector: 'openai', model: 'gpt-4.1' });

// Schema-constrained
const res = await agent.run('Extract: Jane Doe, jane@acme.com, Enterprise plan', {
  responseFormat: {
    type: 'json_schema',
    name: 'contact',
    schema: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        email: { type: 'string' },
        plan: { type: 'string' },
      },
      required: ['name', 'email'],
      additionalProperties: false,
    },
  },
});
console.log(res.output_parsed); // { name: 'Jane Doe', email: 'jane@acme.com', plan: 'Enterprise' }

// Any-JSON mode
const summary = await agent.run('Summarize this note as JSON with `title` and `tags`', {
  responseFormat: { type: 'json_object' },
});

// Single-shot, no context management
const direct = await agent.runDirect('Return 3 primary colors as a JSON array of strings', {
  responseFormat: { type: 'json_object' },
});
console.log(direct.output_parsed); // ['red', 'green', 'blue']

The API is identical across vendors — swap the connector (anthropic, google, grok, …) and the same responseFormat works; the library selects the native mechanism or prompt fallback per model.

Behavior & limits:

Aspect	Behavior
Scope	JSON only (`json_object`, `json_schema`)
Schema validation	Native path: the provider-supported subset is enforced server-side; adapters may move unsupported constraints into descriptions. Prompt-fallback path: parseability only. Validate `output_parsed` against the original schema when every constraint matters
`run()` tool loops	Constrains the final answer. OpenAI composes natively and Google composition is model-specific. Anthropic conservatively uses a final tool-free pass whenever tools are present because citation-producing server tools conflict with JSON outputs
Streaming	`stream()` / `streamDirect()` stream raw text and don't attach `output_parsed` (parse the accumulated text yourself). Enforced only where it applies inline (native, or prompt fallback with no tools); `stream()` has no final reformat pass, so with tools on a prompt-fallback vendor the output isn't guaranteed to be JSON (a warning is logged) — use `run()` for that case
Parse failure	After one tool-free re-ask, throws `StructuredOutputError` (carrying raw output + schema) and logs it — never a silent failure
Where to set it	`RunOptions.responseFormat` (`run`/`stream`) and `DirectCallOptions.responseFormat` (`runDirect`/`streamDirect`); the `ResponseFormat` type is exported from the package root

Per-vendor: OpenAI, current supported Anthropic families, and Google/Vertex use native schema output when the concrete model supports it. Older or unknown Claude models use the prompt fallback; Anthropic json_object also remains prompt-based because its native contract is schema-based. Tool composition is model-specific—when it is unavailable, run() performs the final tool-free pass described above. Non-streaming formatted responses report structured_output_enforcement as native, prompt, or repair.