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-levelHumanInTheLoopAgent, 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:
- Gate evaluation: When a model calls a mutative or external tool (a tool whose name starts with
create_,update_,delete_,run_, oradd_, or a non-read-onlyquery_snowflakecall; MCP tools are judged by name like any other tool),approval_gatecallstool_context.request_confirmation(hint=...)and setstool_context.actions.skip_summarization = True. The gate is skipped when the session state key_approval_modeisfull-accessand no confirmation answer exists yet.AgentRunner.runwrites that key throughstate_deltaon every turn from the request’sapproval_mode, defaulting tofull-accesswhen omitted. - Turn suspension: The ADK run halts immediately without invoking the model to summarize or explain prematurely. An
approval_requiredSSE event is emitted to the client. - Turn resumption: Upon user approval or rejection,
POST /api/conversations/{id}/approvals/{approvalId}submits aFunctionResponsematching the confirmation call. Parallel pending confirmations are resumed together: the optionaldecisionslist adds oneFunctionResponseper extra approval to the sameContent, 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 infull-access. The executor updates the assistant turn in-place and streams the execution result back to the user.
- Identity.
- Mission.
- Methodology.
- Boundaries.
- Examples.
Tool reference formats
Thetools array on an agent can contain:
Workflow executor
ADKWorkflowExecutor.execute() runs graph workflows and returns JSON: