Skip to main content

Actor Resolver

The actor resolver defines who is attempting the action at runtime in the Actra Python SDK.

It is one of the most important Python integration points because it connects Actra to your application’s identity model through ActraRuntime.set_actor_resolver()

runtime.set_actor_resolver(
    lambda ctx: {
        "role": ctx.user.role,
    }
)

Core Mental Model​

Actor = who is attempting the action

Typical actor identities include:

  • authenticated users
  • service accounts
  • internal automation
  • workflow systems
  • background workers
  • AI agents
  • admin tools

Policies reference these fields through the actor domain.

subject:
  domain: actor
  field: role

Basic Resolver​

The most common Python resolver maps authenticated user identity.

runtime.set_actor_resolver(
    lambda ctx: {
        "user_id": ctx.user.id,
        "role": ctx.user.role,
        "tenant": ctx.user.tenant,
    }
)

This is ideal for:

  • RBAC
  • tenant isolation
  • department routing
  • approval routing

FastAPI / Flask Request Resolver​

A common Python production pattern.

runtime.set_actor_resolver(
    lambda request: {
        "user_id": request.user.id,
        "role": request.user.role,
        "tenant": request.user.tenant,
    }
)

This makes Actra integrate naturally with request-scoped auth middleware.

AI Agent Identity​

One of Actra’s strongest modern Python use cases.

runtime.set_actor_resolver(
    lambda agent_ctx: {
        "agent": agent_ctx.name,
        "role": "tool_runner",
    }
)

This is ideal for:

  • tool gating
  • autonomous workflows
  • MCP tool execution
  • multi-agent governance
  • LLM safety boundaries

Service-to-Service Identity​

For internal platform systems.

runtime.set_actor_resolver(
    lambda ctx: {
        "service": ctx.service_name,
        "role": "internal_service",
    }
)

Excellent for:

  • microservices
  • internal APIs
  • deployment systems
  • CI bots
  • platform automation

Queue / Worker Identity​

Useful for Python job processors and background systems.

runtime.set_actor_resolver(
    lambda job: {
        "worker": job.queue_name,
        "role": "worker",
    }
)

Best for:

  • Celery workers
  • RQ jobs
  • Kafka consumers
  • cron jobs
  • ETL workflows

Missing Resolver Behavior​

If no actor resolver is configured, the runtime safely falls back to:

{}

This behavior comes directly from resolve_actor() in the runtime implementation.

This is safe, but usually insufficient for real authorization.

Best Practices​

Keep actor identity-focused​

Use actor only for:

  • identity
  • role
  • tenant
  • department
  • trust level
  • agent name

Avoid business state fields here.

Use stable field names​

Good:

"role"

Avoid unstable fields:

"latest_role_version"

Do not duplicate snapshot state​

Use:

  • actor → who
  • snapshot → current system state

This keeps policies deterministic and auditable.

Production Mental Model​

Request / Worker / Agent
 -> Resolve identity
 -> Build actor object
 -> Runtime evaluation

This is how the Python SDK connects Actra to real-world ident