Python SDK API Reference

init()

from agentsecrets import init

init(
    port: int = 8765,
    workspace: str | None = None,
    project: str | None = None,
    environment: str | None = None
)

Enables transparent HTTP client interception for requests and httpx. Any outgoing request containing an AS_SECRET_ placeholder is intercepted, stripped, and routed through the local AgentSecrets proxy daemon to resolve real credentials at the network transport boundary.

credential Helper

from agentsecrets import credential

# Dynamically evaluates to the placeholder string: "AS_SECRET_<ATTRIBUTE>"
key_ref = credential.OPENAI_API_KEY       # -> "AS_SECRET_OPENAI_API_KEY"
stripe_ref = credential.STRIPE_SECRET_KEY # -> "AS_SECRET_STRIPE_SECRET_KEY"

A dynamic placeholder generator that allows referencing secret names as code attributes instead of hardcoded strings.

AgentSecrets (Synchronous)

from agentsecrets import AgentSecrets

client = AgentSecrets(
    port: int = 8765,
    workspace: str | None = None,
    project: str | None = None,
    environment: str | None = None,
    agent: str | None = None,
    agent_token: str | None = None,
    timeout: float = 30.0,
    intercept: bool = False
)

Supports the standard context manager interface:

with AgentSecrets() as client:
    response = client.call("https://api.stripe.com/v1/balance", bearer="STRIPE_KEY")

Methods

• client.call(url, method="GET", bearer=None, basic=None, header=None, query=None, body_field=None, form_field=None, body=None, params=None, headers=None, timeout=None) -> Response
  Makes an authenticated request through the local proxy. Key arguments accept secret names, never plaintext values.
• client.async_call(...) -> Coroutine[Response]
  Asynchronous invocation of call().
• client.spawn(command: list[str], *, capture: bool = True, timeout: float | None = None) -> SpawnResult
  Spawns a child process with environment variables injected from the active environment in the OS Keychain. Applies real-time stdout/stderr masking.
• client.spawn_async(command: list[str], *, capture: bool = True, timeout: float | None = None) -> Coroutine[SpawnResult]
  Asynchronous process execution.
• client.status() -> StatusInfo
  Returns operational metadata for the active session (workspace, project, environment, proxy status, and port).
• client.close()
  Closes active HTTP connections.

AsyncAgentSecrets (Asynchronous)

from agentsecrets import AsyncAgentSecrets

async with AsyncAgentSecrets(
    port: int = 8765,
    workspace: str | None = None,
    project: str | None = None,
    environment: str | None = None,
    agent: str | None = None,
    agent_token: str | None = None,
    timeout: float = 30.0
) as client:
    response = await client.call("https://api.stripe.com/v1/balance", bearer="STRIPE_KEY")

Response

Returned by client.call():

response.status_code   # int: HTTP response code (e.g. 200, 403)
response.body          # str: Raw response body string
response.json()        # dict / list: Parsed JSON payload
response.headers       # dict: Response headers (sensitive headers redacted)
response.redacted      # bool: True if the proxy redacted an echoed credential
response.duration_ms   # int: Request latency in milliseconds

SpawnResult

Returned by client.spawn():

result.exit_code       # int: Process exit status (0 for success)
result.stdout          # str: Captured stdout (with real-time secret redaction)
result.stderr          # str: Captured stderr (with real-time secret redaction)

from agentsecrets import agent

# Module functions:
agent_list = agent.list_agents()
my_agent = agent.get("billing-bot")
new_agent = agent.create("invoice-agent", scopes=["proxy_call"])
agent.delete("old-agent")

Agent Instance Methods:

• agent_instance.call(url, **kwargs) -> Response
  Executes a proxy call scoped to this agent identity.
• agent_instance.async_call(url, **kwargs) -> Coroutine[Response]
  Asynchronous scoped proxy call.
• agent_instance.issue_token(description=None, expires_in_days=None) -> dict
  Issues a cryptographic token for this agent.
• agent_instance.list_tokens() -> list[dict]
  Lists active token IDs and creation timestamps for this agent.
• agent_instance.revoke_token(token_id: str)
  Revokes a specific token.
• agent_instance.revoke_all_tokens()
  Revokes all tokens belonging to this agent.
• agent_instance.get_policy() -> dict
  Retrieves capabilities policy configured for this agent.
• agent_instance.set_policy(projects: list[str], secrets: list[str], scopes: list[str])
  Configures capabilities policy rules.
• agent_instance.delete()
  Deletes the agent identity.

from agentsecrets.testing import MockAgentSecrets
from agentsecrets.client import Response, SpawnResult

mock = MockAgentSecrets(
    default_response: Response | None = None,
    default_spawn_result: SpawnResult | None = None
)

# Configure mock endpoints
mock.set_response(
    "https://api.stripe.com/v1/balance",
    Response(status_code=200, body='{"object": "balance"}', headers={})
)
mock.set_spawn_result("stripe mcp", SpawnResult(exit_code=0, stdout="OK", stderr=""))

# Test execution
response = mock.call("https://api.stripe.com/v1/balance", bearer="STRIPE_KEY")

# Inspect recorded call objects
record = mock.calls[0]
# record.url -> "https://api.stripe.com/v1/balance"
# record.method -> "GET"
# record.bearer -> "STRIPE_KEY" (Name only, never value)
# record.basic -> None
# record.header -> None
# record.query -> None
# record.body_field -> None
# record.form_field -> None
# record.body -> None

# Reset records
mock.reset()