Backend and ADK architecture

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

/api/v2

Route registration lives in:

pinter-be/routes/v2/__init__.py

Main backend modules

Module	Path	Responsibility
Routes	`routes/v2`	HTTP interface for agents, conversations, tools, users, quotas, and admin operations.
Agent executor	`modules/adk/executor_v2.py`	Coordinates factory, runner, persistence, prompt guard, and SSE output.
Agent factory	`modules/adk/agent_factory_v2.py`	Builds ADK agents from DB config.
Tool registry	`modules/adk/tool_registry_v2.py`	Resolves tool references to ADK-compatible tools.
Workflow executor	`modules/adk/ADKWorkflowExecutor.py`	Runs graph workflows with validation, planning, node execution, and state.
Workflow compiler	`modules/adk/workflow/compiler.py`	Converts graph data into an execution plan.
Session config	`modules/adk/session_config.py`	Configures ADK session service.
Evaluation	`modules/adk/evaluation_v2.py`	Runs evaluation sets and stores results.

Agent run flow

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

Validate attachments

Multimodal inputs are checked before model execution.

Guard the prompt

Prompt extraction attempts are blocked before agent creation.

Build the agent

AgentFactoryV2 loads the agent, model, tools, planner, and generation config.

Run the agent

AgentRunner streams events back to the client.

Persist the run

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

Agent construction

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

Agent type	Implementation
Standard LLM agent	`LlmAgent`
Sequential workflow	`SequentialAgent`
Parallel workflow	`ParallelAgent`
Loop workflow	`LoopAgent`
Conditional workflow	`ConditionalAgent`
Human-in-the-loop workflow	`HumanInTheLoopAgent`

The factory also merges the 5-pattern instruction fields into a single instruction:

Identity.
Mission.
Methodology.
Boundaries.
Examples.

Tool reference formats

The tools array on an agent can contain:

Format	Meaning
`google_search`	ADK Google Search built-in.
`code_execution`	ADK code execution configuration.
`<uuid>`	Tool row from `tools`.
`agent:<uuid>`	Another agent wrapped as a tool.
`mcp:<uuid>`	Legacy MCP tool config from `tools`.
`mcp_server:<uuid>`	MCP server from `mcp_servers`.

Workflow executor

ADKWorkflowExecutor.execute() runs graph workflows and returns JSON:

{
  "status": "success",
  "output": "Final response",
  "history": [],
  "total_token_usage": {},
  "debug_state_keys": [],
  "workflow_run_id": "uuid",
  "node_runs": []
}

The workflow runtime validates the graph, compiles an execution plan, runs ready nodes, handles condition routing, prunes dead paths, and records node results.

Get started

Architecture

Core workflows

Administration

Reference

Backend and ADK architecture

Main backend modules

Agent run flow

Agent construction

Tool reference formats

Workflow executor

​Main backend modules

​Agent run flow

​Agent construction

​Tool reference formats

​Workflow executor

Main backend modules

Agent run flow

Agent construction

Tool reference formats

Workflow executor