What is Agent Maps and how is it different from browser automation tools?

Agent Maps is a semantic search API that returns pre-mapped, step-by-step browser automation instructions. Unlike tools like Playwright or Puppeteer that require you to write selectors yourself, Agent Maps provides exact ARIA selectors and action sequences captured from real browser traces. Think of it as Google Maps for AI agents — you describe where you want to go, and we give you turn-by-turn directions.

Do I need an API key to use Agent Maps?

No, not during the early preview. The API is completely free and requires no authentication. Just send a POST request to the /search endpoint. We plan to introduce API keys and usage tiers in the future, but the free tier will always remain available.

Which websites are currently supported?

We currently have mapped actions for LinkedIn (messaging, posting, connection requests, following companies, commenting). We're actively adding support for Reddit, X (Twitter), Facebook, Telegram Web, and more.

How do I handle non-deterministic steps?

Non-deterministic steps (marked with deterministic: false) require your agent to observe the page state before acting. For example, when selecting from search results, take a page snapshot first to see available options, then choose the correct element.

What does the similarity score mean?

The similarity score (0.0–1.0) indicates how closely a mapped task matches your search query. Scores above 0.9 are excellent matches, 0.7–0.9 are good, and 0.5–0.7 are moderate. You can control the minimum threshold with the match_threshold parameter.

Can I use Agent Maps with any browser automation framework?

Yes. Agent Maps is framework-agnostic — it returns ARIA selectors and action types that work with any automation tool: Playwright, Puppeteer, Selenium, agent-browser, or custom solutions.

What happens if a website updates its UI?

We continuously re-map websites to keep selectors up to date. If you encounter a broken selector, try using response_format: "full" which includes additional selector data as fallbacks.

Is the API stable? Will endpoints change?

Agent Maps is currently in early preview. While we aim to minimize breaking changes, endpoints, response formats, and behavior may change without notice during this phase.

How are the browser automation steps generated?

Steps are captured from real browser interactions using Playwright traces, not hallucinated by an LLM. Each task is recorded by actually performing the workflow in a live browser, then parsed and enriched with metadata.

Can I contribute or request new website mappings?

Absolutely. We're actively expanding our coverage. If you need a specific website or workflow mapped, reach out and we'll prioritize it.

Early Previewv1.0.0

API Documentation

Name: Agent Maps
Rating: 5 (100 reviews)
Author: Agent Maps

Semantic search API for browser automation tasks. Query with natural language, get back step-by-step instructions with exact selectors your agent can execute.

Early Preview — API is subject to change

This API is in early preview. Endpoints, response formats, and behavior may change without notice. We currently have a limited set of mapped actions. No authentication or rate limits are enforced yet.

Quick Start

Search for any browser task in one API call.

Try it now

curl -s -X POST https://api.agentmaps.dev/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "send a message on LinkedIn",
    "website": "linkedin.com",
    "response_format": "normal"
  }' | jq

No API key required. No setup. Just send a POST request and get back executable steps.

Base URL

BASE_URL = https://api.agentmaps.dev

API Reference

GET/

Health check endpoint. Verify the API is running.

Response — 200 OK

{
  "service": "AgentMap API",
  "version": "1.0.0",
  "status": "running"
}

POST/searchMain Endpoint

Semantic search for browser automation tasks. Send a natural language query and get back step-by-step instructions with selectors, action types, and variable templates.

Request Body

Content-Type: application/json

Parameter	Type	Required	Default	Description
`query`	`string`	Required	—	Natural language search query. E.g. `"send a message on LinkedIn"`
`website`	`string`	Optional	null	Filter results by website domain. E.g. `"linkedin.com"`
`response_format`	`string`	Optional	"normal"	Detail level: `"text"`, `"normal"`, or `"full"`
`match_count`	`number`	Optional	3	Maximum number of results to return (1–10 recommended)
`match_threshold`	`number`	Optional	0.7	Cosine similarity threshold (0.0–1.0). Lower values return more results.

Response

200 OK — Search Results

{
  "query": "send a message on LinkedIn",
  "website": "linkedin.com",
  "response_format": "normal",
  "results": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "website": "linkedin.com",
      "title": "Send Direct Message to LinkedIn Connection",
      "similarity": 0.8542,
      "total_steps": 6,
      "steps": [
        {
          "step": 1,
          "action": "goto",
          "description": "Navigate to https://linkedin.com/messaging",
          "deterministic": true,
          "selector": {}
        },
        {
          "step": 2,
          "action": "click",
          "description": "Click \"Compose a new message\"",
          "deterministic": true,
          "selector": {
            "aria": "role=button name=\"Compose a new message\""
          }
        },
        {
          "step": 3,
          "action": "fill",
          "description": "Fill \"Enter message recipients\" with {recipient_name}",
          "deterministic": true,
          "selector": {
            "aria": "role=combobox name=\"Enter message recipients\""
          }
        }
      ],
      "variables": [
        {
          "step": 3,
          "field": "Enter message recipients",
          "template": "{recipient_name}",
          "example": "john_doe"
        },
        {
          "step": 5,
          "field": "Write a message",
          "template": "{message_content}",
          "example": "Hello!"
        }
      ]
    }
  ],
  "count": 1
}

