Agent Runtime Principals

An AgentRuntimePrincipal limits an invocation to explicitly permissioned capabilities. Create it in trusted code after authenticating the caller or selecting a job’s service identity.

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.

Grant permissions on built-in routes

Define one grant hook in the root agent’s lifecycle/ directory. Harnest passes it the connection and the identity established by authentication. Use verified claims or look up permissions in your application.

lifecycle/grants.py

from harnest import lifecycle
from harnest.agent import AgentRuntimePrincipal
from harnest.auth import AuthPrincipal, ConnectionContext

@lifecycle.http.agent_principal
def grant(connection: ConnectionContext, principal: AuthPrincipal) -> AgentRuntimePrincipal:
    permissions = {"refunds.write"} if principal.claims.get("can_refund") is True else set()
    return AgentRuntimePrincipal.create(permissions=permissions)

This example lets any caller start a turn, but only callers with the verified refund claim can use tools tagged refunds.write. Return None to deny the invocation entirely. The hook may also be async. The hook covers /responses (including streaming), AG-UI, live WebSocket connections, and A2A. Live resolves the grant at the handshake; resumed runs keep their original grants. Without a hook these routes keep their previous tool surface unless server.agentPrincipal: required is set. With that setting, these Harnest routes refuse new invocations without a principal. In advanced ADK mode, native /run, /run_sse, and /run_live invocations bypass this hook, including when grants are required. Apply separate authorization if you expose those endpoints.

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 the server requires grants for that HTTP invocation
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. Native tools and graph paths you wire directly can bypass Harnest checks. Enforce equivalent policy there or at a downstream gateway.

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.

API reference

Reference: harnest.mcp.

Overview

Get started

Harnest Studio

Guides

API reference

Agent Runtime Principals

Mark permissioned capabilities

Grant permissions on built-in routes

Invoke with a principal

Understand omission and propagation

Managed and advanced modes

API reference

​Mark permissioned capabilities

​Grant permissions on built-in routes

​Invoke with a principal

​Understand omission and propagation

​Managed and advanced modes

​API reference

Mark permissioned capabilities

Grant permissions on built-in routes

Invoke with a principal

Understand omission and propagation

Managed and advanced modes

API reference