stagewise

https://stagewise.io/docs
Admin
stagewise is a frontend coding agent that helps developers make changes to their codebases by...
Tokens:11,498
Snippets:48
Trust Score:8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start Stagewise CLI with npm

Source: https://stagewise.io/docs/index

This command installs and runs the latest version of the Stagewise CLI using npm. It's a simple way to get started with the Stagewise agent.

```bash
npx stagewise@latest
```

--------------------------------

### Start Stagewise CLI with pnpm

Source: https://stagewise.io/docs/index

This command installs and runs the latest version of the Stagewise CLI using pnpm. It's an alternative to npm for users who prefer pnpm.

```bash
pnpm dlx stagewise@latest
```

--------------------------------

### Clone repository and install dependencies

Source: https://stagewise.io/docs/developer-guides/test-stagewise-locally

Clones the stagewise repository, navigates into the project directory, installs dependencies using pnpm, and starts the development server.

```bash
git clone https://github.com/stagewise-io/stagewise && cd stagewise
pnpm i && pnpm dev
```

--------------------------------

### Install and Run Stagewise CLI

Source: https://stagewise.io/docs/upgrade-to-new-cli

Instructions on how to start the stagewise CLI without prior installation using npx or pnpm, and how to specify the development app's port.

```bash
npx stagewise@latest
# or
pnpm dlx stagewise@latest
```

--------------------------------

### Load Plugin from Local Path

Source: https://stagewise.io/docs/advanced-usage/install-plugins

Provides an example of how to load a plugin directly from a local file path within the stagewise.json configuration, useful for development purposes.

```json
{
  plugins: [
    {
      name: "custom-plugin",
      path: "/user/account/documents/my-super-plugin/dist"
    }
  ]
}
```

--------------------------------

### Testing Your Agent Steps

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

A step-by-step guide to testing your agent after development, including starting the agent, adding the toolbar, testing the connection, and sending test messages.

```Testing
1. **Start your agent** : Run your agent server
2. **Add toolbar to your app** : Follow the Quickstart guide to add the stagewise toolbar
3. **Test the connection** : The toolbar should detect your agent automatically
4. **Send test messages** : Try various prompts and element selections
```

--------------------------------

### Start Stagewise CLI

Source: https://stagewise.io/docs/advanced-usage/cli-deep-dive

Commands to start the Stagewise CLI in the current directory using npm or pnpm.

```bash
# If you're using npm as package manager
npx stagewise@latest
# If you're using pnpm as package manager
pnpm dlx stagewise@latest
```

--------------------------------

### Build and Link Plugin Locally with pnpm

Source: https://stagewise.io/docs/developer-guides/build-plugins

Commands to build a plugin and link it globally using pnpm for local development and testing within an example project.

```bash
pnpm build
pnpm link --global
pnpm link --global @stagewise/plugin-example
```

--------------------------------

### Load Plugin from Specific URL

Source: https://stagewise.io/docs/advanced-usage/install-plugins

Shows how to load a plugin from a dedicated remote endpoint by specifying both the plugin name and its URL in the stagewise.json configuration.

```json
{
  plugins: [
    {
      name: "custom-plugin",
      url: "http://my-cdn.example.com/my-custom-plugin"
    }
  ]
}
```

--------------------------------

### Scaffold a Plugin with CLI

Source: https://stagewise.io/docs/developer-guides/build-plugins

Use the create-stagewise-plugin command to quickly generate a new plugin project with the necessary configuration and example code.

```bash
npx create-stagewise-plugin
```

--------------------------------

### Load Plugin from esm.sh

Source: https://stagewise.io/docs/advanced-usage/install-plugins

Demonstrates how to configure the stagewise.json file to automatically load a plugin from esm.sh by simply listing its name.

```json
{
  plugins: [
    "custom-plugin" // This will be loaded from esm.sh
  ]
}
```

--------------------------------