Error Responses

400Bad Request

{ "error": "Query is required" }

404No Results

{ "results": [], "suggestion": "..." }

Response Detail Levels

"text"— Minimal, for display only

text format

{
  "step": 2,
  "description": "Click \"Compose a new message\"",
  "deterministic": true
}

"normal"Recommended— Includes action + ARIA selector

normal format (default)

{
  "step": 2,
  "action": "click",
  "description": "Click \"Compose a new message\"",
  "deterministic": true,
  "selector": {
    "aria": "role=button name=\"Compose a new message\""
  }
}

"full"— Complete trace data for debugging

full format

{
  "step": 2,
  "action": "click",
  "description": "Click \"Compose a new message\"",
  "deterministic": true,
  "selector": {
    "raw": "internal:role=button[name=\"Compose a new message\"s]",
    "aria": "role=button name=\"Compose a new message\"",
    "name": "Compose a new message",
    "role": "button"
  },
  "element": {
    "tag": "button",
    "class": "msg-form__send-btn"
  },
  "url_before": "https://www.linkedin.com/messaging/",
  "url_after": "https://www.linkedin.com/messaging/"
}

Usage Guide

How It Works

Search

Query the API with natural language describing the task you want to automate

Parse

Read the steps, identify deterministic vs non-deterministic, note required variables

Execute

Run each step using the action type and ARIA selector from the response

Verify

Confirm the automation succeeded by checking the page state after execution

Deterministic vs Non-Deterministic Steps

Each step in the response has a deterministic flag that tells your agent how to handle it.

deterministic: true

Predictable steps. Execute directly using the ARIA selector from the API — no snapshot needed.

Examples: navigating to a URL, clicking a specific button, filling a named input field, pressing a key.

deterministic: false

Context-dependent steps. Take a snapshot first to see available options, then pick the right element.

Examples: selecting from search results, clicking dynamic content, choosing from a list of options.

Variables

Steps that require user input use template variables like {recipient_name}. The variables array in the response tells you which steps need input and provides example values.

Variables in response

"variables": [
  {
    "step": 3,
    "field": "Enter message recipients",
    "template": "{recipient_name}",
    "example": "john_doe"
  },
  {
    "step": 5,
    "field": "Write a message",
    "template": "{message_content}",
    "example": "Hello!"
  }
]

Replace template variables with actual values when executing the corresponding step. The example field shows what kind of value is expected.

Action Types

Each step has an action field. Here's how each maps to browser automation commands:

Action	Description	ARIA Selector
`goto`	Navigate to a URL	Not used — use the URL from description
`click`	Click an element	role=button name="Submit"
`fill`	Type into an input field	role=textbox name="Email"
`select`	Choose from a dropdown	role=combobox name="State"
`keyboardPress`	Press a keyboard key	Not used — key from description
`scroll`	Scroll the page	Not used — direction from description

Full Examples

Send a LinkedIn Message

Step 1 — Search for the task

curl -s -X POST https://api.agentmaps.dev/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "send linkedin message",
    "website": "linkedin.com",
    "response_format": "normal",
    "match_threshold": 0.5
  }' | jq

Then execute each step from the response one at a time with your automation tool (e.g. Playwright, Puppeteer, agent-browser):

Step 2 — Execute steps sequentially

# Step 1: Navigate (deterministic — use URL directly)
agent-browser open https://linkedin.com/messaging

# Step 2: Click "Compose" (deterministic — use ARIA selector)
agent-browser find role button click --name "Compose a new message"

# Step 3: Fill recipient (deterministic — use ARIA selector + variable)
agent-browser find role combobox fill "John Doe" --name "Enter message recipients"

# Step 4: Select from results (NON-DETERMINISTIC — snapshot first!)
agent-browser snapshot
# Output: - option "John Doe • 1st" [ref=e1]
#         - option "John Smith • 2nd" [ref=e2]
agent-browser click @e1

# Step 5: Fill message (deterministic — use ARIA selector + variable)
agent-browser find role textbox fill "Hey, wanted to connect!" --name "Write a message"

