Connectivity and Resilience#

This page presents all APIs and classes related to connectivity and resilience.

Auth#

class pyagentspec.auth.AuthConfig(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v26_2_0)#

Bases: Component

Base class for Auth configurations.

Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

class pyagentspec.auth.OAuthConfig(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v26_2_0, max_agentspec_version=AgentSpecVersionEnum.v26_2_0, issuer=None, endpoints=None, client, redirect_uri, scopes=None, scope_policy=None, pkce=None, resource=None)#

Bases: AuthConfig

Configure OAuth-based authentication for a tool or transport.

OAuthConfig is a generic configuration that can be used for both MCP servers and non-MCP remote API tools. It supports discovery-based configuration (via issuer) and explicit endpoints (via endpoints).

Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • issuer (str | None) – Authorization server issuer URL used for discovery (e.g., OIDC discovery or RFC 8414). If provided, runtimes should discover metadata/endpoints.

  • endpoints (OAuthEndpoints | None) – Explicit OAuth endpoints. If provided, runtimes should use these endpoints directly instead of discovery.

  • client (OAuthClientConfig) – OAuth client identity / registration configuration.

  • redirect_uri (str) – Redirect (callback) URI registered with the authorization server.

  • scopes (str | List[str] | None) – Requested scopes, either as a space-delimited string or a list of scope strings.

  • scope_policy (ScopePolicy | None) – How the runtime selects scopes.

  • pkce (PKCEPolicy | None) – PKCE policy. For authorization code flows, runtimes should typically set this to required with method S256.

  • resource (str | None) – Optional resource indicator value (RFC 8707). If set, runtimes should include it in relevant authorization and token requests when applicable.

client: OAuthClientConfig#

OAuth client identity / registration configuration.

endpoints: OAuthEndpoints | None#

Explicit OAuth endpoints. If provided, runtimes should use these endpoints directly instead of discovery.

issuer: str | None#

Authorization server issuer URL used for discovery (e.g., OIDC discovery or RFC 8414). If provided, runtimes should discover metadata/endpoints.

pkce: PKCEPolicy | None#

PKCE policy. For authorization code flows, runtimes should typically set this to required with method S256.

redirect_uri: str#

Redirect (callback) URI registered with the authorization server.

resource: str | None#

Optional resource indicator value (RFC 8707). If set, runtimes should include it in relevant authorization and token requests when applicable.

scope_policy: ScopePolicy | None#

How the runtime selects scopes.

scopes: str | List[str] | None#

Requested scopes, either as a space-delimited string or a list of scope strings.

class pyagentspec.auth.OAuthClientConfig(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v26_2_0, max_agentspec_version=AgentSpecVersionEnum.v26_2_0, type, client_id=None, client_secret=None, token_endpoint_auth_method=None, client_id_metadata_url=None, registration_endpoint=None)#

Bases: Component

OAuth client identity / registration configuration.

This configuration describes how the runtime establishes the OAuth client identity to use with the authorization server. It supports: - Pre-registered clients (static client_id/client_secret) - Client ID Metadata Documents (URL-formatted client_id) - Dynamic client registration (RFC 7591)

Parameters:

  • id (str) – OAuth client identifier (used for pre-registered clients).

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • type (Literal['pre_registered', 'client_id_metadata_document', 'dynamic_registration']) – Strategy used to obtain client identity.

  • client_id (str | None) – OAuth client identifier (used for pre-registered clients).

  • client_secret (str | None) – OAuth client secret (used for confidential pre-registered clients).

  • token_endpoint_auth_method (str | None) – Token endpoint authentication method (e.g., "client_secret_basic", "client_secret_post", "private_key_jwt", or "none").

  • client_id_metadata_url (str | None) – HTTPS URL used as the OAuth client_id for Client ID Metadata Documents.

  • registration_endpoint (str | None) – Optional dynamic registration endpoint. If omitted, runtimes may obtain it from authorization server discovery metadata when available.

client_id: str | None#

OAuth client identifier (used for pre-registered clients).

client_id_metadata_url: str | None#

HTTPS URL used as the OAuth client_id for Client ID Metadata Documents.

client_secret: str | None#

OAuth client secret (used for confidential pre-registered clients).

registration_endpoint: str | None#

Optional dynamic registration endpoint. If omitted, runtimes may obtain it from authorization server discovery metadata when available.

token_endpoint_auth_method: str | None#

Token endpoint authentication method (e.g., "client_secret_basic", "client_secret_post", "private_key_jwt", or "none").

type: Literal['pre_registered', 'client_id_metadata_document', 'dynamic_registration']#

Strategy used to obtain client identity.

class pyagentspec.auth.OAuthEndpoints(*, authorization_endpoint, token_endpoint, refresh_endpoint=None, revocation_endpoint=None, userinfo_endpoint=None)#

