Agent Spec

Every field on the Agent interface — model, tools, middleware, budgets, reasoning, and structured output.

An Agent (alias AgentSpec) is the declarative configuration the runner executes. Pass it to runAgent, runAgentStream, or register it on Maniac.

Required fields

import type { Agent } from "@maniac-ai/agents";

const spec: Agent = {
  id: "researcher",
  instructions: "Be thorough and cite sources.",
  model: new OpenAICompatibleModel({ slug: "gpt-4o" })
};

Field	Type	Description
`id`	`string`	Stable agent identifier for tracing and memory namespaces
`instructions`	`string \| InstructionsBuilder`	System prompt, or a function of `RequestContext`
`model`	`Model`	Provider adapter implementing `infer` and `stream`

Tools and toolsets

const spec: Agent = {
  id: "support",
  instructions: "...",
  model,
  tools: [lookupOrder],           // inline Tool definitions
  toolsets: [mcpFilesystem]       // BaseToolset / MCPToolset instances
};

See Defining tools and Builtin tools.

Depth and delegation

Field	Default	Description
`max_depth`	`1`	Maximum nested sub-agent depth when toolsets call `asDelegated()`

Budget

budget: {
  max_iterations: 32,      // LM loop iterations (default 32)
  max_tokens: 50_000,      // cumulative prompt + completion tokens
  max_cost_usd: 1.0,       // cumulative USD when provider reports cost
  max_wall_seconds: 120    // wall-clock ceiling
}

Omit fields to disable that limit. See Running agents — budgets.

Middleware and guardrails

Field	Purpose
`lm_middleware`	Transform or log `InferenceRequest` / `InferenceResponse`
`tool_middleware`	Wrap tool invocation
`lm_guardrails`	Block, rewrite, or require approval on LM output
`tool_guardrails`	Block, rewrite, or require approval on tool calls

See Middleware and Permissions.

Step hooks

Field	Purpose
`step_hooks`	`beforeStep`, `shouldStop`, `afterStep`, `beforeFinalize` hooks
`prepare_step`	Sugar for a `beforeStep` hook that rewrites the next request
`stop_when`	Sugar for a custom termination predicate

Hooks compose left-to-right in registration order.

Structured output

import { z } from "zod";

const OutputSchema = z.object({
  answer: z.string(),
  count: z.number().int()
});

const spec: Agent = {
  id: "assistant",
  instructions: "Respond with JSON matching the schema.",
  model,
  output_model: OutputSchema,
  output_repair_attempts: 1  // default 1 when output_model is set
};

Validated value lands on AgentResult.output. See Running agents — structured output.

Reasoning

reasoning: { effort: "high" }  // "minimal" | "low" | "medium" | "high"
// or
reasoning: { max_tokens: 10_000 }  // Anthropic thinking.budget_tokens

Applied to every LM call unless a prepare_step hook overrides request.reasoning. See Streaming and reasoning.

Other fields

Field	Description
`repl`	Python REPL config (`PythonSandboxClient`)
`memory`	Per-agent memory override
`observational_memory`	Per-agent observation config
`policy`	Permission policy override
`background`	Per-agent background-task eligibility
`plans_enabled`	Auto-inject `set_plan` tool (default `false`)

AgentSpec is a deprecated alias kept for backwards compatibility.

Agent Spec

On this page