createAgent

createAgent is the primary factory for building LLM-backed agents. It accepts a declarative configuration object and returns a fully functional Agent with conversation history, tool calling, streaming, and lifecycle hooks.

Model strings support two formats: explicit "providerID/modelID" or bare model IDs like "gpt-4o" where the provider is auto-resolved from the catalog. See Model Resolution for details.

import { createAgent } from "@comma-agents/core";

const agent = createAgent({
  name: "assistant",
  model: "openai/gpt-4o",
  systemPrompt: "You are a helpful coding assistant.",
  tools: ["run_command", "read_file", "edit_file"],
});

Provider and Model Options

Two complementary fields control generation behavior:

providerOptions

Use providerOptions for provider-specific capabilities such as extended thinking or reasoning effort:

const thinker = createAgent({
  name: "planner",
  model: "anthropic/claude-sonnet-4-5",
  providerOptions: {
    anthropic: { thinking: { type: "enabled", budgetTokens: 8000 } },
  },
});

modelOptions

Use modelOptions for provider-independent generation controls such as temperature, token limits, and sampling:

const creative = createAgent({
  name: "writer",
  model: "openai/gpt-4o",
  modelOptions: {
    temperature: 0.9,
    maxOutputTokens: 4096,
    seed: 42,
  },
});

For supported fields, see the modelOptions table in the load agent docs.

Structured Output

Set outputSchema to a supported schema such as a Zod object. The agent requests a structured object response that conforms to the schema:

import { createAgent } from "@comma-agents/core";
import { z } from "zod";

const classifier = createAgent({
  name: "classifier",
  model: "openai/gpt-4o",
  outputSchema: z.object({
    category: z.string(),
    confidence: z.number(),
  }),
});

Conversation Context

Use context to keep exported history intact while limiting what the next model call sees:

const writer = createAgent({
  name: "writer",
  model: "openai/gpt-4o",
  context: {
    rollingWindow: 40,
    compaction: { keepRecent: 8 },
  },
});

rollingWindow may be a number or { maxRecords }. compaction may be true or an object with keepRecent and threshold. Programmatic callers can also pass transformRecords for custom record preparation.

AgentConfig

The configuration object passed to createAgent.

Declarative Custom Agent Types

Use defineAgentType and registerAgent when JSON or YAML files need to create a reusable custom agent implementation by name. The configuration schema validates the agent's config object before the factory runs.

import {
  createAgent,
  defineAgentType,
  registerAgent,
} from "@comma-agents/core";
import { z } from "zod";

registerAgent(
  "prefixed-echo",
  defineAgentType({
    configSchema: z.object({ prefix: z.string() }).strict(),
    create: ({ name, config }) =>
      createAgent({
        name,
        execute: async (message) => `${config.prefix}${message}`,
      }),
  }),
);

After registration, strategy and standalone agent files can reference the type:

type: prefixed-echo
config:
  prefix: "Echo: "

Custom type names cannot be llm or user. Keep implementation-specific fields inside config; unknown types and invalid configuration fail when the agent is loaded.

AgentTypeDefinition

The schema and factory used to register a declarative custom agent type.

AgentTypeContext

The validated configuration and runtime services passed to the custom factory.

AgentTypeRuntime

Loader-provided services available to registered agent factories.

Agent Object

createAgent returns an Agent — a plain object (no classes) with methods for calling, streaming, inspecting history, and resetting state.

AgentCallResult

call() returns an AgentCallResult containing the final text, token usage, finish reason, the full message chain, and each step of the agentic loop.

const agent = createAgent({
  name: "writer",
  model: "openai/gpt-4o",
});

const result = await agent.call("Hello");
console.log(result.text);
console.log(result.usage);
console.log(result.finishReason);