Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

from alter_sdk import App, Agent

​
App.get_agent()

Returns an Agent instance backed by the app key, with caller pinned to the agent UUID. The “monolithic” shape — see Agents → Overview.

​
Signature

def get_agent(self, agent_id: str | UUID) -> Agent

​
Example

research_bot = app.get_agent("agent_uuid")
me = await research_bot.me()

​
App.agents namespace

Operator surface for managed agents and their keys. All methods are async; require the App key.

​
agents.create()

async def create(
    *,
    name: str,
    display_name: str | None = None,
    type: str = "agent",  # "agent" or "service"
    scopes: dict[str, list[str]] | None = None,
    metadata: dict[str, Any] | None = None,
    policy: dict[str, Any] | None = None,
    idempotency_key: str | None = None,
) -> AgentCreateResult
scopes is a per-provider allowlist ({"google": ["gmail.readonly"], "slack": ["chat.write"]}), not a flat list. AgentCreateResult extends AgentInfo with api_key (plaintext, shown once).

​
agents.list()

async def list(
    *,
    include_revoked: bool = False,
    limit: int = 100,
    offset: int = 0,
) -> AgentListResult

​
agents.get(), agents.get_by_name()

async def get(agent_id: str) -> AgentInfo
async def get_by_name(name: str) -> AgentInfo | None

​
agents.update()

async def update(
    agent_id: str,
    *,
    display_name: str | None = None,
    metadata: dict[str, Any] | None = None,
    scopes: dict[str, list[str]] | None = None,
    policy: dict[str, Any] | None = None,
) -> AgentInfo
scopes must be the FULL desired per-provider allowlist — the backend rejects narrowing with AgentScopeNarrowingNotSupportedError.

​
agents.delete()

async def delete(agent_id: str) -> AgentInfo
Soft-deletes the agent and revokes all its keys.

​
agents.mint_key()

async def mint_key(agent_id: str) -> AgentKeyMintResult
AgentKeyMintResult extends AgentKey with api_key (plaintext, shown once).

​
agents.list_keys()

async def list_keys(agent_id: str) -> AgentKeyList
Returns metadata only — no plaintext. AgentKeyList has a single items: list[AgentKey] field; no pagination.

​
agents.deprecate_key(), agents.undeprecate_key()

async def deprecate_key(agent_id: str, key_id: str) -> AgentKey
async def undeprecate_key(agent_id: str, key_id: str) -> AgentKey

​
agents.revoke_key()

async def revoke_key(agent_id: str, key_id: str, *, force: bool = False) -> AgentKey
force=True required when revoking the last active key — otherwise raises LastActiveKeyError.

​
Agent.me()

Returns the calling agent’s AgentInfo. Available on Agent only.

​
Signature

async def me() -> AgentInfo

​
Agent.trace()

Async context manager that binds a run_id (and other tracing fields) to every request inside the scope. Available on Agent only.

​
Signature

def trace(
    *,
    run_id: str | None = None,
    thread_id: str | None = None,
    parent: str | None = ...,
    **metadata: str,
) -> AsyncContextManager[None]

​
Example

agent = app.get_agent("agent_uuid")
async with agent.trace(run_id="run-abc"):
    await agent.request("GET", url1, grant_id=g1)
    await agent.request("POST", url2, grant_id=g2)

​
See also