Core Concepts
Tools
Extend agent capabilities with custom tools and toolkits.
Tools extend what an agent can do beyond its built-in capabilities. Zgent supports both Claude Code's built-in tools and custom tools you define.
Built-in tools
When using AgentEngine.CLAUDE, the agent has access to Claude Code's native tools:
| Tool | Description |
|---|---|
Read | Read file contents |
Write | Create or overwrite files |
Edit | Edit files with string replacement |
Bash | Execute shell commands |
Glob | Find files by pattern |
Grep | Search file contents |
WebSearch | Search the web |
WebFetch | Fetch web page content |
Task | Launch sub-agents |
Control which tools are available with AgentOptions:
from zgent import AgentOptions
options = AgentOptions(
allowed_tools=["Read", "Write", "Glob", "Grep"],
disallowed_tools=["Bash", "WebSearch"],
)Custom tools
Define custom tools by subclassing Tool:
from zgent import AgentDefinition, AgentEngine, Tool
class WeatherTool(Tool):
name = "get_weather"
description = "Get the current weather for a city."
parameters = {
"type": "object",
"properties": {
"city": {"type": "string"},
"units": {"type": "string", "default": "celsius"},
},
"required": ["city"],
}
async def execute(self, input: dict, context) -> str:
city = input["city"]
units = input.get("units", "celsius")
return f"Weather in {city}: 22{units[0]}, sunny"Register tools on the agent definition:
definition = AgentDefinition(
system_prompt="You are a weather assistant.",
engine_type=AgentEngine.CLAUDE,
tools=[WeatherTool()],
)Toolkits
Group related tools into a Toolkit when you want decorator-based tool definitions and an MCP server wrapper:
from zgent import Toolkit
class DatabaseToolkit(Toolkit):
name = "database"
@Toolkit.tool(description="Query rows from the database")
async def query(self, sql: str) -> str:
return f"Executed: {sql}"Tool input schema
Subclassed Tool objects define a JSON-schema-like parameters object. Toolkit.tool(...) extracts parameters from the method signature automatically:
class SearchTool(Tool):
name = "search_docs"
description = "Search internal documentation."
parameters = {
"type": "object",
"properties": {
"query": {"type": "string"},
"max_results": {"type": "integer", "default": 10},
},
"required": ["query"],
}
async def execute(self, input: dict, context) -> str:
results = await search(input["query"], limit=input.get("max_results", 10))
return "\n".join(r.title for r in results)