> ## Documentation Index
> Fetch the complete documentation index at: https://stagehand-sameelarif-stg-2602-update-cache-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# agent()

> Complete API reference for the agent() method

<CardGroup cols={1}>
  <Card title="Agent" icon="robot" href="/v2/basics/agent">
    See how to use agent() to create autonomous AI agents for multi-step browser workflows
  </Card>
</CardGroup>

### Agent Creation

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    // Create agent instance
    const agent = stagehand.agent(config: AgentConfig): AgentInstance
    ```

    **AgentConfig Interface:**

    ```typescript theme={null}
    interface AgentConfig {
      provider?: AgentProviderType;  // "openai" | "anthropic"
      model?: string;
      instructions?: string;
      options?: Record<string, unknown>;
      integrations?: (Client | string)[];
      tools?: ToolSet;
    }
    ```

    **AgentInstance Interface:**

    ```typescript theme={null}
    interface AgentInstance {
      execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Create agent instance
    agent = stagehand.agent(
        model: str,
        instructions: str = None,
        options: Dict[str, Any] = None
    )
    ```
  </Tab>
</Tabs>

### Agent Configuration

<ParamField path="provider" type="AgentProviderType" optional>
  AI provider for agent functionality.

  **Options:** `"anthropic"`, `"openai"`
</ParamField>

<ParamField path="model" type="string" optional>
  Specific model for agent execution.

  **Anthropic:** `"claude-sonnet-4-6"`, `"claude-sonnet-4-5-20250929"`

  **OpenAI:** `"computer-use-preview"`, `"gpt-4o"`
</ParamField>

<ParamField path="instructions" type="string" optional>
  System instructions defining agent behavior.
</ParamField>

<ParamField path="options" type="Record<string, unknown>" optional>
  Provider-specific configuration.

  **Common:** `apiKey`, `baseURL`, `organization`
</ParamField>

<ParamField path="integrations" type="(Client | string)[]" optional>
  MCP (Model Context Protocol) integrations for external tools and services.

  **Array of:** MCP server URLs (strings) or connected Client objects
</ParamField>

<ParamField path="tools" type="ToolSet" optional>
  Custom tool definitions to extend agent capabilities.

  **Format:** Object with tool name keys and tool definition values
</ParamField>

### Execute Method

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    // String instruction
    await agent.execute(instruction: string): Promise<AgentResult>

    // With options
    await agent.execute(options: AgentExecuteOptions): Promise<AgentResult>
    ```

    **AgentExecuteOptions Interface:**

    ```typescript theme={null}
    interface AgentExecuteOptions {
      instruction: string;
      maxSteps?: number;
      autoScreenshot?: boolean;
      waitBetweenActions?: number;
      context?: string;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # 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
    ```
  </Tab>
</Tabs>

### Execute Parameters

<ParamField path="instruction" type="string" required>
  High-level task description in natural language.
</ParamField>

<ParamField path="maxSteps" type="number" optional>
  Maximum number of actions the agent can take.

  **Default:** `20`
</ParamField>

<ParamField path="autoScreenshot" type="boolean" optional>
  Whether to take screenshots before each action.

  **Default:** `true`
</ParamField>

<ParamField path="waitBetweenActions" type="number" optional>
  Delay in milliseconds between actions.

  **Default:** `0`
</ParamField>

<ParamField path="context" type="string" optional>
  Additional context or constraints for the agent.
</ParamField>

### Response

**Returns:** `Promise<AgentResult>`

**AgentResult Interface:**

```typescript theme={null}
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;
  };
}
```

<Tabs>
  <Tab title="TypeScript">
    <ParamField path="success" type="boolean">
      Whether the task was completed successfully.
    </ParamField>

    <ParamField path="message" type="string">
      Description of the execution result and status.
    </ParamField>

    <ParamField path="actions" type="AgentAction[]">
      Array of individual actions taken during execution.
    </ParamField>

    <ParamField path="completed" type="boolean">
      Whether the agent believes the task is fully complete.
    </ParamField>

    <ParamField path="metadata" type="Record<string, unknown>" optional>
      Additional execution metadata and debugging information.
    </ParamField>

    <ParamField path="usage" type="object" optional>
      Token usage and performance metrics.
    </ParamField>
  </Tab>

  <Tab title="Python">
    <ParamField path="success" type="boolean">
      Whether the task was completed successfully.
    </ParamField>

    <ParamField path="message" type="string">
      Description of the execution result and status.
    </ParamField>

    <ParamField path="actions" type="AgentAction[]">
      Array of individual actions taken during execution.
    </ParamField>

    <ParamField path="completed" type="boolean">
      Whether the agent believes the task is fully complete.
    </ParamField>
  </Tab>
</Tabs>

### Example Response

```json theme={null}
{
  "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
  }
}
```