Tools

The tools an agent can call are part of its definition: each one’s name, description and input schema. Tools can be recorded from functions with @tool, and an agent’s MCP servers are recorded as McpServers.

Tool

A tool an agent can call: its name, description and input schema.

Usually made by tool from a function. Build one yourself for a tool that isn’t a Python function, such as one served elsewhere.

Example:

lookup = ga.Tool(
    "lookup_ticket",
    "Fetch a support ticket by ID.",
    {"type": "object", "properties": {"id": {"type": "string"}}},
)

Attributes:

• name (str) – What the model calls the tool.
• description (str) – What the tool does, for the model.
• input_schema (dict[str, Any]) – A JSON Schema for the tool’s arguments.
• source_hash (str | None) – sha256:<hex> of the tool’s source, so editing it gives the agent a new definition; None to leave it out.

Functions:

• from_function – Describe a function as a tool, as tool does.

Tool.from_function

from_function(function: Callable[..., Any], *, name: str | None = None, description: str | None = None, hash_source: bool = True) -> Tool

Describe a function as a tool, as tool does.

Parameters:

• function (Callable[..., Any]) – The function, sync or async.
• name (str | None) – The tool’s name; defaults to the function’s.
• description (str | None) – What the tool does; defaults to the docstring’s summary, the text before any Args:-style section.
• hash_source (bool) – Record a hash of the function’s source.

Raises:

• TypeError – The function takes *args or **kwargs, or a parameter’s type has no JSON Schema.
• ValueError – There is no description, from the argument or a docstring.

tool

tool(function: F | None = None, /, *, name: str | None = None, description: str | None = None, hash_source: bool = True) -> F | Callable[[F], F]

Record a function as a tool, and return it unchanged.

The tool’s name is the function’s, its description the docstring’s summary, and its input schema comes from the type hints through Pydantic, with each Google-style Args: entry as that parameter’s description (an Annotated[..., Field(description=...)] wins over it). Its source is hashed, so editing the tool gives the agent a new definition.

The function keeps working exactly as before; the description is read when the decorator runs, so a mistake fails at the function.

Example:

@ga.tool
def search_docs(query: str, limit: int = 10) -> list[str]:
    """Search the internal documentation."""

@ga.tool(name="search", hash_source=False)
async def wiki_search(query: str) -> list[str]:
    """Full-text search over the wiki."""

Parameters:

• function (F | None) – The function, when used as @ga.tool.
• name (str | None) – The tool’s name; defaults to the function’s.
• description (str | None) – What the tool does; defaults to the docstring’s summary.
• hash_source (bool) – Record a hash of the function’s source.

Raises:

• TypeError – The function takes *args or **kwargs, or a parameter’s type has no JSON Schema.
• ValueError – There is no description.

McpServer

An MCP server the agent uses.

Build one with stdio, http or sse. Headers and environment variables can’t be recorded, and a credential in the URL or arguments is refused.

Attributes:

• name (str) – The server’s name.
• transport (Literal['stdio', 'sse', 'streamable_http']) – "stdio", "sse" or "streamable_http".
• url (str | None) – The server’s URL, for sse and streamable_http.
• command (str | None) – The command that starts it, for stdio.
• args (Iterable[str]) – The command’s arguments.

Functions:

• stdio – A server the agent starts as a process, such as npx.
• http – A server reached over streamable HTTP.
• sse – A server reached over server-sent events.

McpServer.stdio

stdio(name: str, command: str, *args: str) -> McpServer

A server the agent starts as a process, such as npx.

McpServer.http

http(name: str, url: str) -> McpServer

A server reached over streamable HTTP.

McpServer.sse

sse(name: str, url: str) -> McpServer

A server reached over server-sent events.