API Reference

This section provides a detailed API reference for the classes and methods in the pyagentai library.

Client

class pyagentai.client.AgentAIClient(api_key=None, config=None)[source]

Bases: _MethodRegistrarMixin

Client for the agent.ai API.

This client handles authentication and communication with the agent.ai API.

config

The configuration for the client.

Initialize the agent.ai API client.

Parameters:

  • api_key (Optional[str]) – The API key for authenticating with agent.ai. If provided, overrides the key in the config.

  • config (Optional[AgentAIConfig]) – The configuration for the client. If not provided, a default configuration is used.

__init__(api_key=None, config=None)[source]

Initialize the agent.ai API client.

Parameters:

  • api_key (Optional[str]) – The API key for authenticating with agent.ai. If provided, overrides the key in the config.

  • config (Optional[AgentAIConfig]) – The configuration for the client. If not provided, a default configuration is used.

Return type:

None

async close()[source]

Close the HTTP client.

Return type:

None

async find_agents(status=None, slug=None, query=None, tag=None, intent=None, limit=50, offset=0)

Search and discover agents on the agent.ai platform.

This method allows you to find agents by filtering based on their status, slug, tags, or by using a search query or a natural language intent.

For more details, see the official Find Agents API documentation.

Parameters:

  • status (Optional[str]) – Filter agents by visibility status. Can be one of "public", "private", or "any". Defaults to None.

  • slug (Optional[str]) – Filter agents by their human-readable slug (e.g., "domainvaluation"). Defaults to None.

  • query (Optional[str]) – Text to search for in agent names and descriptions. Defaults to None.

  • tag (Optional[str]) – Filter agents by a specific tag (e.g., "Marketing"). Defaults to None.

  • intent (Optional[str]) – A natural language description of the task you want the agent to perform. This helps find agents that match your use case. Example: "I need to analyze financial statements.". Defaults to None.

  • limit (int) – The maximum number of agents to return. Defaults to 50. A limit of 0 will return all agents from the offset.

  • offset (int) – The offset for pagination. Defaults to 0.

  • self (AgentAIClient)

Return type:

list[AgentInfo]

Returns:

A list of AgentInfo objects, each representing an agent that matches the search criteria.

Raises:

ValueError – If pagination parameters are invalid.

async grab_web_text(url, mode='scrape')

Extract text content from a specified web page or domain.

This function can be used to either scrape a single page or crawl a website up to a certain depth to collect text.

For more details, see the official Grab Web Text API documentation.

Parameters:

  • url (str) – The URL of the web page to extract text from. Must be a fully qualified URL, including http:// or https://.

  • mode (str) –

    The crawler mode. Can be one of:

    • "scrape": Extracts content from the provided URL only.

    • "crawl": Crawls the website starting from the URL, collecting content from up to 100 pages.

  • self (AgentAIClient)

Returns:

  • The extracted text content as a single string.

  • A dictionary with metadata about the operation.

Return type:

A tuple containing

Raises:

ValueError – If the provided URL is invalid.

async grab_web_screenshot(url, ttl_for_screenshot=3600)

Capture a visual screenshot of a specified web page for documentation or analysis.

For more details, see the official Grab Web Screenshot API documentation.

Parameters:

  • url (str) – The URL of the web page to capture. Must be a fully qualified URL, including http:// or https://.

  • ttl_for_screenshot (int) –

    The cache expiration time for the screenshot in seconds. Can be one of: - 3600: 1 hour - 86400: 1 day - 604800: 1 week - 18144000: 6 months

    Defaults to 3600.

  • self (AgentAIClient)

Return type:

str

Returns:

A URL to the screenshot.

Raises:

ValueError – If the provided URL is invalid.

async get_youtube_transcript(url)

Fetches the transcript of a YouTube video using the video URL.

For more details, see the official Get YouTube Transcript API documentation.

Parameters:

  • url (str) – The URL of the YouTube video. Must be a fully qualified URL, including http:// or https://.

  • self (AgentAIClient)

Returns:

  • The transcript of the YouTube video as a single string.

  • A dictionary with metadata about the operation.

Return type:

A tuple containing

Raises:

ValueError – If the provided URL is invalid.

async get_youtube_channel(url)

Retrieve detailed information about a YouTube channel, including its videos and statistics.

