Typescript sdk

Agents & Sub Agents

Copy page

Learn how to customize your Agents.

Agents and Sub Agents are the core building blocks of the Inkeep Agent framework.

An Agent is made up of one or more Sub Agents that can delegate or transfer control with each other, share context, use tools to respond to a user or complete a task.

Creating an Agent

An Agent is your top-level entity that you as a user interact with or can trigger programmatically.

An Agent is made up of sub-agents, like so:

// Agent-level prompt that gets added to all Sub Agents
const customerSupportAgent = agent({
  id: "support-agent",
  prompt: `You work for Acme Corp. Always be professional and helpful.
Follow company policies and escalate complex issues appropriately.`,
  subAgents: () => [supportAgent, escalationAgent],
});

The prompt is automatically put into context and added into each Sub Agent's system prompt. This provides consistent behavior and tone to all Sub Agents so they can act and respond as one cohesive unit to the end-user.

Creating a Sub Agent

Like an Agent, a Sub Agent needs an id, name, and clear prompt that define its behavior:

import { subAgent } from "@inkeep/agents-sdk";

const supportAgent = subAgent({
  id: "customer-support",
  name: "Customer Support Agent",
  prompt: `You are a customer support specialist. Always be helpful, professional, and empathetic.`,
});

Configuring Models

Configure models at either the Agent or Sub Agent level. Sub Agents inherit from their parent Agent when not explicitly set, and Agents inherit from project defaults.

The models object allows you to configure different models for different tasks, each with their own provider options:

models: {
  base: {
    model: "anthropic/claude-sonnet-4-5", // Primary model for text generation
    providerOptions: {
      temperature: 0.7,
      maxOutputTokens: 2048  // AI SDK v5 uses maxOutputTokens
    }
  },
  structuredOutput: {
    model: "openai/gpt-4.1-mini", // For structured JSON output only
    providerOptions: {
      temperature: 0.1,
      maxOutputTokens: 1024,
      experimental_reasoning: true  // Enable reasoning for better structured outputs
    }
  },
  summarizer: {
    model: "openai/gpt-4.1-nano", // For summaries and status updates
    providerOptions: {
      temperature: 0.5,
      maxOutputTokens: 1000
    }
  }
}

Model types

  • base: Primary model used for conversational text generation and reasoning
  • structuredOutput: Model used for structured JSON output only (falls back to base if not configured and nothing to inherit)
  • summarizer: Model used for summaries and status updates (falls back to base if not configured and nothing to inherit)

Supported providers

The framework supports a wide range of models from major AI providers:

  • Anthropic: For example anthropic/claude-opus-4-1, anthropic/claude-sonnet-4-5, anthropic/claude-sonnet-4, anthropic/claude-haiku-4-5, anthropic/claude-3-5-haiku-latest, and more
  • OpenAI: For example openai/gpt-5, openai/gpt-4.1-mini, openai/gpt-4.1-nano, and more
  • Google: For example google/gemini-2.5-pro, google/gemini-2.5-flash, google/gemini-2.5-flash-lite, and more
  • Additional providers via OpenRouter and gateway routing

Provider options

All models support providerOptions to customize their behavior. These include both generic parameters that work across all providers and provider-specific features like reasoning.

Generic parameters

These parameters work with all supported providers and go directly in providerOptions:

models: {
  base: {
    model: "anthropic/claude-sonnet-4-20250514",
    providerOptions: {
      maxOutputTokens: 4096,        // Maximum tokens to generate (AI SDK v5)
      temperature: 0.7,             // Controls randomness (0.0-1.0)
      topP: 0.95,                   // Nucleus sampling (0.0-1.0)
      topK: 40,                     // Top-k sampling (integer)
      frequencyPenalty: 0.0,        // Reduce repetition (-2.0 to 2.0)
      presencePenalty: 0.0,         // Encourage new topics (-2.0 to 2.0)
      stopSequences: ["\n\n"],     // Stop generation at sequences
      seed: 12345,                  // For deterministic output
      maxDuration: 30,              // Timeout in seconds (not milliseconds)
      maxRetries: 2,                // Maximum retry attempts
    }
  }
}

Provider-specific features

Advanced features like reasoning require provider-specific configuration wrapped in the provider name:

OpenAI reasoning
models: {
  base: {
    model: "openai/o3-mini",
    providerOptions: {
      maxOutputTokens: 4096,
      temperature: 0.7,
      openai: {
        reasoningEffort: 'medium'  // 'low' | 'medium' | 'high'
      }
    }
  }
}
Note
Note
openai/gpt-5, openai/gpt-5-mini, and openai/gpt-5-nano require a verified OpenAI organization. If your organization is not yet verified, these models will not be available.
Anthropic thinking
models: {
  base: {
    model: "anthropic/claude-3-7-sonnet-20250219",
    providerOptions: {
      maxOutputTokens: 4096,
      temperature: 0.7,
      anthropic: {
        thinking: {
          type: 'enabled',
          budgetTokens: 8000  // Tokens allocated for reasoning
        }
      }
    }
  }
}
Google Gemini thinking
models: {
  base: {
    model: "google/gemini-2-5-flash",
    providerOptions: {
      maxOutputTokens: 4096,
      temperature: 0.7,
      google: {
        thinkingConfig: {
          thinkingBudget: 8192,     // 0 disables thinking
          includeThoughts: true     // Return thought summary
        }
      }
    }
  }
}

Accessing other models

For models not directly supported, use these proxy providers:

  • OpenRouter: Access any model via openrouter/model-id format (e.g., openrouter/anthropic/claude-sonnet-4-0, openrouter/meta-llama/llama-3.1-405b)
  • Vercel AI SDK Gateway: Access models through your gateway via gateway/model-id format (e.g., gateway/anthropic/claude-sonnet-4-0)
