@dawn-ai/sdk

Use this when

Start here when you build a Dawn application. @dawn-ai/sdk owns the route-authoring types and helpers most application code uses. Reach for /pure only when an integration needs dependency-free path or hash utilities, and /testing when you author route scenarios for dawn test.

Install and import

pnpm add @dawn-ai/sdk

import { agent, defineMiddleware, defineMemory } from "@dawn-ai/sdk"
import { pureJoin } from "@dawn-ai/sdk/pure"
import { scenarios } from "@dawn-ai/sdk/testing"

Compatibility and audience

@dawn-ai/sdk/testing is the route-scoped scenario API used by dawn test; it is not the @dawn-ai/testing package, which provides a programmatic agent harness.

Public exports

@dawn-ai/sdk

@dawn-ai/sdk/pure

@dawn-ai/sdk/testing

Key contracts

agent() and AgentConfig

Use agent() as a route module's default export. model and systemPrompt are required; optional policy, retry, reasoning, subagent, and tool fields are preserved on the branded descriptor.

export declare function agent<const Subagents extends SubagentMap = {}>(
  config: AgentConfig<Subagents>,
): DawnAgent<Subagents>

export interface AgentConfig<Subagents extends SubagentMap = {}> {
  readonly delegation?: DelegationConfig<NoInfer<Extract<keyof Subagents, string>>>
  readonly description?: string
  readonly model: KnownModelId
  readonly provider?: ModelProviderId
  readonly reasoning?: ReasoningConfig
  readonly retry?: RetryConfig
  readonly recursionLimit?: number
  readonly subagents?: Subagents
  readonly tools?: ToolScope
  readonly systemPrompt: string
}

Fields: @dawn-ai/sdk#.:AgentConfig

Behavior contract sdk.agent.descriptor-shape

agent() returns a branded descriptor and includes optional tool scope only when supplied.

Exact agent configuration signatures

export interface ReasoningConfig {
  readonly effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh"
}

Fields: @dawn-ai/sdk#.:ReasoningConfig

export interface RetryConfig {
  readonly maxAttempts?: number
  readonly baseDelay?: number
}

Fields: @dawn-ai/sdk#.:RetryConfig

export declare function isDawnAgent(value: unknown): value is DawnAgent

allow() and reject()

Middleware returns an explicit continue or reject result. Use allow(context?) to continue and reject(status, body?) to stop the request.

export declare function defineMiddleware(fn: DawnMiddleware): DawnMiddleware

export declare function allow(context?: Record<string, unknown>): ContinueResult

export declare function reject(status: number, body?: unknown): RejectResult

Behavior contract sdk.middleware.result-shapes

allow() and reject() return discriminated result objects; omitted context and body properties are absent.

validateModelId()

Use this helper to improve author feedback for likely model-ID typos. It does not restrict custom model IDs.

export declare function validateModelId(opts: {
  readonly model: string
  readonly provider?: string
}): ModelIdValidation

Behavior contract sdk.validate-model-id.advisory

Model validation is advisory: curated near-misses return provider-specific suggestions, while an uncurated or unresolved provider returns ok: true.

Application guidance

Treat ok: false as a warning for application feedback, not a runtime gate.

RouteConfig

runtime, streaming, and tags are reserved metadata and do not change execution today. Select deployment runtime with build.targets, select streaming through the endpoint or transport, and do not rely on tags for behavior.

export interface RouteConfig {
  readonly runtime?: "node" | "edge"
  readonly streaming?: boolean
  readonly tags?: readonly string[]
}

Fields: @dawn-ai/sdk#.:RouteConfig

defineMemory()

Declare the typed schema, kind, and namespace dimensions for a route's memory.ts module. identity is optional; semantic memory defaults its reconciliation identity elsewhere.

export declare function defineMemory<S extends z.ZodTypeAny>(def: {
  kind: DefinedMemory["kind"]
  scope: readonly MemoryScopeDimension[]
  schema: S
  identity?: readonly string[]
}): DefinedMemory<S>

Choosing a surface

Application routes normally import the root. Use /pure for infrastructure that must avoid runtime dependencies. Use /testing in *.scenario.ts files; use @dawn-ai/testing when a test needs a programmatic harness instead. Its detailed reference lands with the testing package page.

Examples and related guides

import { agent } from "@dawn-ai/sdk"
 
export default agent({
  model: "gpt-5-mini",
  systemPrompt: "Answer concisely.",
})

Continue with Agents, Middleware, Long-term Memory, Scenario Testing, and Agent Test Harness.