Skip to content

Identity & Run

Identity and Run are the two runtime primitives the SDK exposes.

  • Identity is long-lived. It owns the Ed25519 private key, the CA-signed certificate, and the proxy URL. Build wired LLMs from it. Open runs from it.
  • Run is short-lived. A context manager that defines an execution scope and tags every outbound LLM call with a fresh run_id.
identity = rv.register_agent(agent_id="research-v1", name="Research Agent")

with identity.run() as run:
    print(run.run_id)
    llm.invoke("...")

Identity

You never construct an Identity directly — rv.register_agent(...) returns one.

Attributes

Attribute Type Notes
agent_id str Stable external identifier (e.g. "research-v1").
name str Human-readable label.
proxy_url str Base proxy URL returned by the backend.
security_policy "hard" \| "soft" Default cross-identity guard mode.

Methods

identity.run(security_policy=None)

Returns a context manager that activates a fresh Run. Pure local operation — no backend round-trip.

security_policy (optional) overrides the identity's default for this scope only.

with identity.run() as run:
    ...

async with identity.run() as run:
    ...

identity.build_llm(BaseClass)

Returns a dynamic subclass of BaseClass wired through the RunVault proxy. See LLM Clients for supported classes.

RVChat = identity.build_llm(ChatOpenAI)
llm = RVChat(model="gpt-4o-mini")

Raises TypeError if BaseClass is not in the dispatch table.

identity.refresh_credentials()

Force a credential refresh. The transport calls this automatically on 401 CERTIFICATE_REVOKED; you rarely need to call it yourself. See Credential Rotation.

Raises AgentSuspendedError if the agent has been suspended.

Run

Created by identity.run(). The active Run is read from a ContextVar by the transport on every outbound request.

Attributes

Attribute Type Notes
run_id str Fresh UUID, generated on __enter__.
agent_id str Convenience accessor — pulls from the owning identity.
identity Identity The identity that opened this run.
started_at datetime UTC timestamp when the run was constructed.

Nesting

Nested runs are allowed and produce independent runs (each with its own run_id). The inner run shadows the outer; the outer resumes on exit, even on exception. There is no parent_run_id today.

with identity.run() as outer:
    with identity.run() as inner:
        ...                # uses inner.run_id
    ...                    # uses outer.run_id

current_run()

Module-level function that returns the active Run from the ContextVar.

from runvault import current_run

def my_tool(query: str) -> str:
    run = current_run()           # raises NoActiveRunError outside a run
    log.info("tool fired in run %s", run.run_id)
    ...
Spawning mechanism Inherits current_run()?
asyncio.create_task yes (PEP 567)
threading.Thread no — copy the context manually
concurrent.futures pools no — copy the context manually

For threads:

import contextvars, threading
ctx = contextvars.copy_context()
threading.Thread(target=lambda: ctx.run(worker)).start()

Reference

runvault.identity.Identity

A registered RunVault agent. Owns the Ed25519 private key and the CA-signed certificate. Source of Run objects and LLM classes.

Not constructed directly — always returned by RunVault.register_agent().

build_llm(base_cls)

Return a dynamic subclass of base_cls wired through the RunVault proxy. Dispatched by base-class identity.

Currently supported
  • langchain BaseChatModel subclasses (e.g. ChatOpenAI, ChatAnthropic)
  • crewai.BaseLLM

Raises:

Type Description
TypeError

If base_cls is not in the dispatch table.

provider_proxy_url(provider)

Return the full proxy URL for a given provider (e.g. "openai").

Used by the LLM wrappers when configuring their underlying SDK client (base_url=identity.provider_proxy_url("openai") + "/v1").

refresh_credentials()

Re-mint this identity's credentials via the backend.

Called by the transport when the proxy returns 401 CERTIFICATE_REVOKED. After this returns, the next outbound request will use the freshly minted private key + cert.

Raises:

Type Description
AgentSuspendedError

admin has suspended this agent.
RegistrationError

any other backend failure.

run(*, security_policy=None)

Return a context manager that activates a fresh Run.

with identity.run() as run:
    graph.invoke(...)

Generates a fresh run_id locally; no backend round-trip. The ContextVar is set on enter and reset on exit. Async usage (async with identity.run():) is supported with identical semantics.

Parameters:

Name Type Description Default
security_policy SecurityPolicy | None

Optional per-run override of this identity's default security_policy. The transport reads the effective policy on every request — see the cross-identity guard in http/transport.py.

 None

runvault.identity.Run

A single active execution. Yielded by identity.run().

Holds
  • run_id — fresh UUID generated locally on context-manager entry.
  • identity — back-reference to the owning Identity (for signing).
  • started_at — UTC timestamp when this Run was constructed.

The Run does NOT hold a JWT. JWTs are minted per-request by the transport, which reads run_id from this Run and uses the Identity's private key to sign.

agent_id: str property

Convenience accessor — pulls from the owning Identity.

effective_security_policy: SecurityPolicy property

Per-run override if set, else the owning Identity's default.

runvault.identity.current_run()

Return the active Run for the current async task / thread context.

Set by the with identity.run(): context manager. Read by the transport on every outbound request to embed run_id into the JWT and to reach the owning Identity for the signing key.

Raises:

Type Description
RuntimeError

If called outside a with identity.run(): block. Silent None would mask real bugs ("why is run_id missing from these spans?" three weeks later).