# Step 6: Click Send (deterministic)
agent-browser find role button click --name "Send"

Create a LinkedIn Post

Search + Execute

# Search
curl -s -X POST https://api.agentmaps.dev/search \
  -H "Content-Type: application/json" \
  -d '{"query": "create post linkedin", "website": "linkedin.com"}' | jq

# Execute (all steps deterministic)
agent-browser open https://linkedin.com/feed
agent-browser find role link click --name "Start a post"
agent-browser find role textbox fill "Excited about our new launch!" --name "Text editor for creating content"
agent-browser find role button click --name "Post"

Python Integration

search.py

import requests

response = requests.post(
    "https://api.agentmaps.dev/search",
    json={
        "query": "follow a company on LinkedIn",
        "website": "linkedin.com",
        "response_format": "full",
        "match_threshold": 0.5
    }
)

data = response.json()
for result in data["results"]:
    print(f"Task: {result['title']} (similarity: {result['similarity']:.2f})")
    for step in result["steps"]:
        print(f"  Step {step['step']}: [{step['action']}] {step['description']}")
        if step.get("selector", {}).get("aria"):
            print(f"    Selector: {step['selector']['aria']}")
    for var in result.get("variables", []):
        print(f"  Variable: {var['template']} (e.g. \"{var['example']}\")")

Similarity Scores

Results include a similarity score (0.0–1.0) indicating how well the task matches your query.

0.9 – 1.0

Excellent

0.7 – 0.9

Good

0.5 – 0.7

Moderate

< 0.5

Weak

Tip: Use match_threshold: 0.5 instead of the default 0.7 for broader results.

Supported Websites

We currently have a limited set of mapped actions. More websites and tasks are being added regularly.

Website	Status	Available Tasks
linkedin.com	Live	Send messages, create posts, send connection requests, follow companies, scroll feed & comment
reddit.com	Coming Soon	Vote on posts, comment, join communities, create posts
x.com	Coming Soon	Post tweets, like, retweet, follow users, send DMs
facebook.com	Coming Soon	Create posts, comment, react, send messages, join groups
web.telegram.org	Coming Soon	Send messages, create groups, share media, manage channels

Best Practices

Execute steps one at a time

Do NOT batch all commands into a script. Execute one step, observe the result, then proceed. This is critical for handling dynamic page changes.

Use ARIA selectors for deterministic steps

Trust the selectors from the API response. They are captured from real browser traces and map directly to elements on the page.

Snapshot only for non-deterministic steps

When a step is marked deterministic: false, take a page snapshot first to see available options, then choose the right element by reference.

Use lower thresholds for broader search

Start with match_threshold: 0.5 instead of the default 0.7 to find more potential matches. You can always filter by similarity score after.

Replace variables with real values

Check the variables array in the response. Replace template placeholders like {recipient_name} with actual values before executing fill/type steps.

User must be logged in

The API returns steps that assume the user is already authenticated on the target website. Ensure the browser session is logged in before executing.

Troubleshooting

No results found?

Lower match_threshold to 0.4 or 0.3
Try rephrasing your query (e.g. "message someone on linkedin" instead of "DM on linkedin")
Remove the website filter to search across all sites

Element not found during execution?

Website UI may have changed — take a snapshot to see current page state
Try using response_format: "full" for more selector options
Ensure the user is logged in and on the correct page

Website not mapped?

We currently support a limited set of websites. The API will return a helpful message indicating which websites are available. More are being added — check back soon.

Claude Agent Skill

Drop a single file into your project and give any Claude-powered agent the ability to search Agent Maps and execute browser automations — no extra code needed.

What is a Skill file?

A SKILL.md file teaches Claude agents how to use Agent Maps end-to-end. It contains the full API reference, ARIA selector mapping, step-by-step execution patterns for deterministic and non-deterministic steps, variable handling, and real-world examples (send LinkedIn message, create post, follow company). Place it in your project root and Claude will automatically pick it up.

How to install

Download SKILL.md using the button below
Place it in your project root (alongside your package.json)
Your Claude agent will now know how to search Agent Maps and execute browser tasks

Works with Claude Code, Claude Desktop (via MCP), and any agent using the Claude API with tool use.

Download SKILL.md~4 KB

What your agent will be able to do

Search tasks

Query Agent Maps API with natural language to find automation steps

Execute actions

Run each step using ARIA selectors with agent-browser or Playwright

Handle variables

Replace template fields with real values and manage dynamic steps

Frequently Asked Questions

Common questions about the Agent Maps API and browser automation.

Start building

The API is live and free during early preview. No signup, no API key just start making requests.

Try it now Back to homepage