Anvil Class

The Anvil class is the main entry point for the SDK.

Constructor

from anvil import Anvil

anvil = Anvil(
    api_key: str | None = None,
    firecrawl_key: str | None = None,
    tools_dir: str | Path = "./anvil_tools",
    self_healing: bool = True,
    max_heal_attempts: int = 2,
    use_stub: bool = False,
    model: str | None = None,
    provider: str = "anthropic",
    log_file: str | Path | None = None,
    interactive_credentials: bool = True,
    env_file: str | Path | None = None,
    verified_mode: bool = False,
    security_policy: SecurityPolicy | None = None,
    mode: str = "local",
)

Parameters

Parameter	Type	Default	Description
api_key	str | None	None	LLM provider API key. Falls back to environment variable.
firecrawl_key	str | None	None	FireCrawl API key for documentation fetching.
tools_dir	str | Path	"./anvil_tools"	Directory to store generated tools.
self_healing	bool	True	Enable automatic tool regeneration on failure.
max_heal_attempts	int	2	Maximum self-healing attempts per tool.
use_stub	bool	False	Use stub generator (no LLM calls).
model	str | None	None	LLM model to use. Provider-specific default if None.
provider	str	"anthropic"	LLM provider: “anthropic”, “openai”, or “grok”.
log_file	str | Path | None	None	Path to log file for event logging.
interactive_credentials	bool	True	Enable interactive credential prompts.
env_file	str | Path | None	None	Path to .env file for credentials.
verified_mode	bool	False	Verify generated code in sandbox.
security_policy	SecurityPolicy | None	None	Custom security policy for sandbox.
mode	str	"local"	Generator mode: “local”, “stub”, or “cloud”.

Methods

use_tool()

Create or load a tool.

tool = anvil.use_tool(
    name: str,
    intent: str,
    docs_url: str | None = None,
    inputs: list[InputParam] | None = None,
) -> Tool

Parameters

Parameter	Type	Description
name	str	Unique identifier for the tool.
intent	str	Natural language description of what the tool does.
docs_url	str | None	URL to API documentation.
inputs	list[InputParam] | None	Explicit input parameter definitions.

Returns

Tool - A tool object ready for execution.

Example

tool = anvil.use_tool(
    name="search_github",
    intent="Search GitHub repositories by query",
    docs_url="https://docs.github.com/en/rest/search",
    inputs=[
        InputParam(name="query", param_type="str", required=True),
        InputParam(name="sort", param_type="str", default="stars"),
    ]
)

---

list_tools()

List all available tools in the tools directory.

tools = anvil.list_tools() -> list[str]

Returns

list[str] - List of tool names.

Example

tools = anvil.list_tools()
print(tools)  # ["search_github", "get_weather", "send_email"]

---

get_tool_info()

Get metadata about a specific tool.

info = anvil.get_tool_info(name: str) -> dict | None

Parameters

Parameter	Type	Description
name	str	Tool name.

Returns

dict | None - Tool metadata or None if not found.

Example

info = anvil.get_tool_info("search_github")
print(info)
# {
#     "name": "search_github",
#     "intent": "Search GitHub repositories",
#     "version": "1.0",
#     "status": "active",
#     "created_at": "2025-01-18T10:00:00Z",
#     ...
# }

---

get_tool_code()

Get the source code of a generated tool.

code = anvil.get_tool_code(name: str) -> str | None

Parameters

Parameter	Type	Description
name	str	Tool name.

Returns

str | None - Tool source code or None if not found.

Example

code = anvil.get_tool_code("search_github")
print(code)

---

reset_heal_attempts()

Reset the self-healing attempt counter.

anvil.reset_heal_attempts(name: str | None = None) -> None

Parameters

Parameter	Type	Description
name	str | None	Tool name, or None to reset all.

Example

# Reset specific tool
anvil.reset_heal_attempts("search_github")

# Reset all tools
anvil.reset_heal_attempts()

---

get_sandbox_status()

Get the status of the sandbox system.

status = anvil.get_sandbox_status() -> dict

Returns

dict - Sandbox status information.

Example

status = anvil.get_sandbox_status()
print(status)
# {
#     "enabled": True,
#     "active_driver": "docker",
#     "docker_available": True,
#     "policy": {...}
# }

Properties

logger

Access the event logger.

logger = anvil.logger  # AnvilLogger

sandbox

Access the sandbox manager.

sandbox = anvil.sandbox  # SandboxManager

mode

Get the current generator mode.

mode = anvil.mode  # "local", "stub", or "cloud"

InputParam

Define input parameters for tools.

from anvil import InputParam

param = InputParam(
    name: str,
    param_type: str = "str",
    required: bool = True,
    description: str = "",
    default: Any = None,
)

Fields

Field	Type	Default	Description
name	str	required	Parameter name.
param_type	str	"str"	Type: “str”, “int”, “float”, “bool”, “list”.
required	bool	True	Whether the parameter is required.
description	str	""	Help text for the parameter.
default	Any	None	Default value if not provided.

Exceptions

RuntimeError

Raised when tool execution fails (if self-healing is disabled or exhausted).

ImportError

Raised when a required dependency is missing.

See Also

• Tool Class Reference
• Configuration Options
• CLI Reference