For more details, see the official Get YouTube Channel API documentation.

Parameters:

  • url (str) – The URL of the YouTube channel. Must be a fully qualified URL, including http:// or https://.

  • self (AgentAIClient)

Return type:

dict

Returns:

The channel information as a dictionary of objects.

Raises:

ValueError – If the provided URL is invalid.

async get_twitter_users(keywords, num_users=1)

Search and retrieve Twitter user profiles based on specific keywords for targeted social media analysis.

For more details, see the official Get Twitter Users API documentation.

Parameters:

  • keywords (str) – The keywords to search for.

  • num_users (int) –

    The number of user profiles to retrieve. Can be one of: - 1: 1 user - 5: 5 users - 10: 10 users - 25: 25 users - 50: 50 users - 100: 100 users

    Defaults to 1.

  • self (AgentAIClient)

Return type:

list[str]

Returns:

A list of Twitter user profiles.

Raises:

ValueError – If the provided keywords are invalid or num_users is not one of the allowed values.

async company_financial_info(company, quarter, year)

Retrieve company earnings information for a given stock symbol over time.

For more details, see the official Company Earnings Info API documentation.

Parameters:

  • company (str) – The stock symbol of the company.

  • quarter (int) – The quarter of the year to retrieve earnings info.

  • year (int) – The year of the earnings info to retrieve.

  • self (AgentAIClient)

Return type:

str

Returns:

A string containing the company earnings information.

Raises:

ValueError – If the provided parameters are invalid.

async company_financial_profile(company)

Retrieve detailed financial and company profile information for a given stock symbol, such as market cap and the last known stock price for any company.

For more details, see the official Company Financial Profile API documentation.

Parameters:
Return type:

dict[str, Any]

Returns:

A dictionary containing the company financial profile information.

Raises:

ValueError – If the provided parameters are invalid.

async domain_info(domain)

Retrieve detailed information about a domain, including its registration details, DNS records, and more.

For more details, see the official Domain Info API documentation.

Parameters:

  • domain (str) – The domain name to retrieve information for. Must be a fully qualified domain name, including http:// or https://.

  • self (AgentAIClient)

Return type:

dict[str, Any]

Returns:

The domain information as a dictionary of objects.

Raises:

ValueError – If the provided domain is invalid.

async get_google_news(query, date_range='24h', location=None)

Fetch news articles based on queries and date ranges to stay updated on relevant topics or trends.

For more details, see the official Get Google News API documentation.

Parameters:

  • query (str) – The keywords to search for.

  • date_range (str) – The time frame for the news search. Can be one of: - 24h: Last 24 hours - 7d: Last 7 days - 30d: Last 30 days - 90d: Last 90 days

  • location (Optional[str]) – The location to filter news results. Defaults to None.

  • self (AgentAIClient)

Return type:

dict[str, Any]

Returns:

A dictionary containing the news articles related to the query.

Raises:

ValueError – If the provided query is invalid.

Perform a YouTube search and retrieve results for specified queries.

For more details, see the official Run YouTube Search API documentation.

Parameters:
Return type:

dict[str, Any]

Returns:

A dictionary containing the YouTube search results - videos, shorts, suggestions and channels.

Raises:

ValueError – If the provided query is invalid.

async get_search_results(query, search_engine='google', num_posts=10)

Fetch search results from Google or YouTube for specific queries, providing valuable insights and content.

For more details, see the official Get Search Results API documentation.

Parameters:

  • query (str) – The keywords to search for.

  • search_engine (str) – The search engine to use. Can be one of: - "google": Google - "youtube": YouTube - "youtube_channel": YouTube Channel

  • num_posts (int) – The number of results to retrieve. Can be one of: - 1: 1 result - 5: 5 results - 10: 10 results - 25: 25 results - 50: 50 results - 100: 100 results

  • self (AgentAIClient)

Return type:

dict[str, Any]

Returns:

A dictionary containing the search results from the specified search engine.

Raises:

ValueError – If the provided parameters are invalid.

async get_recent_tweets(profile_handle, recent_tweets_count=1)

Fetch recent tweets from a specified Twitter handle.

For more details, see the official Get Recent Tweets API documentation.

Parameters:

  • profile_handle (str) – The Twitter handle to fetch recent tweets from.

  • recent_tweets_count (int) – The number of tweets to return.

  • self (AgentAIClient)