models: {
  base: {
    model: "openrouter/anthropic/claude-sonnet-4-0",
    providerOptions: {
      temperature: 0.7,
      maxOutputTokens: 2048
    }
  },
  structuredOutput: {
    model: "gateway/openai/gpt-4.1-mini",
    providerOptions: {
      maxOutputTokens: 1024
    }
  }
}

Required API keys

You need the appropriate API key for your chosen provider to be defined in your environment variables:

  • ANTHROPIC_API_KEY for Anthropic models
  • OPENAI_API_KEY for OpenAI models
  • GOOGLE_GENERATIVE_AI_API_KEY for Google models
  • OPENROUTER_API_KEY for OpenRouter models
  • AI_GATEWAY_API_KEY for Vercel AI SDK Gateway models

Default models

When using the Inkeep CLI, the following defaults are applied based on your chosen provider:

Anthropic:

  • base: anthropic/claude-sonnet-4-5
  • structuredOutput: anthropic/claude-sonnet-4-5
  • summarizer: anthropic/claude-sonnet-4-5

OpenAI:

  • base: openai/gpt-4.1
  • structuredOutput: openai/gpt-4.1
  • summarizer: openai/gpt-4.1-nano

Google:

  • base: google/gemini-2.5-flash
  • structuredOutput: google/gemini-2.5-flash-lite
  • summarizer: google/gemini-2.5-flash-lite

Configuring StopWhen

Control stopping conditions to prevent infinite loops:

// Agent level - limit transfers between Sub Agents
agent({
  id: "support-agent",
  stopWhen: {
    transferCountIs: 5  // Max transfers in one conversation
  },
});

// Sub Agent level - limit generation steps
subAgent({
  id: "my-sub-agent",
  stopWhen: {
    stepCountIs: 20  // Max tool calls + LLM responses
  },
});

Configuration levels:

  • transferCountIs: Project or Agent level
  • stepCountIs: Project or Sub Agent level

Settings inherit from Project → Agent → Sub Agent.

Sub Agent overview

Beyond model configuration, Sub Agents define tools, structured outputs, and agent-to-agent relationships available to the Sub Agent.

ParameterTypeRequiredDescription
idstringYesStable Sub Agent identifier used for consistency and persistence
namestringYesHuman-readable name for the Sub Agent
promptstringYesDetailed behavior guidelines and system prompt for the Sub Agent
descriptionstringNoBrief description of the Sub Agent's purpose and capabilities
modelsobjectNoModel configuration for this Sub Agent. See Configuring Models
stopWhenobjectNoStop conditions (stepCountIs). See Configuring StopWhen
canUsefunctionNoReturns the list of MCP/tools the Sub Agent can use. See MCP Servers
dataComponentsarrayNoStructured output components for rich, interactive responses. See Data Components
artifactComponentsarrayNoComponents for handling tool or Sub Agent outputs. See Artifact Components
canTransferTofunctionNoFunction returning array of Sub Agents this Sub Agent can transfer to. See Transfer Relationships
canDelegateTofunctionNoFunction returning array of Sub Agents this Sub Agent can delegate to. See Delegation Relationships

Tools & MCPs

Enable tools for a Sub Agent to perform actions like looking up information or calling external APIs.

Tools can be:

  • MCP Servers - Connect to external services and APIs using the Model Context Protocol
  • Function Tools - Custom JavaScript functions that execute directly in secure sandboxes
import { subAgent, functionTool, mcpTool } from "@inkeep/agents-sdk";

const mySubAgent = subAgent({
  id: "my-agent-id",
  name: "My Sub Agent",
  prompt: "Detailed behavior guidelines",
  canUse: () => [
    functionTool({
      name: "get-current-time",
      description: "Get the current time",
      execute: async () => ({ time: new Date().toISOString() }),
    }),
    mcpTool({
      id: "inkeep-kb-rag",
      name: "Knowledge Base Search",
      description: "Search the company knowledge base.",
      serverUrl: "https://rag.inkeep.com/mcp",
    }),
  ],
});

Data components

Structured output components for rich, interactive responses. See Data Components.

import { z } from 'zod';

const mySubAgent = subAgent({
  id: "my-agent-id",
  name: "My Sub Agent",
  prompt: "Detailed behavior guidelines",
  dataComponents: [
    {
      id: "customer-info",
      name: "CustomerInfo",
      description: "Customer information display component",
      props: z.object({
        name: z.string().describe("Customer name"),
        email: z.string().describe("Customer email"),
        issue: z.string().describe("Customer issue description"),
      }),
    },
  ],
});

Artifact components

Components for handling tool or Sub Agent outputs. See Artifact Components.

import { z } from 'zod';
import { preview } from '@inkeep/agents-core';

const mySubAgent = subAgent({
  id: "my-agent-id",
  name: "My Sub Agent",
  prompt: "Detailed behavior guidelines",
  artifactComponents: [
    {
      id: "customer-info",
      name: "CustomerInfo",
      description: "Customer information display component",
      props: z.object({
        name: preview(z.string().describe("Customer name")),
        customer_info: z.string().describe("Customer information"),
      }),
    },
  ],
});

Sub Agent relationships

Define other Sub Agents this Sub Agent can transfer control to or delegate tasks to.

const mySubAgent = subAgent({
  // ...
  canTransferTo: () => [subAgent1],
  canDelegateTo: () => [subAgent2],
});

As a next step, see Sub Agent Relationships to learn how to design transfer and delegation relationships between Sub Agents.