Tool calling

Filtered Discovery

Only expose specific agents or capabilities to the LLM.

from agentfield.tool_calling import ToolCallConfig

result = await app.ai(
    user="What's the weather in Tokyo and translate the forecast to Spanish?",
    tools=ToolCallConfig(
        tags=["weather", "translation"],     # Only weather and translation tools
        max_turns=5,
        max_tool_calls=10,
    ),
)

Lazy Schema Hydration

For large registries (100+ tools), send metadata first and hydrate schemas only for tools the LLM selects.

result = await app.ai(
    user="Help me analyze this dataset.",
    tools=ToolCallConfig(
        schema_hydration="lazy",       # Send names+descriptions first
        max_candidate_tools=50,        # Present at most 50 tools
        max_hydrated_tools=10,         # Full schemas for top 10 selected
    ),
)

Structured Output with Tool Calling

Combine tool calling with structured output -- the LLM uses tools to gather data, then returns a validated schema.

class TravelPlan(BaseModel):
    destination: str
    weather: str
    activities: list[str]
    estimated_cost: float

plan = await app.ai(
    system="Plan a trip using available tools for weather and activity data.",
    user="Plan a weekend trip to Barcelona.",
    tools="discover",
    schema=TravelPlan,
)
print(plan.destination)  # Validated TravelPlan

Observability and Debugging

Inspect the full trace to understand what the AI did.

result = await app.ai(
    user="Research and summarize recent AI papers.",
    tools="discover",
)

print(f"Completed in {result.trace.total_turns} turns")
print(f"Made {result.trace.total_tool_calls} tool calls")

for call in result.trace.calls:
    status = "OK" if not call.error else f"ERROR: {call.error}"
    print(f"  [{call.turn}] {call.tool_name} ({call.latency_ms:.0f}ms) -> {status}")

Per-Call Limits

Override the default config for specific calls.

# Quick lookup -- tight limits
result = await app.ai(
    user="What time is it in London?",
    tools="discover",
    max_turns=3,
    max_tool_calls=2,
)

# Complex research -- generous limits
result = await app.ai(
    user="Compare pricing across all our vendor APIs.",
    tools="discover",
    max_turns=20,
    max_tool_calls=50,
)

Fine-tune the tool-calling loop with ToolCallConfig.

Every tool-calling response includes a ToolCallTrace for full observability.

ToolCallRecord

Go SDK Details

The Go SDK provides three key functions for tool calling:

// AIWithTools — high-level: discover + loop + trace in one call
resp, trace, err := app.AIWithTools(ctx, prompt, ai.ToolCallConfig{
    MaxTurns:     10,
    MaxToolCalls: 25,
})

// CapabilitiesToToolDefinitions — convert all discovered capabilities to OpenAI tool schemas
caps, _ := app.Discover(ctx)
tools := ai.CapabilitiesToToolDefinitions(caps.JSON.Capabilities)

// ExecuteToolCallLoop — low-level: run the tool-call loop on the AI client
messages := []ai.Message{{Role: "user", Content: []ai.ContentPart{{Type: "text", Text: prompt}}}}
tools := ai.CapabilitiesToToolDefinitions(caps.JSON.Capabilities)
callFn := func(ctx context.Context, target string, input map[string]interface{}) (map[string]interface{}, error) {
    return app.Call(ctx, target, input)
}
finalResp, trace, err := aiClient.ExecuteToolCallLoop(ctx, messages, tools, ai.ToolCallConfig{
    MaxTurns:     5,
    MaxToolCalls: 25,
}, callFn)