Return type:

dict[str, Any]

Returns:

A dictionary containing the recent tweets from the specified Twitter handle, including metrics like retweets, likes, and replies.

Raises:

ValueError – If the provided parameters are invalid.

async get_linkedin_profile(profile_handle)

Retrieve detailed information from a specified LinkedIn profile.

For more details, see the official Get LinkedIn Profile API documentation.

Parameters:

  • profile_handle (str) – The LinkedIn handle to fetch profile from.

  • self (AgentAIClient)

Return type:

dict[str, Any]

Returns:

A dictionary containing the profile information from the specified LinkedIn handle.

Raises:

ValueError – If the provided profile handle is invalid.

async find_linkedin_profile(query)

Find the LinkedIn profile slug for a person.

For more details, see the official Find LinkedIn Profile API documentation.

Parameters:

  • query (str) – The text query to find the LinkedIn profile slug.

  • self (AgentAIClient)

Return type:

str

Returns:

A string containing the LinkedIn profile slug.

Raises:

ValueError – If the provided query is invalid.

async get_linkedin_activity(profile_urls, num_posts=3)

Retrieve recent LinkedIn posts from specified profiles to analyze professional activity and engagement.

For more details, see the official Get LinkedIn Activity API documentation.

Parameters:

  • profile_urls (list[str]) – A list of LinkedIn profile URLs to analyze. Each URL must be a fully qualified URL, including http:// or https://.

  • num_posts (int) –

    The number of recent posts to fetch from each profile. Can be one of: - 1: 1 post - 5: 5 posts - 10: 10 posts - 25: 25 posts - 50: 50 posts - 100: 100 posts

    Defaults to 3.

  • self (AgentAIClient)

Return type:

dict[str, Any]

Returns:

A dictionary containing the recent LinkedIn posts, including the profile URL, post content, and other relevant information.

Raises:

ValueError – If the provided profile URLs are invalid.

async get_company_object(domain)

Gather enriched company data using Breeze Intelligence for deeper analysis and insights.

For more details, see the official Get Company Object API documentation.

Parameters:

  • domain (str) – The domain of the company to retrieve enriched data. Must be a fully qualified domain name, including http:// or https://.

  • self (AgentAIClient)

Return type:

dict

Returns:

The company information as a dictionary of objects.

Raises:

ValueError – If the provided domain is invalid.

async get_bluesky_posts(handle, num_posts=5)

Fetch recent posts from a specified Bluesky user handle, making it easy to monitor activity on the platform.

For more details, see the official Get Bluesky Posts API documentation.

Parameters:

  • handle (str) – The Bluesky handle to fetch recent posts from.

  • num_posts (int) –

    The number of posts to return. Can be one of: - 1: 1 post - 5: 5 posts - 10: 10 posts - 25: 25 posts - 50: 50 posts - 100: 100 posts

    Defaults to 5.

  • self (AgentAIClient)

Return type:

dict[str, Any]

Returns:

A dictionary containing the recent posts from the specified Bluesky handle, including metrics like reposts, likes, and replies.

Raises:

ValueError – If the provided parameters are invalid.

async search_bluesky_posts(query, num_posts=1)

Search for Bluesky posts matching specific keywords or criteria to gather social media insights.

For more details, see the official Search Bluesky Posts API documentation.

Parameters:

  • query (str) – The keywords to search for.

  • num_posts (int) –

    The number of results to retrieve. Can be one of: - 1: 1 result - 5: 5 results - 10: 10 results - 25: 25 results - 50: 50 results - 100: 100 results

    Defaults to 1.

  • self (AgentAIClient)

Return type:

dict[str, Any]

Returns:

A dictionary containing the search results from the specified Bluesky posts including metrics like reposts, likes, and replies.

Raises:

ValueError – If the provided parameters are invalid.

async get_instagram_profile(username)

Fetch detailed profile information for a specified Instagram username.

For more details, see the official Get Instagram Profile API documentation.

Parameters:

  • username (str) – The Instagram username to fetch profile from.

  • self (AgentAIClient)

Return type:

dict[str, Any]

Returns:

A dictionary containing the profile information from the specified Instagram username.

Raises:

ValueError – If the provided username is invalid.

async get_instagram_followers(username, limit=20)