### Install Stagewise Agent Interface

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Installs the necessary package for building custom agent integrations with Stagewise.

```bash
npm install @stagewise/agent-interface
```

--------------------------------

### Stagewise Agent Development Roadmap

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

An overview of the key stages and topics covered in developing a Stagewise agent, from basic setup to advanced features and best practices.

```Documentation Outline
1. Getting Started
   Installation
   Basic Agent Setup
2. Agent Interface Overview
   Core Capabilities
   Architecture
3. Managing Availability
4. Managing Agent State
5. Handling Messages
   Receiving User Messages
   Sending Agent Responses
   Working with Selected Elements
6. Tool Calling (Advanced)
   Setting Up Tool Support
   Calling Tools
7. Best Practices
   State Management
   Message Handling
   Resource Management
   Tool Integration
8. Testing Your Agent
   Debugging Tips
   Next Steps
```

--------------------------------

### Basic Stagewise Agent Server Setup

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Sets up a basic agent server that connects to the Stagewise toolbar. It configures the agent's name and description, handles user messages by echoing them back, and manages the agent's state.

```javascript
import { createAgentServer, AgentStateType } from '@stagewise/agent-interface/agent';

async function startAgent() {
  // Create the agent server - this handles WebSocket connections and HTTP endpoints
  const server = await createAgentServer();
  // Configure your agent
  server.setAgentName('My Custom Agent');
  server.setAgentDescription('A powerful AI assistant');
  // Set the agent as available
  server.interface.availability.set(true);
  // Listen for user messages
  server.interface.messaging.addUserMessageListener(async (message) => {
    // Set state to working
    server.interface.state.set(AgentStateType.WORKING);
    // Process the message and respond
    await processUserMessage(message, server.interface);
    // Set state to completed
    server.interface.state.set(AgentStateType.COMPLETED);
  });
  console.log(`Agent server running on port ${server.port}`);
}

async function processUserMessage(message, agentInterface) {
  // Extract the user's text
  const userText = message.contentItems
    .filter(item => item.type === 'text')
    .map(item => item.text)
    .join('\n');
  // Send a simple response
  agentInterface.messaging.set([
    {
      type: 'text',
      text: `You said: "${userText}". I'm a simple echo agent!`
    }
  ]);
}

startAgent().catch(console.error);
```

--------------------------------

### Build Custom Agent Integrations

Source: https://stagewise.io/docs/developer-guides/contribution-guidelines

This guide explains how to develop and integrate custom agents into the Stagewise platform. It covers the necessary steps and considerations for building these integrations.

```Markdown
# Contribution guidelines

If you want to make contributions to stagewise, follow our guidelines on what to work on and how to make pull requests.
We're just getting started and love contributions! Check out our CONTRIBUTING.md guide to get involved. For bugs and fresh ideas, please open an issue.

## Build custom Agent Integrations

This guide shows you how to build an integration for custom agents into stagewise.
```

--------------------------------

### Configure Dev Script in package.json

Source: https://stagewise.io/docs/advanced-usage/cli-deep-dive

Example of configuring the 'dev' script in package.json to wrap the dev command with the Stagewise CLI.

```json
{
  "scripts": {
    "dev": "npx stagewise@latest -- next dev"
  }
}
```

--------------------------------

### Example Stagewise Plugin Implementation

Source: https://stagewise.io/docs/developer-guides/build-plugins

TypeScript code for a Stagewise plugin, demonstrating its structure, display name, description, icon, action handler, and component usage with the `@stagewise/plugin-sdk`.

```typescript
//src/index.tsx
import type { ToolbarPlugin } from '@stagewise/plugin-sdk';
import { ExampleComponent } from './component';
const ExamplePlugin: ToolbarPlugin = {
  displayName: 'Example',
  description: 'Example Plugin',
  iconSvg: null,
  pluginName: 'example',
  onActionClick: () => <ExampleComponent />,
};
export default ExamplePlugin;

