Agent Class Configuration

Overview

The Agent class is the core building block for creating AI agents across multiple frameworks (Agno, OpenAI Agents SDK, Mastra). This reference covers configuration options, parameters, and best practices.

Agno Framework

Basic Agent Setup

from agno.agent import Agent
from agno.models.nebius import Nebius
from agno.tools.hackernews import HackerNewsTools
import os

agent = Agent(
    name="Tech News Analyst",
    model=Nebius(
        id="Qwen/Qwen3-30B-A3B",
        api_key=os.getenv("NEBIUS_API_KEY")
    ),
    tools=[HackerNewsTools()],
    instructions=["You are a helpful tech news analyst"],
    description="Analyzes HackerNews content and trends",
    markdown=True,
    show_tool_calls=True
)

Agent Parameters

name

string

required

The name of the agent. Used for identification in multi-agent systems.Example: "Tech News Analyst"

model

Model

required

The LLM model to use for the agent. See Model Providers for options.Example: Nebius(id="Qwen/Qwen3-30B-A3B", api_key=os.getenv("NEBIUS_API_KEY"))

tools

list[Tool]

default:"[]"

List of tools the agent can use. Tools extend agent capabilities with external functions.Example: [HackerNewsTools(), DuckDuckGoTools(search=True)]

instructions

list[str] | str

default:"[]"

Instructions that guide the agent’s behavior and responses.Example: ["You are a professional financial advisor", "Always provide data-backed insights"]

description

string

A description of the agent’s purpose and capabilities.Example: "Agent for managing database projects and schemas"

role

string

The role or persona the agent should adopt.Example: "search the web for information based on user input"

markdown

boolean

default:"false"

Enable markdown formatting in agent responses.Example: True

show_tool_calls

boolean

default:"false"

Display tool calls during execution (useful for debugging).Example: True

team

list[Agent]

List of sub-agents that this agent can delegate tasks to.Example: [web_search_agent, financial_agent]

memory

boolean

default:"false"

Enable conversation memory for context retention across interactions.Example: True

Agent Methods

run()

Execute the agent with a message/query.

response = agent.run(message: str, stream: bool = False)

message

string

required

The input message or query for the agent.

stream

boolean

default:"false"

Enable streaming responses.

content

string

The agent’s response content.

Example

response = agent.run("What are the top stories on HackerNews?")
print(response.content)

print_response()

Execute agent and print the response directly.

agent.print_response(message: str)

Example

agent.print_response("Analyze the latest AI trends")

aprint_response() (Async)

Asynchronously execute agent and print response.

await agent.aprint_response(message: str, stream: bool = False)

Example

import asyncio

async def main():
    await agent.aprint_response("Create a database schema", stream=True)

asyncio.run(main())

Multi-Agent Configuration

Team-Based Agents

Create agents that can delegate to specialized sub-agents:

from agno.agent import Agent
from agno.models.nebius import Nebius
from agno.tools.duckduckgo import DuckDuckGoTools
from agno.tools.yfinance import YFinanceTools
import os

# Specialized agents
web_search_agent = Agent(
    name="web_agent",
    role="search the web for information",
    model=Nebius(
        id="deepseek-ai/DeepSeek-R1-0528",
        api_key=os.getenv("NEBIUS_API_KEY")
    ),
    tools=[DuckDuckGoTools(search=True, news=True)],
    instructions=[
        "You are a professional web search AI agent",
        "Search for accurate, up-to-date information",
        "Provide exact information available on the web"
    ]
)

financial_agent = Agent(
    name="financial_agent",
    role="get financial information",
    model=Nebius(
        id="Qwen/Qwen3-32B",
        api_key=os.getenv("NEBIUS_API_KEY")
    ),
    tools=[
        YFinanceTools(
            stock_price=True,
            analyst_recommendations=True,
            stock_fundamentals=True,
            company_info=True,
            technical_indicators=True,
            historical_prices=True,
            key_financial_ratios=True,
            income_statements=True
        )
    ],
    instructions=[
        "You are a professional financial advisor AI agent",
        "Provide stock prices, recommendations, and fundamentals",
        "Include information about companies and financial terms"
    ]
)

