egisai.set_context()

egisai.set_context(
    *,
    user_id: str | None = None,
    user_role: str | None = None,
    agent: str | None = None,
    agent_id: str | None = None,
    session_id: str | None = None,
    workflow_id: str | None = None,
    end_user_id: str | None = None,
) -> None

Attach per-request metadata to every governed call that runs inside the same async task or thread. The fields you set land on each audit event and on the context that the policy engine sees. set_context() writes to a ContextVar, so async tasks and child threads inherit the value cleanly without leaking across requests.

When to use it

Use set_context() for:

Multi-tenant attribution — pass the end-customer’s user_id and session_id per request so each audit event identifies who triggered it.
Sub-agents — name a logical sub-agent (agent="billing-bot") so calls from this section of code show up as a distinct Agent on the dashboard.
Workflows — group related calls with a workflow_id.

If you only have one Agent per process, you don’t need to call this — the app= argument on egisai.init() is enough.

Parameters

str | None

End-customer or end-user identifier for multi-tenant attribution. Recorded on each audit event for the lifetime of the context.

str | None

Optional role label for the user (e.g. "admin", "customer"). Free-form.

str | None

Logical sub-agent name. The first time the SDK sees a new name it registers it as an Agent on the platform; subsequent uses are cache hits.Wins over the process-level app from egisai.init() and over auto-detected identity for the duration of the context.

str | None

Direct UUID escape hatch for callers that already know the platform’s internal Agent ID and don’t want a name-resolution round-trip.Most users should prefer agent= and let the SDK resolve the ID.

str | None

End-user session identifier. Useful for grouping conversation turns on the dashboard.

str | None

Identifier for an orchestration step or batch job. Lets you correlate related calls on the dashboard.

str | None

Opaque identifier for the end-user the agent is currently serving — used to power per-end-user behavioral roll-ups inside the dashboard’s Agent Identity view. Distinct from user_id: user_id is typically the operator or session principal, end_user_id is the downstream customer the agent is helping.The platform hashes this value on intake; we recommend hashing on the SDK side too (e.g. hashlib.sha256(customer_id.encode()).hexdigest()) so a raw customer identifier never leaves your process.

Passing None for any field leaves the existing value alone. To clear a field, set it to an empty string.

Returns

None. The active context is updated in place.

Examples

Multi-tenant FastAPI handler

from fastapi import FastAPI, Request
import egisai
import openai

egisai.init(app="orchestrator", env="production")
app = FastAPI()
client = openai.OpenAI()

@app.post("/chat")
async def chat(request: Request, body: dict):
    egisai.set_context(
        user_id=body["user_id"],
        session_id=body["session_id"],
        agent="customer-support-bot",
    )
    response = client.chat.completions.create(
        model="gpt-4.1",
        messages=body["messages"],
    )
    return response.choices[0].message.content

Each request lands on the dashboard tagged with the right user, session, and sub-agent.

Multiple sub-agents in one process

egisai.init(app="orchestrator", env="production")

def triage(query):
    egisai.set_context(agent="triage-agent")
    return client.chat.completions.create(...)

def billing(query):
    egisai.set_context(agent="billing-agent")
    return client.chat.completions.create(...)

Calls from each function show up as separate Agents on the dashboard. See Multi-agent context for more patterns.

Workflow correlation

import uuid
import egisai

workflow_id = uuid.uuid4().hex
egisai.set_context(workflow_id=workflow_id)
for step in plan:
    run_step(step)         # all calls share workflow_id

Block-scoped identity with `egisai.agent()`

For a short-lived block where you want a single agent identity to win outright over every auto-detection tier, egisai.agent(name) is a context manager. It pushes the identity onto an internal stack on entry and restores the previous identity on exit, so it is safe to nest and to use inside async tasks.

import egisai

egisai.init(app="orchestrator", env="production")

with egisai.agent("Triage"):
    response = client.chat.completions.create(...)

with egisai.agent("Billing"):
    response = client.chat.completions.create(...)

Use agent() for surgical pins (one tool call, one sub-routine). Use set_context(agent=…) for handler-scoped state that should flow across multiple downstream calls in the same task.

Eager registration with `egisai.register_agent()`

import egisai

egisai.init(app="orchestrator", env="production")

# Pre-create the dashboard row at startup so it appears under
# Agents the moment the app boots, before any traffic flows.
egisai.register_agent("billing-agent")

register_agent(name) is equivalent to set_context(agent=name) without mutating the current context. It returns the platform agent ID on success or None if the SDK isn’t initialized or the backend is unreachable. The function never raises — failures fall through silently and the next call uses the SDK’s normal attribution.

Resolution precedence

When attributing a call, the SDK uses, in order, the first identity it finds:

with egisai.agent(name): block on the current task.
set_context(agent_id=...) (explicit UUID).
set_context(agent=...) (resolved name).
Server-issued stable IDs surfaced by the provider (e.g. OpenAI prompt_id, Gemini cached_content, Bedrock managed-agent IDs).
A framework patch’s explicit agent name.
A framework patch’s composite bundle hash.
System-prompt fingerprint (auto-detected sub-agent).
The process-level app= from egisai.init().

Explicit agent() and set_context calls always win over auto-detection.

What’s next

Multi-agent context

Patterns for several sub-agents in one process.

Agents

The mental model behind agent identity.

​When to use it

​Parameters

​Returns

​Examples

​Multi-tenant FastAPI handler

​Multiple sub-agents in one process

​Workflow correlation

​Block-scoped identity with egisai.agent()

​Eager registration with egisai.register_agent()

​Resolution precedence

​What’s next

Multi-agent context

Agents

When to use it

Parameters

Returns

Examples

Multi-tenant FastAPI handler

Multiple sub-agents in one process

Workflow correlation

Block-scoped identity with `egisai.agent()`

Eager registration with `egisai.register_agent()`

Resolution precedence

What’s next