Schema Extraction (agentvisor.schema)

@agent and @tool decorators, plus the registry and JSON Schema generation functions AgentVisor's dynamic schema extraction (Tier 2 of the three-tier fallback) uses to discover custom Python agents and tools that aren't already described by a framework's own discovery file.

Not the same @agent/@tool as your framework

CrewAI's @agent/@task/@crew decorators and LangChain/LangGraph's @tool are framework-native and unrelated to this module — AgentVisor's framework providers read schemas from those directly (see each framework's own guide). Reach for agentvisor.schema's @agent/@tool only for custom Python entry points that have no framework of their own to discover them from.

Usage

from agentvisor import agent, tool
from pydantic import BaseModel

class ChatInput(BaseModel):
    message: str

class ChatOutput(BaseModel):
    reply: str

@agent(name="chat", description="A simple chat agent", input_type=ChatInput, output_type=ChatOutput)
def chat_agent(input: ChatInput) -> ChatOutput:
    ...

@tool(name="web_search", description="Search the web")
def search(query: str) -> list[str]:
    ...

If input_type/output_type are omitted, schemas are inferred from the function's own type hints (Pydantic models, TypedDict, dataclasses, and basic Python types are all supported).

API Reference

Decorators

agent()

def agent(
    name: str | None = None,
    description: str = "",
    input_type: type | None = None,
    output_type: type | None = None,
    metadata: dict[str, Any] | None = None,
) -> Callable[[Callable[..., Any]], Callable[..., Any]]

name defaults to the decorated function's __name__.

tool()

def tool(
    name: str | None = None,
    description: str = "",
    input_type: type | None = None,
    output_type: type | None = None,
    metadata: dict[str, Any] | None = None,
) -> Callable[[Callable[..., Any]], Callable[..., Any]]

Same signature and defaulting behavior as agent().

Functions

get_agents() / get_tools()

def get_agents() -> dict[str, AgentDefinition]
def get_tools() -> dict[str, ToolDefinition]

Return a copy of the module-level registry populated by every @agent/@tool decoration since process start.

get_agent_schema() / get_tool_schema()

def get_agent_schema(name: str) -> dict[str, Any] | None
def get_tool_schema(name: str) -> dict[str, Any] | None

Return {"name", "description", "input_schema", "output_schema", "metadata"} for a registered agent/tool, or None if name isn't registered.

export_schema() / export_schema_json()

def export_schema() -> dict[str, Any]
def export_schema_json(indent: int = 2) -> str

Export every registered agent, tool, and (if agentvisor.langgraph is importable) LangGraph graph schema in one combined {"agents", "tools", "graphs"} document. schema_cli (Tier 2 dynamic extraction, python3 -m agentvisor.schema_cli) calls export_schema_json() after importing your agent module, so anything registered at import time is included automatically — see Schema Discovery for how this fits into the full three-tier fallback and Troubleshooting: schema_cli fails if extraction fails at startup.

discover_agents() / discover_tools()

def discover_agents(module: ModuleType) -> list[AgentDefinition]
def discover_tools(module: ModuleType) -> list[ToolDefinition]

Find every decorated function reachable from module's top-level namespace (via dir(module)) that's present in the registry.

Classes

AgentDefinition / ToolDefinition

class AgentDefinition:
    def __init__(
        self,
        name: str,
        func: Callable[..., Any],
        description: str = "",
        input_schema: dict[str, Any] | None = None,
        output_schema: dict[str, Any] | None = None,
        metadata: dict[str, Any] | None = None,
    ): ...

ToolDefinition has an identical shape. description falls back to func.__doc__ if not given explicitly.