How It Works

This document describes the end-to-end execution flow of an agent task, from schedule trigger to completion.

Execution Flow

Step 1: Schedule Trigger

Cloud Scheduler fires according to the task's cron expression and enqueues a message in Cloud Tasks. The message targets the executor's /internal/agent/execute endpoint with an OIDC token scoped to the executor's service account. This ensures that only authenticated, Google-signed requests can initiate executions.

Cloud Scheduler (cron)
    |
    v
Cloud Tasks (queue: agent-executions)
    |
    v
POST /internal/agent/execute
  Headers:
    Authorization: Bearer <OIDC token>
  Body:
    { "task_id": "abc123", "user_id": "uid_456" }

Step 2: Load Task

The executor loads the task document from Firestore at agent_tasks/{task_id}. This includes the full task configuration: prompts, model, tools, integrations, schedule metadata, and limits.

If the task is disabled, deleted, or the owning user has insufficient credits, the executor aborts immediately and records a failed execution with the reason.

Step 3: Decrypt Credentials

Credentials are stored in a subcollection agent_tasks/{task_id}/credentials/{key} as KMS-encrypted ciphertext. The executor service account has cloudkms.cryptoKeyVersions.useToDecrypt permission on the agent KMS key, but not the encrypt permission. The bridge service account (used by Cloud Functions during credential storage) has encrypt-only access. This split-trust model ensures no single service account can both write and read credential material.

Decrypted credentials are held in memory only for the duration of the execution and are never written to logs or persisted in plaintext.

Step 4: Content Moderation

Before any LLM call, the executor runs the task's system_prompt and task_prompt through a prompt security scanner. The scanner applies regex-based detection for:

• Infrastructure provisioning commands (Terraform, CloudFormation, gcloud).

• Cryptocurrency mining instructions.

• Reverse shell patterns.

• Data exfiltration instructions.

• Attempts to override safety preambles.

If the scanner flags the prompt, the execution is aborted with status failed and reason content_moderation.

Step 5: Build Messages

The executor constructs the LLM message array:

1. Safety preamble -- system-level instructions that constrain the agent's behavior, prohibit credential leakage, and define tool usage rules.

2. Credential context -- a list of available credential names (not values) so the agent knows which credential parameter to pass to api_call.

3. System prompt -- the task's system_prompt field.

4. Task prompt -- the task's task_prompt field, optionally with variable substitutions (e.g., {{date}}, {{execution_id}}).

Step 6: Agentic Loop

The core of the executor is a loop that alternates between LLM inference and tool execution:

                    +---------------------+
                    |  Build messages     |
                    +---------------------+
                              |
                              v
              +-------------------------------+
              |  POST /internal/agent/code    |
              |  (main API, charges credits)  |
              +-------------------------------+
                              |
                              v
                    +-------------------+
                    |  Parse response   |
                    +-------------------+
                              |
                   +----------+----------+
                   |                     |
                   v                     v
          +----------------+    +-----------------+
          |  Tool calls?   |    |  No tool calls  |
          |  Yes           |    |  (final answer) |
          +----------------+    +-----------------+
                   |                     |
                   v                     v
          +----------------+    +-----------------+
          |  Execute tools |    |  Save output    |
          |  (parallel)    |    |  Complete exec  |
          +----------------+    +-----------------+
                   |
                   v
          +--------------------+
          |  Append tool       |
          |  results to        |
          |  messages           |
          +--------------------+
                   |
                   v
          +--------------------+
          |  Check limits:     |
          |  - iterations      |
          |  - credits         |
          |  - timeout         |
          |  - API call count  |
          +--------------------+
                   |
          +--------+--------+
          |                 |
          v                 v
     Limits OK?        Limits hit
          |                 |
          v                 v
     Loop back to      Save partial
     LLM call          output, complete
                       with status
                       "timeout" or
                       "limit_exceeded"

The LLM call is made to the main API at POST /internal/agent/code. The request body includes the user_id, so credits are deducted from the task owner's account. The executor does not deduct credits directly.

Tool calls within a single iteration are executed in parallel when they have no dependencies. Results are wrapped in <tool_response> tags and appended to the message history before the next LLM call.

Step 7: Save Execution Record

On completion (or failure), the executor writes an execution document to agent_tasks/{task_id}/executions/{execution_id} with the full trace: iterations consumed, credits used, tool call log, final output, and status.

The task document itself is updated with last_execution_id, last_execution_status, and last_executed_at.

Credit Charging

Credits flow through the main API, not the executor:

Executor  --->  POST /internal/agent/code (main API)  --->  Deduct credits from user_id

Each LLM call within the agentic loop is a separate credit charge. The executor tracks cumulative credits and aborts if the per-execution limit is reached.

Plan Limits

Execution limits are enforced based on the user's subscription plan:

Limit	Guru ($10/mo)	Pro ($50/mo)
Max iterations per execution	10	25
Max credits per execution	100	500
Execution timeout	10 minutes	30 minutes
Max API calls per execution	20	50
Max executions per minute	10	20

Free-tier users do not have access to the agent system. Upgrading to Guru or Pro unlocks agent functionality.

If any limit is reached during execution, the agent completes with whatever output it has produced so far. The execution record reflects the limit that was hit and partial results are preserved.

Failure Handling

Failure Mode	Behavior
Insufficient credits	Execution aborted before LLM call, status failed
Content moderation flag	Execution aborted, status failed, reason content_moderation
LLM call error	Retry once, then abort with status failed
Tool execution error	Error message returned to LLM as tool result; loop continues
Timeout	Execution completes with partial output, status timeout
Iteration/credit limit	Execution completes with partial output, status limit_exceeded
Unhandled exception	Execution marked failed, error logged to Cloud Logging