Agents & Sub 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

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.

Parameter	Type	Required	Description
`id`	string	Yes	Stable Sub Agent identifier used for consistency and persistence
`name`	string	Yes	Human-readable name for the Sub Agent
`prompt`	string	Yes	Detailed behavior guidelines and system prompt for the Sub Agent
`description`	string	No	Brief description of the Sub Agent's purpose and capabilities
`models`	object	No	Model configuration for this Sub Agent. See Configuring Models
`stopWhen`	object	No	Stop conditions (`stepCountIs`). See Configuring StopWhen
`canUse`	function	No	Returns the list of MCP/tools the Sub Agent can use. See MCP Servers
`dataComponents`	array	No	Structured output components for rich, interactive responses. See Data Components
`artifactComponents`	array	No	Components for handling tool or Sub Agent outputs. See Artifact Components
`canTransferTo`	function	No	Function returning array of Sub Agents this Sub Agent can transfer to. See Transfer Relationships
`canDelegateTo`	function	No	Function 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.

On this page