# Agents reference

> Define agents, their data tools and the SDK for conversations.


## Definition

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

```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](/docs/developers/backend/security) 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

```ts
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

| Method | Path |
|---|---|
| GET | `/agents` |
| POST / GET | `/agents/<name>/conversations` |
| GET | `/conversations/<id>` |
| POST | `/conversations/<id>/messages` with `{ "content": "…" }` |

## Skills, memory and access

```json
{
  "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.