//src/component.tsx
import { Panel, PanelHeader, PanelContent, Button, useToolbar } from '@stagewise/plugin-sdk';
export const ExampleComponent = () => {
  const toolbar = useToolbar();
  return (
    <Panel>
      <PanelHeader title="Example Plugin" />
      <PanelContent>
        <Button onClick={() => toolbar.sendPrompt('Hello world!')}>
          Send "Hello world!" to Cursor!
        </Button>
      </PanelContent>
    </Panel>
  );
};
```

--------------------------------

### Monorepo Plugin Testing with workspace:*

Source: https://stagewise.io/docs/developer-guides/build-plugins

Details how to test a plugin within a monorepo by adding it as a workspace dependency in the test project's `package.json` and running `pnpm install`.

```json
{
  "dependencies": {
    "@stagewise/plugin-example": "workspace:*"
  }
}
```

--------------------------------

### Start Stagewise in a Different Workspace

Source: https://stagewise.io/docs/advanced-usage/cli-deep-dive

Commands to start the Stagewise CLI in a different working directory using the -w or --workspace argument with npm or pnpm.

```bash
# If you're using npm as package manager
npx stagewise@latest -w ~/projects/my-dev-app
# If you're using pnpm as package manager
pnpm dlx stagewise@latest -w ~/projects/my-dev-app
```

--------------------------------

### Unlink Plugin Locally with pnpm

Source: https://stagewise.io/docs/developer-guides/build-plugins

Commands to unlink a globally linked pnpm plugin from an example project and the global scope.

```bash
pnpm unlink --global @stagewise/plugin-example
pnpm unlink --global
```

--------------------------------

### Tool Calling Setup and Usage

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Details how to enable tool calling support, listen for available tools, and make requests to specific tools like web search, including error handling.

```javascript
// Enable tool calling support
server.interface.toolCalling?.setToolCallSupport(true);
// Listen for available tools
server.interface.toolCalling?.onToolListUpdate((tools) => {
  console.log('Available tools:', tools.map(t => t.toolName));
});

async function handleToolCallingExample(agentInterface) {
  // Get available tools
  const tools = agentInterface.toolCalling?.getAvailableTools() || [];
  // Find a specific tool
  const webSearchTool = tools.find(tool => tool.toolName === 'web_search');
  if (webSearchTool) {
    agentInterface.state.set(AgentStateType.CALLING_TOOL, 'Searching the web...');
    try {
      // Call the tool
      const result = await agentInterface.toolCalling?.requestToolCall(
        'web_search',
        { query: 'stagewise AI documentation', limit: 5 }
      );
      // Use the result
      agentInterface.messaging.addPart({
        type: 'text',
        text: `Search results: ${JSON.stringify(result?.result, null, 2)}`
      });
    } catch (error) {
      agentInterface.state.set(AgentStateType.FAILED, 'Tool call failed');
      agentInterface.messaging.addPart({
        type: 'text',
        text: `Error calling web search: ${error.message}`
      });
    }
  }
}
```

--------------------------------

### Wrap Dev Command with Stagewise CLI

Source: https://stagewise.io/docs/advanced-usage/cli-deep-dive

Examples of wrapping a development command with the Stagewise CLI using the double-dash syntax, including options, with npm or pnpm.

```bash
# Wrap your dev command
npx stagewise@latest -- pnpm dev
# You can still use stagewise options before the double-dash
npx stagewise@latest -p 3100 -a 3000 -- pnpm dev
```

--------------------------------

### Use External Agent with Stagewise CLI

Source: https://stagewise.io/docs/advanced-usage/cli-deep-dive

Commands to start the Stagewise CLI in bridge mode to use an external agent, using npm or pnpm.

```bash
# If you're using npm as package manager
npx stagewise@latest -b
# If you're using pnpm as package manager
pnpm dlx stagewise@latest -b
```

--------------------------------

### Stagewise IDE Extension Integration

Source: https://stagewise.io/docs/advanced-usage/use-different-agents

The Stagewise code editor extension allows the toolbar to connect with IDE-integrated coding agents. After installation, the toolbar prompts you to connect to an available agent, sends your prompts directly to the agent, and may require switching to the IDE to send the message due to API limitations.

```markdown
IDE chat integrations work like this:
  1. stagewise hosts it's toolbar on top of your dev app
  2. Upon opening the toolbar, you will be prompted to connect to one of the other available agents
  3. You send a message through the toolbar
  4. The toolbar will directly send the prompt to the specifc agent
