Skip to content

AuthorizedRestApiTool

The AuthorizedRestApiTool is a specialized version of RestApiTool that provides a simplified way to make authenticated REST API calls. This tool streamlines authentication handling, making it ideal for working with APIs that require consistent authentication across multiple requests.

Features

  • Simplified authentication setup
  • Support for Bearer tokens, Basic auth, API keys in parameters, and custom headers
  • All the capabilities of the base REST API tool
  • Automatic secret retrieval from Agentic's secret store

Initialization

def __init__(token_type: str, token_var: str, token_name: str = "Bearer")

Parameters:

  • token_type (str): Authentication type, one of "bearer", "basic", "parameter", or "header"
  • token_var (str): The name of the secret variable that contains the token value
  • token_name (str): The name used with the token (varies by auth method)

Authentication Types

The tool supports the following authentication methods:

  1. Bearer Token: python AuthorizedRestApiTool("bearer", "API_KEY_SECRET_NAME") Adds an Authorization: Bearer <token> header.

  2. Basic Auth: python AuthorizedRestApiTool("basic", "BASIC_AUTH_SECRET") For basic auth, the secret should be in the format username:password.

  3. Parameter Auth: python AuthorizedRestApiTool("parameter", "API_KEY_SECRET", "api_key") Adds the token as a query parameter (e.g., ?api_key=value).

  4. Header Auth: python AuthorizedRestApiTool("header", "API_KEY_SECRET", "X-API-Key") Adds a custom header with the specified name (e.g., X-API-Key: value).

Methods

get_resource

async def get_resource(url: str, params: dict = {}, run_context: RunContext = None)

Performs an HTTP GET request with authentication.

Parameters:

  • url (str): The URL to request
  • params (dict): Query parameters
  • run_context (RunContext): The execution context

Returns: The parsed response based on content type.

post_resource

async def post_resource(url: str, content_type: str = "application/json", data: str = "{}", run_context: RunContext = None)

Performs an HTTP POST request with authentication.

Parameters:

  • url (str): The URL to request
  • content_type (str): The content type (default: "application/json")
  • data (str): Request body
  • run_context (RunContext): The execution context

Returns: The parsed response based on content type.

put_resource

async def put_resource(url: str, data: str = "{}", run_context: RunContext = None)

Performs an HTTP PUT request with authentication.

Parameters:

  • url (str): The URL to request
  • data (str): JSON request body
  • run_context (RunContext): The execution context

Returns: The parsed response based on content type.

patch_resource

async def patch_resource(url: str, data: str = "{}", run_context: RunContext = None)

Performs an HTTP PATCH request with authentication.

Parameters:

  • url (str): The URL to request
  • data (str): JSON request body
  • run_context (RunContext): The execution context

Returns: The parsed response based on content type.

delete_resource

async def delete_resource(url: str, run_context: RunContext = None)

Performs an HTTP DELETE request with authentication.

Parameters:

  • url (str): The URL to request
  • run_context (RunContext): The execution context

Returns: The parsed response based on content type.

Example Usage

from agentic.common import Agent
from agentic.tools import AuthorizedRestApiTool

# Set up the secret first
# agentic set-secret GITHUB_TOKEN your_token_here

# Create an agent with authenticated API capability
github_api = AuthorizedRestApiTool("bearer", "GITHUB_TOKEN")
api_agent = Agent(
    name="GitHub API Client",
    instructions="You can make authenticated API calls to GitHub.",
    tools=[github_api]
)

# Use the agent to get user information
response = api_agent << "Get my GitHub profile information from https://api.github.com/user"
print(response)

# Use the agent to list repositories
response = api_agent << "List my repositories from https://api.github.com/user/repos"
print(response)

# Using an API key in a parameter
weather_api = AuthorizedRestApiTool("parameter", "WEATHER_API_KEY", "apikey")
weather_agent = Agent(
    name="Weather API Client",
    instructions="You can get weather data using the Weather API.",
    tools=[weather_api]
)

# Use the agent to get weather data
response = weather_agent << "Get the current weather for London from https://api.weatherapi.com/v1/current.json"
print(response)

Setting Up Secrets

Before using the tool, you need to set up your secrets:

# For GitHub API
agentic set-secret GITHUB_TOKEN your_github_token

# For Weather API
agentic set-secret WEATHER_API_KEY your_weather_api_key

Common API Configurations

  1. GitHub API: python AuthorizedRestApiTool("bearer", "GITHUB_TOKEN")

  2. OpenAI API: python AuthorizedRestApiTool("bearer", "OPENAI_API_KEY")

  3. RapidAPI: python AuthorizedRestApiTool("header", "RAPIDAPI_KEY", "X-RapidAPI-Key")

  4. AWS Signature v4: python # For AWS, use a custom tool that implements Signature v4 auth # The AuthorizedRestApiTool is for simpler auth methods

Notes

  • The tool automatically retrieves the token value from the agent's secret store
  • If the token is not found, the tool will raise an error
  • The authentication is automatically applied to all requests
  • For different APIs that require different authentications, create multiple instances of the tool
  • The tool inherits all capabilities from RestApiTool
  • For more complex authentication schemes like OAuth 2.0 flows, additional tools may be needed