The backend uses FastAPI, SQLAlchemy, PostgreSQL, and Google ADK. The active API surface is mounted under:
Route registration lives in:

Main backend modules

Agent run flow

ADKExecutor.execute() is the main runtime interface for chat-driven agent execution. It performs these steps:
1

Validate attachments

Multimodal inputs are checked before model execution.
  • Gemini Direct Document Bypass: If the agent runs on a Google Gemini provider model, PDF attachments bypass the traditional text-extraction/OCR pipeline and are passed directly as native multimodal document parts. This preserves layout, charts, formulas, and visual context.
  • Non-Gemini Providers: Standard OCR and plain text extraction pipelines are applied before passing text into the prompt.
2

Guard the prompt

Prompt extraction and prompt injection attempts are blocked before agent creation:
  • System One / JEV Guardrail Middleware: Analyzes incoming prompts for jailbreak attempts, delimiter hijacking, and prompt extraction patterns.
  • PII Redaction: Sensitive personal data patterns are automatically redacted based on the platform’s security policy.
  • Defense Modes: Configurable agent defense modes evaluate strictness of boundaries before delegating to the model.
3

Build the agent

AgentFactory loads the agent, model, tools, planner, and generation config.
4

Run the agent

AgentRunner streams events back to the client.
5

Persist the run

Messages, token usage, and traces are saved after execution completes.

Agent construction

AgentFactory.create_agent(agent_id) loads an agent record and creates the correct ADK agent type.

Runtime tool confirmation (HITL gate)

In addition to workflow-level HumanInTheLoopAgent, Pinter implements interactive, tool-call-level confirmation directly on standard agents. When building an agent, AgentFactory installs approval_gate as the first callback in the before_tool_callback chain:
  1. Gate evaluation: When a model calls a mutative or external tool (a tool whose name starts with create_, update_, delete_, run_, or add_, or a non-read-only query_snowflake call; MCP tools are judged by name like any other tool), approval_gate calls tool_context.request_confirmation(hint=...) and sets tool_context.actions.skip_summarization = True. The gate is skipped when the session state key _approval_mode is full-access and no confirmation answer exists yet. AgentRunner.run writes that key through state_delta on every turn from the request’s approval_mode, defaulting to full-access when omitted.
  2. Turn suspension: The ADK run halts immediately without invoking the model to summarize or explain prematurely. An approval_required SSE event is emitted to the client.
  3. Turn resumption: Upon user approval or rejection, POST /api/conversations/{id}/approvals/{approvalId} submits a FunctionResponse matching the confirmation call. Parallel pending confirmations are resumed together: the optional decisions list adds one FunctionResponse per extra approval to the same Content, so the model does not continue while others are still pending. An existing answer always wins over the mode, so a rejection is enforced even in full-access. The executor updates the assistant turn in-place and streams the execution result back to the user.
The factory also merges the 5-pattern instruction fields into a single instruction:
  1. Identity.
  2. Mission.
  3. Methodology.
  4. Boundaries.
  5. Examples.

Tool reference formats

The tools array on an agent can contain:

Workflow executor

ADKWorkflowExecutor.execute() runs graph workflows and returns JSON:
The workflow runtime validates the graph, compiles an execution plan, runs ready nodes, handles condition routing, prunes dead paths, and records node results.