Concepts
Agents
Create tool-loop agents, load instructions, and delegate to specialist agents.
Agents are server-only AI SDK agents. Tulip helpers accept the general AI SDK Agent interface, so
apps can use ToolLoopAgent directly or switch to another compatible agent later.
Create an agent
import "server-cli-only";
import { loadAgentInstructions } from "@tulip-systems/ai/agents/server";
import { isStepCount, ToolLoopAgent } from "ai";
import { openrouter } from "./providers";
export const assistantAgent = new ToolLoopAgent({
model: openrouter("openai/gpt-5-mini"),
instructions: loadAgentInstructions(import.meta.url),
stopWhen: isStepCount(10),
tools: {},
});Instructions
Use loadAgentInstructions(import.meta.url) when the instructions file lives next to the agent.
Recommended instruction structure:
- role and scope
- operating principles
- available tools and when to use them
- mutation safety rules
- clarification rules
- response style and answer patterns
Delegation
Use delegateToAgentTool() when one agent should call another specialist agent.
import { delegateToAgentTool } from "@tulip-systems/ai/agents/server";
import { resolveAgentTool } from "@tulip-systems/ai/tools/server";
import { z } from "zod";
import { salesAgent } from "../sales/agent";
export const delegateToSales = delegateToAgentTool({
name: "delegate_to_sales",
title: "Sales Agent",
description: "Delegate CRM and sales tasks to the sales specialist.",
agent: salesAgent,
inputSchema: z.object({
task: z.string().min(1),
}),
outputSchema: z.object({
summary: z.string(),
}),
});
export const delegateToSalesTool = resolveAgentTool(delegateToSales);Guidance
- Keep agents independent and directly addressable.
- Prefer specialist agents over one large catch-all prompt.
- Give each specialist read tools before write tools.
- Put mutation rules in specialist instructions, not only in the UI.
- Do not claim delegation happened unless the delegation tool was actually called.