run()when you want to wait for completion and then read the final typed result.stream()when you want real-time output while the agent is running.
Configure an Agent
- Claude
- OpenCode
- Codex
Agent Options
You can pass provider-specific agent options with theoptions field on box.agent.run() and box.agent.stream().
ClaudeCode:maxTurns,maxBudgetUsd,effort,thinking,disallowedTools,agents,promptSuggestions,fallbackModel,systemPromptCodex:modelReasoningEffort,modelReasoningSummary,personality,webSearchOpenCode:reasoningEffort,textVerbosity,reasoningSummary,thinking
Quickstart
- Refactor Code
- Review Changes
- Structured Output
- Open a PR
- Process Documents
Codebase refactor
Use Claude Code when you want an agent to work through a larger code change with filesystem, shell, and git access.API
Prompt (required)
Type:stringSupported on:
box.agent.run() and box.agent.stream()
The task instruction sent to the agent.
Options
Type:AgentOptionsSupported on:
box.agent.run(), box.agent.stream(), and box.schedule.agent()
Provider-specific agent options forwarded to the underlying runner.
Timeout
Type:numberSupported on:
box.agent.run(), box.agent.stream(), and box.schedule.agent()Default: no execution timeout Execution timeout in milliseconds. When reached, the run is aborted.
onToolUse
Type:{ name: string; input: Record<string, unknown> }Supported on:
box.agent.run() and box.agent.stream()
Called whenever the agent invokes a tool (for example file, shell, or git tools).
responseSchema
Type:Zod SchemaSupported on:
box.agent.run()
Attach a Zod schema to get typed output.
maxRetries
Type:numberSupported on:
box.agent.run()Default:
0
Retry count to compensate temporary provider outages or similar transient errors. Retries use exponential backoff (1s, 2s, 4s, …) capped at 30s.
Webhook
Type:WebhookConfigSupported on:
box.agent.run()
Useful for fire-and-forget mode. The SDK returns immediately and sends the completion payload to your webhook URL when the run succeeds or fails.