Skip to main content
Custom agents let you turn any website into a structured data API. Describe what data you need, and Nimble builds a production-ready extraction agent that delivers structured results at scale. There are multiple ways to create them. Pick the one that fits your workflow.

Nimble Studio

Visual, no-code creation in the browser

API / CLI / SDK

Create agents from code, terminal, or CI/CD pipelines

Agent Builder Skill

AI-assisted creation in Claude Code or Cursor

​
Custom vs Public Agents

FeaturePublic AgentCustom Agent
MaintenanceMaintained by Nimble 24/7Maintained by you
SetupZero, just use agent nameCreate via Platform, API, CLI, SDK, or IDE
AvailabilityPopular sitesAny website
Auto-healingYes, updated when sites changeNo, you update if needed
API usageSame Agent APISame Agent API
VisibilityAvailable to all usersPrivate to your account
Check the Agent Gallery first. A pre-built agent may already exist for your target site. Pre-built agents are auto-maintained by Nimble 24/7.

​
Choose Your Method

All methods produce the same result: a private agent accessible via the Agent API. The difference is the interface.
MethodBest forSetup
Nimble StudioNon-technical users, quick visual creationNone, browser only
APICI/CD pipelines, automated agent creationAPI key
CLITerminal-first developersnpm i -g @nimble-way/nimble-cli + API key
SDK (Python/Node)Programmatic creation in application codepip install nimble_python or npm i @nimble-way/nimble-js + API key
Agent Builder SkillAI-assisted creation in Claude Code / CursorPlugin install + API key
The fastest way to create custom agents. The Agent Builder skill handles the entire generate/test/iterate flow inside your IDE. Just describe what you need in plain language, and your AI assistant does the rest.

Get Started with Agent Builder

Install the Nimble plugin for Claude Code or Cursor and start building agents from your IDE in minutes.
Example prompts: 
"build an agent for extracting hotel prices from Booking.com"
"set up extraction for Amazon product pages"
"create a reusable scraper for job listings on LinkedIn"
The skill searches for existing agents, generates a new one if needed, and lets you refine interactively. No manual API calls or polling required.
The Agent Builder skill uses the same APIs documented below, but handles the generate/poll/iterate loop automatically. Start here unless you need CI/CD integration or full programmatic control.

​
Via API / CLI / SDK

For CI/CD pipelines, automation, or full programmatic control. All methods follow three steps: generate, poll, iterate.
1

Generate

Describe what you need. Optionally provide input/output schemas. Refine an existing agent by passing from_agent.
2

Poll for completion

Generation is async. Poll the generation ID until status is success. This typically takes 3-7 minutes for new agents, or as fast as 1 minute for refinements. The generated version is automatically available via the Agent API.
3

Iterate (optional)

Not satisfied with the results? Generate again with from_agent pointing at the current agent to refine it. Repeat steps 1-2 until the output matches expectations.

​
Generate

POST /v1/agents/generations
​
agent_name
string
required
Name for the new agent. Use lowercase with underscores (e.g., niche_store_pdp).Be descriptive: competitor_pricing not agent1. Include the site or type: niche_store_reviews.
​
prompt
string
required
Natural language description of what data to extract from the target page.Be specific about data types and structure. For example: “Extract product name, current price as a number, rating out of 5, and first 5 reviews with rating and text.”
​
url
string
required
Sample URL of the page type you want to extract from. The generation engine analyzes this page to build the extraction logic.
​
from_agent
string
Name of an existing agent to refine. Use this to iterate on a previous generation. A new version is created with the new prompt applied on top, preserving what already works.
​
input_schema
object
Custom input schema defining the parameters the agent accepts (e.g., url, keyword, page). If omitted, the schema is inferred from the prompt and URL.
​
output_schema
object
Custom output schema defining the structure of extracted data. If omitted, the schema is inferred from the prompt.
​
metadata
object
Additional metadata to attach to the agent. Use this for internal labels, tags, or tracking information.
from nimble_python import Nimble
import time

nimble = Nimble(api_key="YOUR-API-KEY")

# Generate the agent
result = nimble.agent.generate(
    agent_name="niche_store_pdp",
    prompt="Extract product name, price, rating, stock status, and first 5 reviews with rating and text",
    url="https://example-niche-store.com/products/widget-pro"
)

generation_id = result["id"]
print(f"Generation started: {generation_id}")