```

--------------------------------

### Run Stagewise CLI in Bridge Mode

Source: https://stagewise.io/docs/advanced-usage/use-different-agents

This command starts the Stagewise CLI in bridge mode, disabling the default Stagewise agent and enabling the toolbar to search for other active agents on your machine. You can specify a different working directory using the -w flag.

```bash
# If your terminal's working directory is the root directory of the repository of your dev app
stagewise -b
# If you want stagewise to load in another directory than the current working directory
stagewise -b -w ~/repos/my-dev-app
```

--------------------------------

### Typical Plugin Project Structure

Source: https://stagewise.io/docs/developer-guides/build-plugins

Illustrates the standard directory and file layout for a stagewise plugin project, including the main entry point, UI components, and build configurations.

```json
my-plugin/
  src/
    index.tsx        # Main plugin entry point
    component.tsx    # Example UI component
  build.config.ts
  package.json
  tsconfig.json
  ...
```

--------------------------------

### Agent Message Handling Best Practices

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Recommendations for processing user context and delivering responses. Focuses on thoughtful context utilization, streaming for long operations, rich responses, and clear message management.

```Best Practices
Process user context thoughtfully (selected elements, page info, plugins)
Use streaming responses for long-running operations
Provide rich responses with appropriate markdown formatting
Clear messages when starting new conversations
```

--------------------------------

### Agent State Management Best Practices

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Guidelines for managing agent states to provide clear user feedback. Emphasizes using `COMPLETED` and `FAILED` states appropriately and maintaining them for a sufficient duration.

```Best Practices
Always set appropriate states to give users feedback
Stay in `COMPLETED` state for at least 1 second before returning to `IDLE`
Use descriptive state messages when helpful
Handle errors gracefully with `FAILED` state
```

--------------------------------

### Plugin UI Component with stagewise SDK

Source: https://stagewise.io/docs/developer-guides/build-plugins

Shows how to build plugin UI using `@stagewise/plugin-sdk` components like `Panel` and `Button`, and utilize the `useToolbar` hook to interact with the main application, such as sending prompts.

```typescript
// src/component.tsx
import { Panel, PanelHeader, PanelContent, Button, useToolbar } from '@stagewise/plugin-sdk';
export const ExampleComponent = () => {
  const toolbar = useToolbar();
  return (
    <Panel>
      <PanelHeader title="Example Plugin" />
      <PanelContent>
        <Button onClick={() => toolbar.sendPrompt('Hello world!')}>
          Send "Hello world!" to Cursor!
        </Button>
      </PanelContent>
    </Panel>
  );
};
```

--------------------------------

### Stagewise Configuration File (`stagewise.json`)

Source: https://stagewise.io/docs/advanced-usage/cli-deep-dive

Defines project-specific configuration for Stagewise, including ports, automatic plugin loading, and custom plugin definitions. Plugins can be specified by npm package name, local path, or remote URL.

```json
{
  "port": 3100,
  "appPort": 3000,
  "autoPlugins": true,
  "plugins": [
    "@stagewise/react-plugin",
    {
      "name": "my-custom-plugin",
      "path": "./local-plugin/"
    },
    {
      "name": "external-plugin",
      "url": "https://example.com/plugin.js"
    }
  ]
}
```

--------------------------------

### Minimal stagewise Plugin Implementation

Source: https://stagewise.io/docs/developer-guides/build-plugins

Demonstrates the basic structure of a stagewise plugin, implementing the `ToolbarPlugin` interface with essential fields like `displayName`, `pluginName`, and `onActionClick`.

```typescript
// src/index.tsx
import type { ToolbarPlugin } from '@stagewise/toolbar';
import { ExampleComponent } from './component';
const ExamplePlugin: ToolbarPlugin = {
  displayName: 'Example',
  description: 'Example Plugin',
  iconSvg: null, // You can provide a VNode for a custom SVG icon
  pluginName: 'example',
  onActionClick: () => <ExampleComponent />,
};
// It's super important to default-export the plugin!
export default ExamplePlugin;
```

--------------------------------

### Agent Tool Integration Best Practices

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Guidelines for integrating tools into agents, including conditional enabling, error handling, feedback, and documenting requirements.

```Best Practices
Only enable tool calling if your agent actually uses tools
Handle tool call timeouts and errors
Provide clear feedback when calling tools
Document your agent's tool requirements
```

--------------------------------

### Agent Debugging Tips

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Tips for debugging agent issues, including checking console logs, using browser dev tools, monitoring endpoints, and verifying state changes and tool integration.

```Debugging
Check the agent server console for connection logs
Use browser dev tools to inspect WebSocket messages
Monitor the `/stagewise/info` endpoint
Test availability state changes
Verify tool calling integration
```

--------------------------------

### Agent Resource Management Best Practices

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Best practices for managing agent resources, including listeners, WebSocket connections, error handling, and timeouts for tool calls.

```Best Practices
Always clean up listeners when shutting down
Handle WebSocket disconnections gracefully
Implement proper error handling and recovery
Use appropriate timeouts for tool calls
```

--------------------------------

### Configure App Port with Stagewise CLI

Source: https://stagewise.io/docs/advanced-usage/cli-deep-dive

Commands to configure the port on which the dev app runs using the -a or --app-port argument with npm or pnpm.

```bash
# If you're using npm as package manager
npx stagewise@latest -a 3002 # Set the port on which your dev app is hosted on
# If you're using pnpm as package manager
pnpm dlx stagewise@latest -a 3002
```

--------------------------------

### Receiving User Messages

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Shows how to listen for and process incoming user messages, extracting content, metadata like current URL and title, selected elements, and plugin content.

```javascript
server.interface.messaging.addUserMessageListener((message) => {
  // Message structure:
  console.log('User text:', message.contentItems);
  console.log('Current URL:', message.metadata.currentUrl);
  console.log('Page title:', message.metadata.currentTitle);
  console.log('Selected elements:', message.metadata.selectedElements);
  console.log('Plugin content:', message.pluginContent);
  console.log('User agent:', message.metadata.userAgent);
  console.log('Viewport:', message.metadata.viewportResolution);
});
```

--------------------------------

### Host Stagewise on a Specific Port

Source: https://stagewise.io/docs/advanced-usage/cli-deep-dive

Commands to host the Stagewise CLI on a specific port using the -p or --port argument with npm or pnpm.

```bash
# If you're using npm as package manager
npx stagewise@latest -p 3500 # Set the port you want to use
# If you're using pnpm as package manager
pnpm dlx stagewise@latest -p 3500
```

--------------------------------

### Sending Agent Responses

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Illustrates different methods for sending responses back to users, including plain text, text with images, and streaming responses by adding or updating message parts.

```javascript
// Send text response
agentInterface.messaging.set([
  {
    type: 'text',
    text: 'Here is my response to your question...'
  }
]);
// Send text with images
agentInterface.messaging.set([
  {
    type: 'text', 
    text: 'Here\'s the analysis you requested:'
  },
  {
    type: 'image',
    mimeType: 'image/png',
    data: base64ImageData, // Base64 encoded image
    replacing: false
  }
]);
// Stream responses by updating parts
agentInterface.messaging.addPart({
  type: 'text',
  text: 'Starting analysis...'
});
// Update existing part with more content
agentInterface.messaging.updatePart({
  type: 'text', 
  text: '\n\nProgress: 50% complete...'
}, 0, 'append');
```

--------------------------------

### Stagewise Authentication Commands

Source: https://stagewise.io/docs/advanced-usage/cli-deep-dive

Commands for managing authentication with the Stagewise service, including logging in, logging out, and checking status.

```APIDOC
stagewise auth login
  Initiates the OAuth authentication flow to log in to your stagewise account. Opens a browser window for authentication and stores the resulting tokens securely.