# Coordinator agent
multi_agent = Agent(
    team=[web_search_agent, financial_agent],
    model=Nebius(
        id="meta-llama/Llama-3.3-70B-Instruct",
        api_key=os.getenv("NEBIUS_API_KEY")
    ),
    markdown=True
)

response = multi_agent.run("What's the latest news about Tesla stock?")

OpenAI Agents SDK

Basic Setup

from agents import Agent, Runner, RunConfig, ModelProvider
from openai import AsyncOpenAI
import os

client = AsyncOpenAI(
    base_url="https://api.tokenfactory.nebius.com/v1",
    api_key=os.getenv("NEBIUS_API_KEY")
)

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant",
    tools=[send_email]
)

result = await Runner.run(
    agent,
    "Send an email to [email protected]",
    run_config=RunConfig(model_provider=CUSTOM_MODEL_PROVIDER)
)

Custom Model Provider

from agents import ModelProvider, Model, OpenAIChatCompletionsModel
from openai import AsyncOpenAI

class CustomModelProvider(ModelProvider):
    def get_model(self, model_name: str | None) -> Model:
        return OpenAIChatCompletionsModel(
            model=model_name,
            openai_client=client
        )

CUSTOM_MODEL_PROVIDER = CustomModelProvider()

Mastra Framework (TypeScript)

Agent Configuration

import { Agent, Mastra } from '@mastra/core';
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { z } from 'zod';

const nebius = createOpenAICompatible({
  name: 'nebius',
  apiKey: process.env.NEBIUS_API_KEY,
  baseURL: 'https://api.tokenfactory.nebius.com/v1'
});

const agent = new Agent({
  name: 'Weather Agent',
  instructions: `You are a helpful weather assistant that provides accurate weather information.
Your primary function is to help users get weather details for specific locations.`,
  model: nebius('meta-llama/Meta-Llama-3.1-405B-Instruct'),
  tools: { weatherTool }
});

const mastra = new Mastra({
  agents: { weatherAgent: agent }
});

TypeScript Agent Parameters

name

string

required

Agent identifier.

instructions

string

required

Agent behavior guidelines.

model

LanguageModel

required

The LLM model instance.

tools

Record<string, Tool>

Object containing available tools.

Advanced Configuration

Agent with MCP Tools

import asyncio
from agno.agent import Agent
from agno.models.nebius import Nebius
from agno.tools.mcp import MCPTools
import os

async def run_agent():
    mcp_tools = MCPTools(
        "uvx --from gibson-cli@latest gibson mcp run",
        timeout_seconds=300
    )
    
    await mcp_tools.connect()
    
    agent = Agent(
        name="DatabaseAgent",
        model=Nebius(
            id="meta-llama/Meta-Llama-3.1-70B-Instruct",
            api_key=os.getenv("NEBIUS_API_KEY")
        ),
        tools=[mcp_tools],
        description="Agent for managing database projects",
        instructions="""You are a database assistant. Help users:
- Create new database projects
- Manage schemas (tables, columns, relationships)
- Deploy schema changes
- Query database structures
- Provide best practices guidance
""",
        markdown=True,
        show_tool_calls=True
    )
    
    await agent.aprint_response("Create a blog database", stream=True)
    await mcp_tools.close()

asyncio.run(run_agent())

Agent with Multiple Tool Types

from agno.agent import Agent
from agno.models.nebius import Nebius
from agno.tools.hackernews import HackerNewsTools
from agno.tools.duckduckgo import DuckDuckGoTools
from agno.tools.yfinance import YFinanceTools
import os

agent = Agent(
    name="Comprehensive Research Agent",
    model=Nebius(
        id="meta-llama/Llama-3.3-70B-Instruct",
        api_key=os.getenv("NEBIUS_API_KEY")
    ),
    tools=[
        HackerNewsTools(),
        DuckDuckGoTools(search=True, news=True),
        YFinanceTools(stock_price=True, company_info=True)
    ],
    instructions=[
        "You are a comprehensive research assistant",
        "Combine information from tech news, web search, and financial data",
        "Provide well-rounded, data-backed insights",
        "Always cite your sources"
    ],
    markdown=True,
    show_tool_calls=True
)

Best Practices

1. Clear Instructions