Retrieve a list of top followers from a specified Instagram account for social media analysis.

For more details, see the official Get Instagram Followers API documentation.

Parameters:

  • username (str) – The Instagram username to fetch profile from.

  • limit (int) –

    The number of top followers to retrieve. Can be one of: - 10: 10 followers - 20: 20 followers - 50: 50 followers - 100: 100 followers

    Defaults to 20.

  • self (AgentAIClient)

Return type:

dict[str, Any]

Returns:

A dictionary containing the list of top followers from the specified Instagram account including their profile information, follower count, and other relevant metrics.

Raises:

ValueError – If the provided parameters are invalid.

Configuration

class pyagentai.config.agentai_config.AgentAIConfig(**data)[source]

Bases: BaseModel

Configuration for the agent.ai client.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
api_url: str
api_key: str
web_url: str
timeout: float
endpoints: AgentAIEndpoints
classmethod from_yaml(path)[source]

Load configuration from a YAML file.

Return type:

AgentAIConfig

Parameters:

path (str)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Configuration for agent.ai API endpoints.

class pyagentai.config.agentai_endpoints.AgentAIEndpoints(**data)[source]

Bases: BaseModel

Endpoints for agent.ai API.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • find_agents (Endpoint)

  • grab_web_text (Endpoint)

  • grab_web_screenshot (Endpoint)

  • get_youtube_transcript (Endpoint)

  • get_youtube_channel (Endpoint)

  • get_twitter_users (Endpoint)

  • company_financial_info (Endpoint)

  • company_financial_profile (Endpoint)

  • domain_info (Endpoint)

  • get_google_news (Endpoint)

  • run_youtube_search (Endpoint)

  • get_search_results (Endpoint)

  • get_recent_tweets (Endpoint)

  • get_linkedin_profile (Endpoint)

  • find_linkedin_profile (Endpoint)

  • get_linkedin_activity (Endpoint)

  • get_company_object (Endpoint)

  • get_bluesky_posts (Endpoint)

  • search_bluesky_posts (Endpoint)

  • get_instagram_profile (Endpoint)

  • get_instagram_followers (Endpoint)

find_agents: Endpoint
grab_web_text: Endpoint
grab_web_screenshot: Endpoint
get_youtube_transcript: Endpoint
get_youtube_channel: Endpoint
get_twitter_users: Endpoint
company_financial_info: Endpoint
company_financial_profile: Endpoint
domain_info: Endpoint
get_google_news: Endpoint
get_search_results: Endpoint
get_recent_tweets: Endpoint
get_linkedin_profile: Endpoint
find_linkedin_profile: Endpoint
get_linkedin_activity: Endpoint
get_company_object: Endpoint
get_bluesky_posts: Endpoint
search_bluesky_posts: Endpoint
get_instagram_profile: Endpoint
get_instagram_followers: Endpoint
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Data Types

class pyagentai.types.agent_info.FunctionProperty(**data)[source]

Bases: BaseModel

A property of a function parameter.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
type: str
description: str
enum: list[str] | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyagentai.types.agent_info.FunctionParameters(**data)[source]

Bases: BaseModel

Parameters for a function.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
type: str
properties: dict[str, FunctionProperty]
required: list[str]
additional_properties: bool
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyagentai.types.agent_info.FunctionInfo(**data)[source]

Bases: BaseModel

The function information for invoking an agent.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
name: str
description: str
parameters: FunctionParameters
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyagentai.types.agent_info.InvokeAgentInput(**data)[source]

Bases: BaseModel

The input specification for invoking the agent.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
type: str
function: FunctionInfo
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyagentai.types.agent_info.AgentInfo(**data)[source]

Bases: BaseModel

Information about an agent.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • agent_id (str)

  • agent_id_human (str | None)

  • name (str)

  • invoke_agent_input (InvokeAgentInput)

  • description (str | None)

  • tags (list[str | None])

  • price (int | None)

  • approximate_time (int | None)

  • type (str | None)

  • reviews_count (int | None)

  • reviews_score (float | None)

agent_id: str
agent_id_human: str | None
name: str
invoke_agent_input: InvokeAgentInput
description: str | None
tags: list[str | None]
price: int | None
approximate_time: int | None
type: str | None
reviews_count: int | None
reviews_score: float | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].