stagewise auth logout
  Clears all stored authentication tokens and logs you out of stagewise.

stagewise auth status
  Displays your current authentication status, including the email address of the logged-in user.
```

--------------------------------

### Stagewise Command-Line Arguments

Source: https://stagewise.io/docs/advanced-usage/cli-deep-dive

Overview of command-line arguments for configuring Stagewise, including port settings, workspace directory, and silent mode operation. These arguments can override settings in `stagewise.json`.

```bash
# Set the host port for the application and toolbar
stagewise --port 3000

# Set the port for the development application
stagewise --app-port 3000

# Set the workspace directory
stagewise --workspace /path/to/your/project

# Run in silent mode (no user input)
stagewise --silent
```

--------------------------------

### Stagewise CLI Options

Source: https://stagewise.io/docs/advanced-usage/cli-deep-dive

Provides options for controlling Stagewise CLI behavior, including verbose logging, authentication, and bridge mode.

```APIDOC
-v, --verbose
  Enable verbose logging to see detailed debug information about stagewise's operation, including configuration resolution, plugin loading, proxy request logging, and WebSocket connection details.

-t, --token
  Provide an authentication token for the stagewise agent directly via the command line instead of using stored credentials from `stagewise auth login`. Note: This option is incompatible with bridge mode (`-b`).