Provide specific, actionable instructions:

instructions = [
    "You are a professional financial advisor AI agent",
    "Always use tables to display financial/numerical data",
    "For text data use bullet points and small paragraphs",
    "Provide data-backed insights with sources",
    "Explain complex financial terms in simple language"
]

2. Enable Markdown for Better Output

agent = Agent(
    name="Agent",
    model=model,
    markdown=True  # Enable for formatted output
)

3. Use show_tool_calls During Development

agent = Agent(
    name="Agent",
    model=model,
    tools=[tool],
    show_tool_calls=True  # See tool execution details
)

4. Organize Multi-Agent Systems

# Specialized agents for specific tasks
searcher_agent = Agent(name="Searcher", ...)
analyst_agent = Agent(name="Analyst", ...)
writer_agent = Agent(name="Writer", ...)

# Coordinator for complex workflows
coordinator = Agent(
    name="Coordinator",
    team=[searcher_agent, analyst_agent, writer_agent],
    model=powerful_model
)

5. Choose Appropriate Models

# For simple tasks
basic_agent = Agent(
    model=Nebius(id="Qwen/Qwen3-30B-A3B", api_key=key)
)

# For complex reasoning
advanced_agent = Agent(
    model=Nebius(id="deepseek-ai/DeepSeek-V3-0324", api_key=key)
)

# For very large context
large_context_agent = Agent(
    model=Nebius(id="meta-llama/Meta-Llama-3.1-405B-Instruct", api_key=key)
)

Environment Setup

# Required
NEBIUS_API_KEY=your_nebius_api_key

# Optional (tool-specific)
SERPER_API_KEY=your_serper_key
SGAI_API_KEY=your_scrapegraph_key
GITHUB_TOKEN=your_github_token

Error Handling

try:
    response = agent.run("Your query")
    print(response.content)
except Exception as e:
    print(f"Agent error: {e}")

Common Tools

Agent Configuration

Overview

Agno Framework

Basic Agent Setup

Agent Parameters

Agent Methods

run()

Example

print_response()

Example

aprint_response() (Async)

Example

Multi-Agent Configuration

Team-Based Agents

OpenAI Agents SDK

Basic Setup

Custom Model Provider

Mastra Framework (TypeScript)

Agent Configuration

TypeScript Agent Parameters

Advanced Configuration

Agent with MCP Tools

Agent with Multiple Tool Types

Best Practices

1. Clear Instructions

2. Enable Markdown for Better Output

3. Use show_tool_calls During Development

4. Organize Multi-Agent Systems

5. Choose Appropriate Models

Environment Setup

Error Handling

Build docs developers (and LLMs) love

Common Tools

Agent Configuration

​Overview

​Agno Framework

​Basic Agent Setup

​Agent Parameters

​Agent Methods

​run()

​Example

​print_response()

​Example

​aprint_response() (Async)

​Example

​Multi-Agent Configuration

​Team-Based Agents

​OpenAI Agents SDK

​Basic Setup

​Custom Model Provider

​Mastra Framework (TypeScript)

​Agent Configuration

​TypeScript Agent Parameters

​Advanced Configuration

​Agent with MCP Tools

​Agent with Multiple Tool Types

​Best Practices

​1. Clear Instructions

​2. Enable Markdown for Better Output

​3. Use show_tool_calls During Development

​4. Organize Multi-Agent Systems

​5. Choose Appropriate Models

​Environment Setup

​Error Handling

​Related Resources

Build docs developers (and LLMs) love

Overview

Agno Framework

Basic Agent Setup

Agent Parameters

Agent Methods

run()

Example

print_response()

Example

aprint_response() (Async)

Example

Multi-Agent Configuration

Team-Based Agents

OpenAI Agents SDK

Basic Setup

Custom Model Provider

Mastra Framework (TypeScript)

Agent Configuration

TypeScript Agent Parameters

Advanced Configuration

Agent with MCP Tools

Agent with Multiple Tool Types

Best Practices

1. Clear Instructions

2. Enable Markdown for Better Output

3. Use show_tool_calls During Development

4. Organize Multi-Agent Systems

5. Choose Appropriate Models

Environment Setup

Error Handling

Related Resources