Agent Configuration for Claude and Gemini

AI agents in flyte-sdk are configured using provider-specific Agent classes that encapsulate model selection, system instructions, and execution constraints. These configurations ensure that agents behave consistently across different tasks and prevent common issues like infinite tool-calling loops or excessive token consumption.

Defining Agent Behavior

The Agent class allows you to define the persona and operational parameters of your AI assistant. By setting the instructions (the system prompt), you control the agent's role and tone.

For Anthropic Claude, use flyteplugins.anthropic.agents.Agent:

from flyteplugins.anthropic.agents import Agent

# Configure a specialized Claude agent
research_agent = Agent(
    name="research-assistant",
    instructions="You are a meticulous researcher. Provide citations for all claims.",
    model="claude-3-5-sonnet-20240620",
    max_tokens=2048
)

For Google Gemini, use flyteplugins.gemini.agents.Agent:

from flyteplugins.gemini.agents import Agent

# Configure a specialized Gemini agent
creative_agent = Agent(
    name="creative-writer",
    instructions="You are a creative writer. Use vivid imagery and metaphors.",
    model="gemini-1.5-pro",
    max_output_tokens=4096
)

The name attribute is used for local logging and identification within flyte-sdk; it is not sent to the provider's API.

Resource and Loop Control

To prevent agents from getting stuck in "hallucination loops" or consuming too many resources during tool use, flyte-sdk provides two primary controls:

1. Token Limits: max_tokens (Anthropic) or max_output_tokens (Gemini) restricts the length of each individual response from the model.
2. Iteration Limits: max_iterations (defaulting to 10) defines the maximum number of tool-call and response cycles allowed before the agent stops.

If an agent reaches the max_iterations limit without providing a final text response, run_agent returns the string: "Maximum iterations reached without final response."

Integrating Tools

Agents become powerful when they can execute Flyte tasks. You use the function_tool() utility to wrap tasks or functions into a format the agent understands.

import flyte
from flyteplugins.anthropic import function_tool

@flyte.task
async def get_current_inventory(item_name: str) -> int:
    """Check the stock level for a specific item."""
    # Implementation details...
    return 42

# Wrap the task as a tool
inventory_tool = function_tool(get_current_inventory)

# Add it to an agent
agent = Agent(
    instructions="You manage warehouse stock.",
    tools=[inventory_tool]
)

Internally, function_tool uses the Flyte type engine to generate a JSON schema for the function's parameters, ensuring that complex types like dataclasses or FlyteFile are correctly described to the LLM.

Executing the Agent

The run_agent function is the primary entry point for executing an agent loop. You can either pass configuration parameters directly to run_agent or provide a pre-configured Agent object.

Option 1: Direct Parameters

This is useful for simple, one-off agent calls.

from flyteplugins.anthropic import run_agent

result = await run_agent(
    prompt="How many hammers do we have?",
    system="You are a helpful warehouse assistant.",
    tools=[inventory_tool],
    model="claude-3-5-sonnet-20240620"
)

Option 2: Using an Agent Object

Passing an Agent object is recommended for reusable configurations. When an agent is provided, it overrides the individual model, system, max_tokens, and tools parameters passed to run_agent.

from flyteplugins.anthropic import run_agent
from flyteplugins.anthropic.agents import Agent

my_agent = Agent(instructions="Be concise.", model="claude-3-haiku-20240307")

# The agent object's settings (concise, haiku) will be used
result = await run_agent(
    prompt="Explain photosynthesis",
    agent=my_agent
)

Provider Specifics

While the interfaces are similar, flyte-sdk handles the underlying API differences for each provider.

Feature	Anthropic Claude	Google Gemini
Default Model	claude-sonnet-4-20250514	gemini-2.5-flash
Token Param	max_tokens (default 4096)	max_output_tokens (default 8192)
API Key Env	ANTHROPIC_API_KEY	GOOGLE_API_KEY
Tool Format	get_anthropic_tools()	get_gemini_tools()

Handling Safety and Errors

In addition to iteration limits, Gemini agents include built-in safety filtering. If the model's response is blocked by Google's safety filters, the agent will stop and return: "Agent stopped: content was blocked by safety filters."

For both providers, tool results that are not strings are automatically JSON-serialized before being sent back to the LLM, ensuring the agent can process structured data returned by Flyte tasks.