-b
  Enable bridge mode, which disables the built-in stagewise agent server. In this mode, stagewise only provides the toolbar and proxy functionality, allowing you to connect to external agents or use stagewise with other AI coding assistants. Note: Bridge mode is incompatible with the `--token` option.

--
  Use the double-dash to wrap your development command with stagewise, running both in a single terminal. Example: `npx stagewise@latest [options] -- <your-dev-command>`.
  This allows you to run `npm run dev`, `pnpm dev`, or any other command while stagewise operates in the background.
```

--------------------------------

### Managing Agent State

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Demonstrates how to set and update the agent's state to provide clear feedback to the user during different stages of processing. Includes available state types like IDLE, THINKING, WORKING, and COMPLETED.

```typescript
import { AgentStateType } from '@stagewise/agent-interface/agent';
// Available states:
// - IDLE: Ready for new requests
// - THINKING: Processing/analyzing 
// - WORKING: Actively executing task
// - CALLING_TOOL: Executing a tool call
// - WAITING_FOR_USER_RESPONSE: Needs user input
// - FAILED: Encountered an error
// - COMPLETED: Successfully finished task
async function handleUserMessage(message, agentInterface) {
  // Set state with optional description
  agentInterface.state.set(AgentStateType.THINKING, 'Analyzing your request...');
  // Simulate processing time
  await new Promise(resolve => setTimeout(resolve, 1000));
  agentInterface.state.set(AgentStateType.WORKING, 'Generating response...');
  // Do the actual work
  const response = await generateResponse(message);
  agentInterface.state.set(AgentStateType.COMPLETED, 'Response ready!');
  // Return to idle after a brief delay
  setTimeout(() => {
    agentInterface.state.set(AgentStateType.IDLE);
  }, 2000);
}
```

--------------------------------

### Stagewise Telemetry Commands

Source: https://stagewise.io/docs/advanced-usage/cli-deep-dive

Commands for managing telemetry settings, allowing users to control the level of diagnostic data sent to improve Stagewise.

```APIDOC
stagewise telemetry status
  Shows your current telemetry configuration and explains the available telemetry levels.

