Create & Configure

Define agents with instructions, model selection, and tool restrictions

An agent is a reusable definition — a name, instructions, and optional configuration. Create it once, then run it many times with different prompts.

Create an agent

Endpoint

POST /agent/v1/agents

TypeScript

const agent = await client.agents.create({
  name: 'Discovery Analyst',
  instructions: `You are a legal discovery analyst. When given a vault ID and topic:
1. Search the vault for relevant documents
2. Analyze key passages
3. Compile a summary memo with citations
Use the casedev CLI for all vault and search operations.`,
})

console.log(agent.id) // agent_xxx

Response

{
  "id": "agent_abc123xyz",
  "name": "Discovery Analyst",
  "instructions": "You are a legal discovery analyst...",
  "model": "anthropic/claude-sonnet-4.6",
  "vaultIds": null,
  "enabledTools": null,
  "disabledTools": null,
  "sandbox": null,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Configuration options

Property	Type	Default	Description
name	string	required	Display name for the agent
instructions	string	required	System prompt that defines behavior
description	string	optional	Human-readable description
model	string	anthropic/claude-sonnet-4.6	LLM model identifier
vaultIds	string[]	all vaults	Restrict to specific vault IDs
enabledTools	string[]	all tools	Allowlist of tools
disabledTools	string[]	none	Denylist of tools
sandbox	object	default	Custom sandbox resources

Object-level scoping (objectIds) is set per-run, not per-agent. This allows the same agent to work with different document sets on each execution. See Execute Runs → Object ID scoping.

Model selection

Override the default model per agent. Any model available through the LLM Gateway works:

TypeScript

const agent = await client.agents.create({
  name: 'Fast Summarizer',
  instructions: 'Summarize documents concisely.',
  model: 'anthropic/claude-haiku-3.5',
})

Vault restrictions

Lock an agent to specific vaults so it can only access authorized data:

TypeScript

const agent = await client.agents.create({
  name: 'Case 2024-1234 Analyst',
  instructions: 'Analyze documents in your assigned vault.',
  vaultIds: ['vault_abc123', 'vault_def456'],
})

Tool restrictions

Control which tools the agent can use. Either allowlist specific tools, or denylist ones you want to block:

TypeScript

// Only allow vault search and legal research
const agent = await client.agents.create({
  name: 'Research Only',
  instructions: 'Research legal questions. Do not modify any files.',
  enabledTools: ['bash', 'read', 'grep', 'glob'],
  disabledTools: ['write', 'edit'],
})

Sandbox resources

Customize CPU and memory for compute-intensive tasks:

TypeScript

const agent = await client.agents.create({
  name: 'Heavy Processor',
  instructions: 'Process large document sets.',
  sandbox: { cpu: 4, memoryMiB: 4096 },
})

Default sandbox: 2 CPU, 2048 MiB memory. The sandbox has a 30-minute execution timeout.

Writing good instructions

The instructions field is the agent’s system prompt. It defines personality, capabilities, and constraints. Tips:

1. Be specific about tools. Tell the agent to use casedev CLI for vault operations, legal search, etc.
2. Define the output format. “Write a markdown report” or “Return a JSON summary.”
3. Set boundaries. “Only search the assigned vault” or “Do not modify existing documents.”
4. Include workflow steps. Numbered steps help the agent stay on track for complex tasks.

TypeScript

// Good: specific, structured, actionable
const agent = await client.agents.create({
  name: 'Deposition Summarizer',
  instructions: `You summarize depositions. For each deposition:
1. Use 'casedev vault search' to find the document
2. Read the full transcript
3. Identify key admissions, contradictions, and timeline facts
4. Write a 1-page summary in markdown
5. Upload the summary to the same vault using 'casedev vault upload'
6. Return the vault object ID and a presigned download URL

Always cite page numbers. Use formal legal writing style.`,
})

Update an agent

Endpoint

PATCH /agent/v1/agents/:id

Partial updates — only provided fields change:

TypeScript

const updated = await client.agents.update(agent.id, {
  instructions: 'Updated instructions...',
  model: 'anthropic/claude-sonnet-4.6',
})

List agents

Endpoint

GET /agent/v1/agents

Returns active agents in your organization with cursor-based pagination.

TypeScript

const { agents, hasMore, nextCursor } = await client.agents.list({ limit: 20 })

// Fetch next page
if (hasMore) {
  const page2 = await client.agents.list({ cursor: nextCursor })
}

Query parameters

Parameter	Type	Required	Description
limit	integer	no	Max results per page (1-250, default 50)
cursor	string	no	Agent ID from a previous page’s nextCursor

Response

{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "Discovery Analyst",
      "description": null,
      "model": "anthropic/claude-sonnet-4.6",
      "isActive": true,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Delete an agent

Endpoint

DELETE /agent/v1/agents/:id

Soft-deletes the agent and revokes its scoped API key. Existing run data is preserved.

TypeScript

await client.agents.delete(agent.id)

Next: Execute runs

Now that you have an agent, learn how to create and execute runs →