papers/hanzo-agent-sdk/sections/04-implementation-details.tex

\section{Implementation Details}


\subsection{Tool Management}

Tools are defined using the \texttt{@function\_tool} decorator:

\begin{lstlisting}[language=Python]
@function_tool
async def search_web(
    context: RunContextWrapper,
    query: str,
    max_results: int = 10
) -> list[SearchResult]:
    """Search the web for information."""
    return await context.web_client.search(
        query, max_results)
\end{lstlisting}

The decorator extracts parameter schemas from type annotations and docstrings, generating OpenAPI-compatible tool definitions for MCP compatibility.

\subsection{Lifecycle Hooks}

The \texttt{AgentHooks} interface provides callbacks for:
\begin{itemize}
    \item \texttt{on\_start}: Before agent execution begins
    \item \texttt{on\_end}: After agent completes (success or failure)
    \item \texttt{on\_tool\_call}: Before each tool invocation
    \item \texttt{on\_tool\_result}: After tool returns
    \item \texttt{on\_handoff}: When control transfers to another agent
\end{itemize}

These hooks enable comprehensive tracing, metrics collection, and custom logic injection.

\subsection{Tracing Integration}

Every execution creates a trace with structured spans:

\begin{lstlisting}[language=Python]
with custom_span("network_execution",
                 {"network": config.name}):
    result = await Runner.run(
        starting_agent=agent,
        input=input,
        context=network_context,
        max_turns=max_turns)
\end{lstlisting}

Traces are compatible with OpenTelemetry exporters, enabling integration with observability platforms.