Custom HTTP endpoints

Add custom endpoints when your application needs a business-specific HTTP contract in addition to Harnest’s neutral API. The same extension works with managed or advanced ADK and LangGraph agents.

Add an endpoint

Create a synchronous route factory in the root agent’s lifecycle/ directory. Harnest injects an AgentInvoker and mounts the returned FastAPI router.

lifecycle/http.py

from fastapi import APIRouter, Request
from harnest.http import AgentInvoker
from harnest import lifecycle

@lifecycle.http_routes
def http_routes(agent: AgentInvoker):
    router = APIRouter(prefix="/threadify")

    @router.post("/execute")
    async def execute(payload: dict, request: Request):
        response = await agent.invoke(
            connection=request,
            input=payload["message"],
            session_id=payload.get("sessionId"),
            metadata={"source": "threadify"},
        )
        return {
            "sessionId": response.session_id,
            "status": response.status,
            "answer": response.output_text,
            "result": response.result,
            "requiredAction": response.required_action,
        }

    return router

The factory can return multiple routes or use FastAPI dependencies. Define route factories only at the root. SubAgents do not own server paths.

Invoke the agent safely

AgentInvoker uses the same response coordinator as POST /responses. It does not call the raw ADK or LangGraph object.

Behavior	Custom endpoint result
Authentication	Harnest derives identity from `connection`; callers cannot supply `user_id`
Session omitted	Harnest creates a user-scoped session
Session supplied	Harnest verifies that the authenticated caller owns it
Input schema	Harnest validates the configured Pydantic input model
Runtime capability grants	Trusted route code can pass `agent_principal=`
Lifecycle and credentials	The normal invocation bindings run
Approval or client tool	`status` is `requires_action` and `required_action` describes the continuation
Telemetry and limits	Standard tracing, logging, timeout, concurrency, and request-size policy applies

Pass the current FastAPI Request as connection. Do not accept or construct a user_id from the request body.

After authenticating the request, your route can derive an invocation-specific tool surface:

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),
)

With the default server configuration, omitting a principal leaves the tool surface unrestricted. Supplying one enables default-deny checks; an empty principal permits no governed capabilities. Never take permission names directly from request input. See Agent Runtime Principals. For a security-sensitive deployment, require grants on every custom agent invocation:

config.yaml

server:
  agentPrincipal: required

With this setting, a custom route that omits agent_principal= fails before session creation. Built-in routes also need a grant hook; they cannot use a principal constructed inside your custom route.

Handle required actions

An invocation can pause instead of returning a final answer:

response = await agent.invoke(connection=request, input=payload["message"])

if response.status == "requires_action":
    return {
        "status": response.status,
        "requiredAction": response.required_action,
    }

Resume human approvals through POST /approvals/{approvalId}. Submit browser-hosted tool results through POST /client-tools/{requestId}. These endpoints share the same suspended execution created by the custom route. Use response.as_dict() when your endpoint should return Harnest’s complete neutral response shape unchanged.

Add an application-specific session view

Keep business dimensions such as site origin, workspace, inbox, or project out of the neutral /sessions contract. Add an authenticated custom endpoint and query an application-owned index instead:

lifecycle/http.py

from fastapi import APIRouter, Request
from harnest.http import AgentInvoker
from harnest import lifecycle
from harnest.auth import principal_for
from harnest.lib.site_sessions import site_sessions

@lifecycle.http_routes
def site_session_routes(_agent: AgentInvoker):
    router = APIRouter(prefix="/sites")

    @router.get("/{origin}/sessions")
    async def sessions(
        origin: str,
        request: Request,
        cursor: str | None = None,
        limit: int = 50,
    ):
        principal = principal_for(request)
        return await site_sessions.list(
            user_id=principal.user_id,
            origin=origin,
            cursor=cursor,
            limit=min(max(limit, 1), 100),
        )

    return router

site_sessions is your indexed repository. Scope it by authenticated user_id and update it when sessions acquire an origin.

Do not fetch one bounded /sessions page and filter it locally. Matching sessions may exist on later pages, and sorting a page is not the same as sorting the complete filtered result.

Route ownership

Compilation rejects duplicate routes and Harnest-owned namespaces. Reserved paths include /responses, /sessions, /live, /approvals, /client-tools, /agent, /healthz, playground assets, OpenAPI pages, and ADK-native run or application routes. When you configure authentication, custom routes are protected by default. They also appear in /openapi.json. Harnest does not currently provide streaming through AgentInvoker; use the neutral SSE or WebSocket APIs when you need streaming. See Neutral API, Approvals and client tools, and Authentication and credentials.

API reference

Reference: harnest.agent, harnest.auth.

Overview

Get started

Harnest Studio

Guides

API reference

Custom HTTP endpoints

Add an endpoint

Invoke the agent safely

Handle required actions

Add an application-specific session view

Route ownership

API reference

​Add an endpoint

​Invoke the agent safely

​Handle required actions

​Add an application-specific session view

​Route ownership

​API reference

Add an endpoint

Invoke the agent safely

Handle required actions

Add an application-specific session view

Route ownership

API reference