stagewise telemetry set <level>
  Set the telemetry level for stagewise CLI. Available levels:
    * off: Disable telemetry completely
    * anonymous: Enable telemetry with pseudonymized machine ID
    * full: Enable telemetry with actual user ID and email

Telemetry helps improve stagewise by tracking usage patterns and error reports without capturing sensitive code or request content. We only use usage data to understand issues and improve the performance of our service and will never sell telemetry data to third-party providers.
```

--------------------------------

### Run Stagewise CLI in Bridge Mode

Source: https://stagewise.io/docs/upgrade-to-new-cli

Command to launch the stagewise CLI in bridge mode, allowing continued use of other code editor agents.

```bash
npx stagewise@latest -b
```

--------------------------------

### Stagewise SSH Remote Session on WSL Limitation

Source: https://stagewise.io/docs/troubleshooting/common-issues

Explains that Stagewise must run on localhost and therefore does not work when accessed through an SSH remote session on WSL.

```APIDOC
stagewise:
  Access:
    - Localhost only
  
  Limitations:
    - Does not work in SSH remote sessions on WSL.
    - Requires direct localhost access.
```

--------------------------------

### Working with Selected Elements

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Provides a function to iterate through user-selected elements on a webpage, logging details such as node type, XPath, text content, attributes, bounding box, and parent information.

```javascript
function analyzeSelectedElements(selectedElements) {
  selectedElements.forEach((element, index) => {
    console.log(`Element ${index}:`);
    console.log('- Node type:', element.nodeType);
    console.log('- XPath:', element.xpath);
    console.log('- Text content:', element.textContent);
    console.log('- Attributes:', element.attributes);
    console.log('- Bounding box:', element.boundingClientRect);
    console.log('- Plugin annotations:', element.pluginInfo);
    // Check parent element if available
    if (element.parent) {
      console.log('- Parent:', element.parent.nodeType);
    }
  });
}
```

--------------------------------

### Stagewise Agent Interface Architecture

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Defines the structure of the AgentInterface, outlining its core capabilities for managing agent availability, state, messaging, tool calling, and cleanup.

```typescript
export type AgentInterface = {
  availability: { get, set };    // Agent availability status
  state: { get, set };          // Current agent state  
  messaging: {                  // Message sending/receiving
    get, set, addPart, updatePart, clear,
    addUserMessageListener, removeUserMessageListener
  };
  toolCalling?: {               // Optional tool calling support
    setToolCallSupport, getAvailableTools, requestToolCall
  };
  cleanup: { clearAllListeners }; // Resource cleanup
};
```

--------------------------------

### Manage Stagewise Agent Availability

Source: https://stagewise.io/docs/developer-guides/build-custom-agent-integrations

Demonstrates how to control the availability status of a Stagewise agent, including setting it to available, unavailable with specific error reasons, and checking its current availability.

```javascript
import { AgentAvailabilityError } from '@stagewise/agent-interface/agent';

// Set agent as available
agentInterface.availability.set(true);

// Set agent as unavailable with error reason
agentInterface.availability.set(
  false,
  AgentAvailabilityError.NO_AUTHENTICATION,
  'Please log in to use this agent'
);

// Check current availability
const availability = agentInterface.availability.get();

if (availability.isAvailable) {
  console.log('Agent is ready!');
} else {
  console.log('Agent unavailable:', availability.error, availability.errorMessage);
}

// Available error types:
// - NO_CONNECTION: Cannot connect to service
// - NO_AUTHENTICATION: Authentication required
// - INCOMPATIBLE_VERSION: Version mismatch
// - OTHER: Custom error condition
```
Tokens:
Raw