Agent Runtime Principals

An AgentRuntimePrincipal establishes a default-deny boundary for Harnest-governed capabilities during one invocation. A server tool, client-hosted tool, or MCP operation is available only when it declares a permission carried by the principal. Create the principal in trusted application code after authenticating the caller or deciding which service identity a job should use.

from harnest.agent import AgentRuntimePrincipal


agent_principal = AgentRuntimePrincipal.create(
    permissions={"tickets.read", "tickets.comment"},
)

The generated id is an opaque runtime identity. Your application remains the source of user, tenant, role, and policy decisions.

Concern	Owner
Agent capability definition	Your Harnest project
Permission grants for this execution	Your application
Capability projection and execution checks	Harnest-owned runtime boundaries
Final authorization of an external action	Your gateway or downstream service

Do not derive permissions from model output or an untrusted request field. Authenticate at your application or gateway boundary, then construct the principal in trusted code.

Mark permissioned capabilities

Every capability that should remain available under a principal must declare a permission. Server and client-hosted tools accept one permission identifier:

from harnest.agent import tool


@tool(permission="tickets.read")
async def read_ticket(ticket_id: str) -> dict:
    """Read one support ticket."""

    return await tickets.get(ticket_id)

from harnest.agent import client_tool


@client_tool(permission="tickets.admin")
def open_admin_console(ticket_id: str) -> dict:
    """Open one ticket in the local administration UI."""

    ...

An MCP client can require a permission for every remote tool and add requirements to individual tools:

mcp/catalog.py

import os

from harnest.mcp import MCPClient


def client():
    return MCPClient.streamable_http(
        os.environ["CATALOG_MCP_URL"],
        permission="catalog.connect",
        tool_permissions={
            "search_products": "catalog.search",
            "update_product": "catalog.write",
        },
    )

permission= applies to every tool from that client. A matching tool_permissions entry is an additional requirement. Permission identifiers start with a letter and can contain letters, numbers, ., _, :, or -. When you omit the client-wide permission, only operations named in tool_permissions can be available under a principal. Untagged MCP operations remain unavailable.

Invoke with a principal

Pass the principal through a trusted custom HTTP endpoint:

from harnest.agent import AgentRuntimePrincipal


permissions = application_permissions_for(authenticated_user)
response = await agent.invoke(
    connection=request,
    input=payload["message"],
    agent_principal=AgentRuntimePrincipal.create(permissions=permissions),
)

You can also pass agent_principal= to an in-process AgentSession.invoke(...) or AgentSession.stream(...) call. Harnest removes untagged and unmatched capabilities from Harnest-owned model tool surfaces and checks the permission again at execution. Treat the execution check as defense in depth. The downstream service must still authorize the actual operation.

Understand omission and propagation

Situation	Behavior
Root invocation omits `agent_principal`	Compatibility mode; the existing capability surface remains available unless a custom route uses `server.agentPrincipal: required`
Root invocation receives an empty principal	Every Harnest-governed capability is unavailable
Active principal encounters an untagged capability	Capability is unavailable
Nested agent call omits it	Inherits the active principal
Nested agent call supplies a subset	Uses the narrower principal
Nested agent call attempts to add permissions	Fails before execution
A restricted invocation defers a Task	Persists permission names and reconstructs a fresh principal in the worker
A restricted invocation suspends on external work	Persists a private versioned permission-name snapshot and reconstructs a fresh principal on the resuming replica
A scheduled Task invokes an agent without one	Uses an empty principal and fails closed for permissioned capabilities

Queued Task and external-continuation states contain only permission identifiers. They do not serialize the principal ID, authentication claims, or credentials. A scheduled Task can construct and pass an explicit service principal in trusted task code when it needs declared capabilities.

Managed and advanced modes

Mode	Guarantee
Managed	Harnest requires complete capability projection and fails before execution when the managed topology cannot provide it
Advanced	Best-effort enforcement at boundaries Harnest owns

In advanced mode, Harnest enforces the principal for Harnest-decorated server tools, client-hosted tools, configured MCP clients, local agent invocation, and queued Task propagation when those operations cross Harnest runtime boundaries. Harnest does not rewrite a native graph, inspect every framework plugin, or wrap tools that you wire directly into your own agent graph. Those user-owned paths remain your responsibility and can bypass runtime-principal projection. Enforce equivalent policy in the native graph or downstream gateway when you need complete coverage.

The principal is private runtime state rather than a property on harnest.context. Tools and extensions declare required permissions; they do not read or make policy decisions from the active principal.

Overview

Get started

Guides

Agent Runtime Principals

Mark permissioned capabilities

Invoke with a principal

Understand omission and propagation

Managed and advanced modes

​Mark permissioned capabilities

​Invoke with a principal

​Understand omission and propagation

​Managed and advanced modes

Mark permissioned capabilities

Invoke with a principal

Understand omission and propagation

Managed and advanced modes