Agents reference

Definition

draftship/agents/<kebab-name>.json:

{
  "name": "support",
  "description": "Answers questions about orders",
  "instructions": "You are the support assistant for Cozy Bakery. Be brief and warm. Never promise refunds; open a ticket instead.",
  "greeting": "Hi! Ask me anything about your orders.",
  "entities": [
    { "name": "Order", "access": "read" },
    { "name": "Ticket", "access": "write" }
  ]
}

Agents are synced after each successful build.

Tools

For each entity the agent gets list_<Entity> (MongoDB-style query, sort, limit up to 50). With "write" it also gets create_<Entity> and update_<Entity>. Every tool call runs with the conversation user's permissions, so security rules apply; errors such as a permission denial are returned to the agent, which explains them to the user. Up to 6 tool rounds run per message.

SDK

const agents = await ds.agents.list();                       // [{ name, description, greeting }]
const convo = await ds.agents.createConversation("support"); // { id, messages: [greeting] }
const reply = await ds.agents.sendMessage(convo.id, "Where is my last order?");
// reply: { role: "assistant", content, tool_calls?: [{ name, args }] }

const mine = await ds.agents.listConversations("support");   // signed-in user's chats
const full = await ds.agents.getConversation(convo.id);      // { ...convo, messages }

Conversations of signed-in users belong to them; anonymous conversations are reachable only by their id.

REST

Skills, memory and access

{
  "name": "support",
  "instructions": "…",
  "skills": ["refund-policy", "brand-voice"],
  "memory": { "enabled": true, "scope": "both", "instructions": "Remember each customer's preferred contact time." },
  "allow_anonymous": false
}

• skills: names of files in draftship/agent-skills/ (lowercase, dashes). Each file has YAML frontmatter with a description (up to 1,024 characters) and a body of instructions (up to 15,000). The agent gets a load_skill tool.
• memory.scope: "global", "user" or "both" (default). The agent gets save_memory and forget_memory tools. Per-person memory needs a known person: a signed-in user or a channel chat.
• allow_anonymous (default true): with false, createConversation and sendMessage return 401 for signed-out visitors.