Skip to main content
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

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

PropertyTypeDefaultDescription
namestringrequiredDisplay name for the agent
instructionsstringrequiredSystem prompt that defines behavior
descriptionstringoptionalHuman-readable description
modelstringanthropic/claude-sonnet-4.6LLM model identifier
vaultIdsstring[]all vaultsRestrict to specific vault IDs
enabledToolsstring[]all toolsAllowlist of tools
disabledToolsstring[]noneDenylist of tools
sandboxobjectdefaultCustom sandbox resources

​
Model selection

Override the default model per agent. Any model available through the LLM Gateway works: 
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: 
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: 
// 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: 
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.
// 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: 
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 all active agents in your organization: 
const { agents } = await client.agents.list()
Response
{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "Discovery Analyst",
      "description": null,
      "model": "anthropic/claude-sonnet-4.6",
      "isActive": true,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ]
}

​
Delete an agent

Endpoint
DELETE /agent/v1/agents/:id
Soft-deletes the agent and revokes its scoped API key. Existing run data is preserved. 
await client.agents.delete(agent.id)

​
Next: Execute runs

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