Agent Creation
// Create agent instance
const agent = stagehand.agent(config: AgentConfig): AgentInstance
interface AgentConfig {
provider?: AgentProviderType; // "openai" | "anthropic"
model?: string;
instructions?: string;
options?: Record<string, unknown>;
integrations?: (Client | string)[];
tools?: ToolSet;
}
interface AgentInstance {
execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
}
# Create agent instance
agent = stagehand.agent(
model: str,
instructions: str = None,
options: Dict[str, Any] = None
)
Agent Configuration
AI provider for agent functionality.Options: "anthropic", "openai"
Specific model for agent execution.Anthropic: "claude-sonnet-4-20250514", "claude-3-5-sonnet-20241022"OpenAI: "computer-use-preview", "gpt-4o"
System instructions defining agent behavior.
Provider-specific configuration.Common: apiKey, baseURL, organization
MCP (Model Context Protocol) integrations for external tools and services.Array of: MCP server URLs (strings) or connected Client objects
Custom tool definitions to extend agent capabilities.Format: Object with tool name keys and tool definition values
Execute Method
// String instruction
await agent.execute(instruction: string): Promise<AgentResult>
// With options
await agent.execute(options: AgentExecuteOptions): Promise<AgentResult>
interface AgentExecuteOptions {
instruction: string;
maxSteps?: number;
autoScreenshot?: boolean;
waitBetweenActions?: number;
context?: string;
}
# String instruction
await agent.execute(instruction: str) -> AgentResult
# With options dictionary
await agent.execute({
"instruction": str,
"max_steps": int = 20,
"auto_screenshot": bool = True,
"wait_between_actions": int = 0,
"context": str = None
}) -> AgentResult
Execute Parameters
High-level task description in natural language.
Maximum number of actions the agent can take.Default: 20
Whether to take screenshots before each action.Default: true
Delay in milliseconds between actions.Default: 0
Additional context or constraints for the agent.
Response
Returns: Promise<AgentResult>
AgentResult Interface:
interface AgentResult {
success: boolean;
message: string;
actions: AgentAction[];
completed: boolean;
metadata?: Record<string, unknown>;
usage?: {
input_tokens: number;
output_tokens: number;
reasoning_tokens?: number;
cached_input_tokens?: number;
inference_time_ms: number;
};
}
Whether the task was completed successfully.
Description of the execution result and status.
Array of individual actions taken during execution.
Whether the agent believes the task is fully complete.
Additional execution metadata and debugging information.
Token usage and performance metrics.
Whether the task was completed successfully.
Description of the execution result and status.
Array of individual actions taken during execution.
Whether the agent believes the task is fully complete.
Example Response
{
"success": true,
"message": "Task completed successfully",
"actions": [
{
"action": "click",
"selector": "button.primary",
"text": "Submit"
}
],
"completed": true,
"metadata": {
"execution_time": 1000
},
"usage": {
"input_tokens": 100,
"output_tokens": 50,
"reasoning_tokens": 12,
"cached_input_tokens": 0,
"inference_time_ms": 100
}
}
