Execute

The execute endpoint is the fastest way to run an agent task without creating a persistent agent or managing a queued run lifecycle. By default, execute uses the lighter linc-based runtime in a Vercel Sandbox and returns the final result in the same HTTP response.

Endpoint

POST /agent/v1/execute

Default behavior

The default execute flow is synchronous:

create an ephemeral agent and run record
boot a Vercel Sandbox with linc and the casedev CLI
execute the task immediately
return the final output, logs, and runtime metadata in the same response

Request shape

Request body

{
  "prompt": "Review the NDA in vault vault_xxx and return the top 5 issues.",
  "instructions": "You are a contract reviewer. Focus on indemnity, liability, term, and confidentiality.",
  "model": "anthropic/claude-sonnet-4.6",
  "vaultIds": ["vault_xxx"],
  "objectIds": ["obj_123"],
  "guidance": "Keep the answer under 10 bullets.",
  "enabledTools": ["vault.search", "legal-research.search"],
  "sandbox": {
    "cpu": 2,
    "memoryMiB": 4096
  }
}

Fields

Field	Type	Required	Description
`prompt`	string	yes	The task to execute
`instructions`	string	no	System instructions for the ephemeral agent
`model`	string	no	Model override for this execution
`vaultIds`	string[]	no	Limit the execution to specific vaults
`objectIds`	string[]	no	Limit the execution to specific vault objects
`guidance`	string	no	Extra run-specific guidance
`enabledTools`	string[]	no	Allowlist of tools
`disabledTools`	string[]	no	Denylist of tools
`sandbox`	object	no	Runtime sizing hints such as CPU and memory
`agentRuntime`	boolean	no	Set to `true` to opt into the legacy Daytona-backed agent runtime

enabledTools and disabledTools are mutually exclusive.

Response shape

The default response is synchronous and includes the final result directly.

Response body

{
  "runId": "run_abc123",
  "agentId": "agent_abc123",
  "status": "completed",
  "provider": "vercel",
  "runtimeId": "sandbox_abc123",
  "runtimeState": "ended",
  "output": "Top issues: 1. Broad indemnity ...",
  "error": null,
  "logs": {
    "runner": "sandbox bootstrap logs...",
    "linc": "agent execution logs..."
  },
  "usage": {
    "model": "anthropic/claude-sonnet-4.6",
    "inputTokens": 4200,
    "outputTokens": 1800,
    "toolCalls": 4,
    "durationMs": 18743
  }
}

Legacy agent runtime

If you need the older Daytona-backed runtime behavior, set agentRuntime: true.

Legacy request body

{
  "prompt": "Review the NDA in vault vault_xxx and return the top 5 issues.",
  "agentRuntime": true
}

That legacy mode returns a queued/running-style response instead of the final output:

Legacy response body

{
  "runId": "run_abc123",
  "agentId": "agent_abc123",
  "status": "running",
  "provider": "daytona",
  "runtimeState": "running",
  "message": "Run started. Poll /agent/v1/run/:id/status for progress, or GET /agent/v1/run/:id/details for results."
}

When to use execute

You want the smallest possible integration surface.
You do not need a persistent chat session.
You prefer a blocking request that returns the final answer directly.
You want the lighter linc-based runtime by default.

When to use runs instead

You need queued execution and polling semantics.
You need separate create-run and exec-run steps.
You want the broader run lifecycle APIs.

See Execute Runs for the full run lifecycle.

Get Started

Platform

Resources

Default behavior

Request shape

Fields

Response shape

Legacy agent runtime

When to use execute

When to use runs instead

​Default behavior

​Request shape

​Fields

​Response shape

​Legacy agent runtime

​When to use execute

​When to use runs instead

Default behavior

Request shape

Fields

Response shape

Legacy agent runtime

When to use execute

When to use runs instead