Skip to main content

​
The problem

You need AI to do real work — not just generate text, but search your vaults, run legal research, compile reports, and upload results. But LLM API calls are stateless: no file system, no tools, no persistence.

​
The solution

An agent is a reusable AI executor that runs in an isolated sandbox with the full Case.dev platform. Define it once with instructions, then create runs against it with different prompts. Each run spins up a dedicated sandbox with an AI coding agent and the casedev CLI pre-authenticated. The agent can search vaults, run legal research, process documents, write files, and upload results — autonomously.

​
Quick start

# 1. Create an agent
AGENT=$(curl -s -X POST https://api.case.dev/agent/v1/agents \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract Reviewer",
    "instructions": "You review contracts and flag risky clauses. Use the casedev CLI to search vaults and analyze documents."
  }')
AGENT_ID=$(echo $AGENT | jq -r '.id')

# 2. Create a run
RUN=$(curl -s -X POST https://api.case.dev/agent/v1/run \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"agentId\": \"$AGENT_ID\",
    \"prompt\": \"Review the NDA in vault vault_xxx for liability issues\"
  }")
RUN_ID=$(echo $RUN | jq -r '.id')

# 3. Execute the run
curl -s -X POST "https://api.case.dev/agent/v1/run/$RUN_ID/exec" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

# 4. Poll for results
curl -s "https://api.case.dev/agent/v1/run/$RUN_ID/status" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

# 5. Get full results when complete
curl -s "https://api.case.dev/agent/v1/run/$RUN_ID/details" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

​
Ad-hoc execution

Don’t need a persistent agent? Use the /execute endpoint to run an agent in a single call — no setup required: 
const result = await client.agents.execute({
  prompt: 'Search vault vault_abc for force majeure clauses and compile a summary.',
  vaultIds: ['vault_abc'],
  objectIds: ['obj_contract_001', 'obj_contract_002'],
})

// Poll for results using result.runId
const details = await client.agents.runs.getDetails(result.runId)
The /execute endpoint creates an ephemeral agent behind the scenes and immediately starts execution. You get back a runId to poll for status and results — same as the full flow.
ParameterTypeRequiredDescription
promptstringyesTask for the agent
instructionsstringnoCustom system prompt
modelstringnoLLM model (default: claude-sonnet)
vaultIdsstring[]noRestrict to specific vaults
objectIdsstring[]noScope to specific vault object IDs
guidancestringnoAdditional run context
enabledToolsstring[]noTool allowlist
disabledToolsstring[]noTool denylist
sandboxobjectnoCustom CPU/memory
Use /execute for one-off tasks. Use the full agent lifecycle (create → run → exec) when you need a persistent agent identity with fixed instructions that runs repeatedly.

​
How it works

Full lifecycle (persistent agents):
  1. Define an agent with a name, instructions, and optional model/vault restrictions
  2. Create a run with a prompt — this queues it without executing
  3. Execute the run — a durable workflow spins up a sandbox and starts the AI
  4. Poll or watch — check status or register a callback URL for completion notifications
  5. Get results — full output plus every tool call, token count, and execution logs
Ad-hoc execution:
  1. Call /execute with a prompt and optional config — agent is created and started automatically
  2. Poll or watch — same as above
  3. Get results — same as above
Interactive chat:
  1. Create a session — a sandbox starts and stays alive for multi-turn conversation
  2. Send messages — each message goes to the same running agent with full context
  3. Stream events — optional real-time SSE stream of agent activity
  4. End the session — sandbox is snapshotted and terminated, billing summary returned
Create and execute are separate steps by design. This lets you register a watcher callback before execution starts, or batch-create multiple runs and execute them on a schedule.

​
Next steps

Create & Configure

Define agents with instructions, model selection, and vault restrictions.

Execute Runs

Create runs, execute them, and understand the lifecycle.

Interactive Chat

Multi-turn agent sessions with real-time streaming.

Monitor & Analyze

Poll status, get full audit trails, and register webhooks.

Sandbox Environment

What’s inside the sandbox — tools, CLI, and capabilities.

Vaults

Store documents that agents can search and analyze.

Legal Research

Agents use this to search case law, statutes, and patents.

LLMs

The AI models that power agent reasoning.

OCR

Agents can trigger OCR on scanned documents.