Quick Start

This guide will walk you through creating your first Anvil tool.

1. Initialize Your Project

Start by creating a new project with the Anvil CLI:

mkdir my-agent && cd my-agent
anvil init

This will:

Create an anvil_tools/ directory for generated tools
Set up .gitignore to protect your API keys
Prompt you for your API keys (securely stored in .env)
Create an example script

2. Create Your First Tool

Create a file called main.py:

from dotenv import load_dotenv
from anvil import Anvil

load_dotenv()

# Initialize Anvil
anvil = Anvil()

# Create a tool by describing what you want
weather_tool = anvil.use_tool(
    name="get_weather",
    intent="Get the current weather for a city using a free weather API"
)

# Run the tool
result = weather_tool.run(city="San Francisco")
print(result)

Run it:

python main.py

The first run will:

Generate Python code for the weather tool
Save it to anvil_tools/get_weather.py
Execute and return the result

Subsequent runs use the cached code instantly.

3. View the Generated Code

Check what Anvil generated:

cat anvil_tools/get_weather.py

You’ll see clean, working Python code with:

A header showing it’s Anvil-managed
The intent hash for change detection
A run() function with your logic

4. Use with Input Parameters

Define explicit input parameters for better control:

from anvil import Anvil, InputParam

anvil = Anvil()

stock_tool = anvil.use_tool(
    name="get_stock_price",
    intent="Get the current stock price for a given ticker symbol",
    inputs=[
        InputParam(name="symbol", param_type="str", required=True, description="Stock ticker symbol"),
        InputParam(name="include_history", param_type="bool", required=False, default=False),
    ]
)

result = stock_tool.run(symbol="AAPL")
print(result)

5. Handle Errors Safely

Use run_safe() for error handling without exceptions:

result = stock_tool.run_safe(symbol="INVALID")

if result.success:
    print(result.data)
else:
    print(f"Error: {result.error}")

6. Use with AI Frameworks

Convert your tool for any framework:

# For LangChain
from langchain.agents import create_react_agent

lc_tool = stock_tool.to_langchain()
agent = create_react_agent(llm, [lc_tool], prompt)

# For CrewAI
from crewai import Agent

crew_tool = stock_tool.to_crewai()
agent = Agent(role="Analyst", tools=[crew_tool])

7. Chain Multiple Tools

Combine tools for complex workflows:

# Create tools
search = anvil.use_tool(name="search", intent="Search the web")
summarize = anvil.use_tool(name="summarize", intent="Summarize text")

# Chain them together
chain = search.pipe(summarize)
result = chain.run(query="Latest AI news")

CLI Commands

Useful commands for managing your tools:

# Check system status
anvil doctor

# List all generated tools
anvil list

# Force regeneration of all tools
anvil clean

# Verify tool code is safe
anvil verify get_weather

Testing Without API Keys

Use stub mode for testing without LLM calls:

anvil = Anvil(use_stub=True)

# Tools return mock data - no API calls made
tool = anvil.use_tool(name="test", intent="Test tool")
result = tool.run()  # Returns stub response