Bases: BaseModel

Explicit OAuth endpoint configuration.

Use this component when endpoint discovery is not available or not desired. This groups the relevant endpoints required to execute OAuth authorization code flows and token refresh.

Parameters:

  • authorization_endpoint (str) –

  • token_endpoint (str) –

  • refresh_endpoint (str | None) –

  • revocation_endpoint (str | None) –

  • userinfo_endpoint (str | None) –

authorization_endpoint: str#

Authorization endpoint where the user agent is redirected for login and consent.

refresh_endpoint: str | None#

Optional endpoint for refresh token requests. If not provided, runtimes typically reuse token_endpoint for refresh.

revocation_endpoint: str | None#

Optional endpoint for token revocation.

token_endpoint: str#

Token endpoint where authorization codes (and refresh tokens) are exchanged for access tokens.

userinfo_endpoint: str | None#

Optional OIDC UserInfo endpoint.

class pyagentspec.auth.PKCEPolicy(*, required=True, method=PKCEMethod.S256)#

Bases: BaseModel

Policy configuration for Proof Key for Code Exchange (PKCE).

PKCE mitigates authorization code interception and injection attacks in authorization code flows. Some protocols (such as MCP OAuth) require PKCE.

Parameters:
method: PKCEMethod#

PKCE challenge method. Defaults to “S256”.

required: bool#

If True, the runtime must refuse to proceed if PKCE cannot be used or cannot be validated as supported by the authorization server (depending on runtime policy and available metadata).

class pyagentspec.auth.PKCEMethod(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: str, Enum

PLAIN = 'plain'#

Code challenge is equal to code verifier.

S256 = 'S256'#

Code verifier is hashed using SHA-256. Recommended over the plain method

class pyagentspec.auth.ScopePolicy(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: str, Enum

FIXED = 'fixed'#

requests exactly the provided scopes.

USE_CHALLENGE_OR_SUPPORTED = 'use_challenge_or_supported'#

may prefer scopes indicated by challenges/metadata.

Retry Policy#

class pyagentspec.retrypolicy.RetryPolicy(*, max_attempts=2, request_timeout=None, initial_retry_delay=1.0, max_retry_delay=8.0, backoff_factor=2.0, jitter='full_and_equal_for_throttle', service_error_retry_on_any_5xx=True, recoverable_statuses=<factory>)#

Bases: BaseModel

Parameters:

  • max_attempts (int) –

  • request_timeout (float | None) –

  • initial_retry_delay (float) –

  • max_retry_delay (float) –

  • backoff_factor (float) –

  • jitter (Literal['equal', 'full', 'full_and_equal_for_throttle', 'decorrelated'] | None) –

  • service_error_retry_on_any_5xx (bool) –

  • recoverable_statuses (Dict[str, List[str]]) –

backoff_factor: float#

Back-off factor controlling how retry delays grow between attempts.

initial_retry_delay: float#

Base amount of time to wait before retrying (in seconds).

This is the base delay used for exponential backoff. For example, without jitter, retry backoff uses roughly:

t = initial_retry_delay * (backoff_factor ** attempts).

jitter: Literal['equal', 'full', 'full_and_equal_for_throttle', 'decorrelated'] | None#

Method to add randomness to the retry time. Supported methods are:

  • None: No jitter. t = min(initial_retry_delay * (backoff_factor ** attempts), max_retry_delay)

  • "full": t = min(random(0, initial_retry_delay * (backoff_factor ** attempts)), max_retry_delay)

  • "equal": t = min(initial_retry_delay * (backoff_factor ** attempts), max_retry_delay) * (1 + random(0, 1)) / 2)

  • "full_and_equal_for_throttle": full for 5xx errors and equal for 4xx errors

  • "decorrelated": t = min(initial_retry_delay * (backoff_factor ** attempts) + random(0, 1), max_retry_delay)

max_attempts: int#

Maximum number of retries for a request that fails with a recoverable status.

This value does not include the initial attempt.

max_retry_delay: float#

Maximum amount of time to wait between 2 retries (in seconds).

This caps the backoff delay computed from initial_retry_delay and backoff_factor.

recoverable_statuses: Dict[str, List[str]]#

Some additional statuses considered as recoverable.

By default retries on:

  • 409: conflict

  • 429: throttling (retry after x time)

Note: keys are represented as strings because Agent Spec configurations must be valid JSON (object keys are strings).

request_timeout: float | None#

Maximum allowed time (in seconds) for a single request attempt.

This is a per-attempt timeout. When set, runtimes should pass this value to the underlying HTTP client / SDK timeout configuration. Values are expressed in seconds and may be fractional (e.g., 0.5 means 500 milliseconds).

service_error_retry_on_any_5xx: bool#

Whether to retry on all 5xx errors (network errors, except 501)