# Poll until complete
while True:
    gen = nimble.agent.get_generation(generation_id=generation_id)
    print(f"Status: {gen['status']}")
    if gen["status"] == "success":
        break
    time.sleep(10)

print(f"Agent ready: {gen['agent_name']}")
print(f"Summary: {gen['summary']}")

​
Generate Response

{
  "id": "gen_abc123",
  "status": "queued",
  "agent_name": "niche_store_pdp"
}
FieldTypeDescription
idstringUnique generation ID. Use this to poll for completion.
statusstringqueued, in_progress, success, or failed.
agent_namestringThe agent name provided in the request.

​
Poll Response

GET /v1/agents/generations/{generation_id} Generation is async and typically takes 3-7 minutes for new agents, or as fast as 1 minute for refinements. Poll with the generation_id (path parameter) until status is success. Review the results to decide whether to iterate or use the agent. Response: 
{
  "id": "gen_abc123",
  "status": "success",
  "agent_name": "niche_store_pdp",
  "generated_version_id": "ver_xyz789",
  "summary": "Extracts product name, price, rating, stock status, and customer reviews from product detail pages."
}
FieldTypeDescription
idstringThe generation ID.
statusstringqueued, in_progress, success, or failed.
agent_namestringThe agent name.
generated_version_idstringVersion ID of the generated agent. Present when success. Automatically published.
summarystringWhat the generated agent does. Present when success. Review to decide if refinement is needed.

​
Iterate (Optional)

POST /v1/agents/generations If the generation results are not satisfactory, refine the agent by calling the same generate endpoint with from_agent. A new version is created with the new prompt applied on top, preserving what already works.
​
from_agent
string
required
Name of the agent to refine. Pass the agent name from the original generation.
​
prompt
string
required
Describe what to change. For example: “Add a discount_percentage field” or “Fix the reviews array to include the reviewer name.”
result = nimble.agent.generate(
    prompt="Add a discount_percentage field. Fix the reviews array to include the reviewer name.",
    from_agent="niche_store_pdp"
)
Response is the same as Generate. Poll the new generation ID until complete, then decide to iterate again or use the agent. Each generated version is automatically published and available via POST /v1/agents/run with "agent": "niche_store_pdp" just like any pre-built agent. See the Agents API docs for full usage.

​
Tips for Better Agents

Be specific about data types. Instead of “get the price”, say “extract the current price as a number without currency symbols.” Describe the structure you want. Instead of “get reviews”, say “extract reviews as an array with rating (1-5) and review text for each.” Mention edge cases. “Extract the sale price if available, otherwise use the regular price.” Test with multiple pages. Try your agent on different pages of the same type to ensure it works consistently.

​
Agent Naming

  • Use lowercase with underscores: my_store_pdp
  • Be descriptive: competitor_pricing not agent1
  • Include the site or type: niche_store_reviews

​
Good to Know

  • Pre-built agents are auto-maintained by Nimble 24/7. Custom agents can be updated anytime via Nimble Studio, API, CLI, or SDK if the target site changes.
  • Each agent handles one page type. For multi-page workflows, create separate agents (e.g., one for search results, one for product details).
  • Custom agents are private to your account but shared within your team.

​
FAQ

Yes. Custom agents are designed for production use. They use the same reliable infrastructure as public agents with predictable costs and high throughput.
Unlike public agents (maintained by Nimble 24/7), custom agents don’t auto-heal. If extractions start failing or returning incorrect data, update the agent via Nimble Studio, API, CLI, or SDK using the from_agent refinement flow.
Generation typically takes 3-7 minutes for new agents, or as fast as 1 minute for refinements. Poll the generation ID until the status is success.
generate creates a new agent from scratch. Passing from_agent refines an existing agent by creating a new version with your prompt applied on top, preserving what already works while fixing what doesn’t.
Yes. The full generate/poll/iterate flow is available via REST API, making it straightforward to integrate into CI/CD pipelines.
There is no limit on the number of custom agents you can create.
Yes. Custom agents are available to all members of your Nimble account. They are private to your organization but shared within your team.

​
Next Steps

Nimble Studio

Create agents visually in the browser

Agent Builder Skill

AI-assisted creation in Claude Code or Cursor

Agent Gallery

Browse pre-built agents for popular sites

API Reference

Full API docs for agents endpoints