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

FieldTypeRequiredDescription
promptstringyesThe task to execute
instructionsstringnoSystem instructions for the ephemeral agent
modelstringnoModel override for this execution
vaultIdsstring[]noLimit the execution to specific vaults
objectIdsstring[]noLimit the execution to specific vault objects
guidancestringnoExtra run-specific guidance
enabledToolsstring[]noAllowlist of tools
disabledToolsstring[]noDenylist of tools
sandboxobjectnoRuntime sizing hints such as CPU and memory
agentRuntimebooleannoSet 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.