Agents

An agent is the default scaffolded route in Dawn — an LLM-driven workflow that picks tools at runtime. It's the path we recommend when you want the model to decide what to do; for deterministic flows, prefer a workflow, graph, or chain.

A minimal agent

A route's index.ts exports an agent created by agent({ model, systemPrompt }). Tools in the sibling tools/ directory are auto-discovered and wired into the generated graph; the LLM picks when to call them.

import { agent } from "@dawn-ai/sdk"
 
export default agent({
  model: "gpt-5-mini",
  systemPrompt:
    "You are a research assistant. Answer questions thoroughly and cite your sources.",
})

Tools live next to the agent — index.ts is the agent entry, and any TS file in tools/ is discovered for it. Param types are inferred from the function signature at dawn build time and made available to the generated graph.

Model providers

The built-in agent() route materializes to a LangChain chat model. Dawn infers providers for known model families and lazy-loads the matching LangChain integration package. Supported built-in provider ids are openai, anthropic, google, mistral, groq, ollama, xai, and openrouter; see ModelProviderId. Raw graph and chain routes can still instantiate any provider directly.

Set provider to one of the supported built-in provider ids when the model name is an alias, ambiguous, local, or routed through a provider gateway:

src/app/(public)/research/index.ts

import { agent } from "@dawn-ai/sdk"
 
export default agent({
  model: "llama3.1",
  provider: "ollama",
  systemPrompt: "You are a helpful assistant.",
})

Dawn includes the OpenAI integration for the default path. Install other LangChain provider packages as your app needs them:

bash

pnpm add @langchain/anthropic     # anthropic
pnpm add @langchain/google-genai  # google
pnpm add @langchain/mistralai     # mistral
pnpm add @langchain/groq          # groq
pnpm add @langchain/ollama        # ollama
pnpm add @langchain/xai           # xai
pnpm add @langchain/openrouter    # openrouter

dawn check (and dawn verify) warn when a model id isn't in Dawn's curated list for the resolved provider (openai, google, anthropic, xai), with did-you-mean suggestions; the runtime prints the same advisory once when the model is constructed. The lists are advisory — new, proxy, or gateway model ids run fine if your provider accepts them, and providers without curated lists (mistral, groq, ollama, openrouter) are never warned about.

When to pick an agent

Dawn supports four route entry shapes. Pick the one that fits the problem:

Agent — LLM-driven, model picks tools at runtime. Default for conversational and discovery-style routes.
Workflow — deterministic async function with a typed state. Pick when you control the order of operations.
Graph — full LangGraph DSL with branching, looping, and conditional edges. Pick when the flow has structure the model shouldn't decide.
Chain — LangChain LCEL Runnable. Pick for simple linear pipelines.

A route's index.ts exports exactly one of these. You can mix shapes across routes inside the same project.

Tool auto-binding

Any TypeScript file in a route's tools/ directory is discovered for the agent. No manual tools: [...] config — Dawn wires them into the generated graph at build time.

src/app/(public)/research/tools/search.ts

export default async (input: { readonly query: string }) => {
  return { results: [`Result for: ${input.query}`] }
}

The exported parameter type is read by Dawn's compiler integration and turned into a JSON schema for the LLM. The agent calls tools.search({ query }) at runtime; the model decides when.

See Tools for the full input/output rules and the generated declarations.

Retry

Agent calls accept a retry config for transient route execution failures:

src/app/.../index.ts

export default agent({
  model: "gpt-5-mini",
  systemPrompt: "...",
  retry: { maxAttempts: 3, baseDelay: 250 },
})

See Retry for the backoff strategy, what is retried, and the streaming caveat. Dawn does not expose per-tool retry overrides today.

Built-in agent features

Agent routes can opt into higher-level behavior from files and descriptor fields.

Memory loads workspace/AGENTS.md into the prompt.
Planning adds plan.md, writeTodos, todos, and plan_update.
Skills adds skills/<name>/SKILL.md and readSkill.
Subagents adds child routes and task.
Reasoning Effort maps reasoning.effort to OpenAI-backed agent() routes.
Workspace activates workspace tools (listDir, readFile, writeFile, runBash) when a workspace/ directory exists.