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.

Code that runs as a managed agent uses the Agent class. This page covers the runtime surface; for provisioning and key management, see Creating agents and Keys and rotation.

​
Constructing an Agent

Two ways: 
# (a) Direct: per-agent API key from env
from alter_sdk import Agent

vault = Agent(api_key=AGENT_API_KEY)

# (b) From an App (impersonation): app key + agent UUID
from alter_sdk import App

app = App(api_key=APP_API_KEY)
vault = app.get_agent(agent_id)
Both shapes produce the same backend identity. See Agents overview for when to pick which.

​
Identifying the agent at runtime

me = await vault.me()
print(me.id, me.name, me.scopes, me.policy)
me() returns the agent’s AgentInfo. Useful for self-introspection in tools that need to display “who am I” without a separate config plumbing step. Only available on Agent, not App.

​
Tracing a run

trace() binds a run_id to every request inside its scope. The run ID flows into the audit log so a multi-call workflow can be reconstructed: 
async with vault.trace(run_id="run-abc123"):
    await vault.request("GET", url1, grant_id=g1)
    await vault.request("POST", url2, grant_id=g2)
    # both audit rows tagged with run_id="run-abc123"
Pair with context={...} for per-call metadata — trace() for the run-level ID, context for tool name / step name. To attach run/tool/thread metadata without using trace(), pass context={"run_id": ..., "tool": ...} directly on vault.request(...).

​
Bootstrapping a grant from the agent

Agents can run vault.connect() and vault.authenticate() the same way an App can — useful for self-service flows where the agent obtains its own delegation rather than waiting for an operator to bind one: 
results = await vault.connect(providers=["github"])
print(results[0].grant_id)
The resulting grant is bound to the agent (not to a user). See Headless OAuth.

​
Self-revoking a delegation

When an agent decides it should no longer hold a delegation: 
await vault.revoke_delegation(grant_id)
Removes only the agent’s access path; the underlying user grant is untouched. To revoke the underlying grant entirely, an operator must call App.revoke_grant() — see Managing grants.

​
Identity-blending rules

  • Per-agent key + user_token is rejected. Returns HTTP 400. Agents do not impersonate users.
  • For agent code that runs inside a user session, use App(caller=AGENT_UUID, user_token_getter=...) instead of Agent. See Agents overview.

​
See also