Platform Architecture
Four services work together to package, deploy, execute, and coordinate AI agents.
Agent Packager
Configuration bundling
Collects an agent's tools, actions, message schemas, and knowledge into a self-contained package by combining project settings, template config, and agent overrides.
- Generates master system prompt with all capabilities
- Includes Q&A knowledge base for context
- Packages environment variables and secrets references
Agent Brain
AI execution engine
The runtime inside each agent container. Processes tasks by calling your configured LLM (OpenAI, Anthropic, etc.), executing tool calls, and sending messages to other agents.
- Iterative task processing with tool execution
- Built-in send_message and update_status tools
- Tracks token usage for billing
Agent Runner
In-container job processor
Each container runs its own job processor that polls the database for pending jobs and executes them locally using the LLM. No external dispatch needed.
- Container polls for its own jobs directly
- Processes jobs using local LLM (Agent Brain)
- Updates job status on completion
Message Router
Inter-agent routing
Routes messages between agents based on message schemas. When a message matches a configured route, it automatically creates jobs for target agents.
- Route messages by schema to multiple agents
- Notify users when messages match schemas
- Chain multi-agent workflows
Execution Flow
How a task moves through the system
Job Created
A job enters the agent_jobs table—either via API call, dashboard action, or message flow trigger. The job contains the input payload and target agent.
Container Picks Up Job
The agent's Cloud Run container polls for pending jobs. When it finds one assigned to this agent, it marks it as running and begins processing.
LLM Execution
The Agent Brain (running in the container) loads the packaged configuration, builds a prompt with the task, and calls the LLM directly.
Tool Execution Loop
If the LLM requests tool calls, the brain executes them (shell commands, HTTP requests, file operations, etc.) and adds results to context. This repeats until the task is complete.
Output Messages
The agent can send messages to other agents using the send_message tool. These messages are routed based on schema mappings, potentially starting new jobs for other agents.
Job Completion
The job is marked complete (or failed). The agent returns to idle state and the next queued job (if any) automatically starts.
Key Concepts
Tools
Tools give agents capabilities by installing CLI tools or MCP servers. Define the installation command and required environment variables:
- npmInstall Node.js CLI tools and MCP servers
- pipInstall Python packages and tools
- apt-getInstall system packages
- curlDownload and install binaries
{
"name": "supabase-cli",
"description": "Supabase CLI for database management",
"installation_command": "npm install -g supabase",
"setup_command": "supabase login --token ${SUPABASE_ACCESS_TOKEN}",
"required_env_vars": ["SUPABASE_ACCESS_TOKEN"],
"publish_to_marketplace": false
}Actions
Actions are custom scripts that agents can execute. Write Python, Shell, or JavaScript code with defined dependencies and environment variables.
Actions appear to the LLM as callable functions. Dependencies are automatically installed when the agent container is built.
{
"name": "sync_agent_config",
"description": "Sync configuration across agents",
"language": "python",
"code": "<your Python code here>",
"tool_dependencies": [],
"action_dependencies": ["httpx"],
"required_env_vars": ["API_SERVICE_KEY"],
"publish_to_marketplace": false
}Message Schemas
Message Schemas define structured communication formats between agents. Each field has a type, description, and required flag.
- stringText fields
- numberNumeric values
- booleanTrue/false flags
- arrayLists of values
{
"display_name": "Deployment Request",
"description": "Request to deploy code changes",
"schema_fields": [
{
"key": "branch",
"description": "Git branch name",
"type": "string",
"required": true
},
{
"key": "environment",
"description": "Target environment",
"type": "string",
"required": true
},
{
"key": "approval_required",
"description": "Requires human approval",
"type": "boolean",
"required": false
}
],
"publish_to_marketplace": false
}Message Router
The Message Router maps schemas to recipients. When a message using a schema is sent, it automatically routes to configured agents and users.
{
"message_schema_id": "schema-uuid",
"agent_ids": [
"agent-uuid-1",
"agent-uuid-2"
],
"recipient_user_ids": [
"user-uuid-1"
]
}Configuration Assembly
Agent packages are built by combining multiple configuration sources
The Agent Packager combines project settings, template configuration from your library, and agent-specific overrides into a single deployable package.
Security & Isolation
Container Isolation
Each agent runs in its own Cloud Run container with isolated filesystem, network, and process space.
Multi-Tenant Data
Row-level security in PostgreSQL ensures tenants can only access their own data. All queries filter by tenant_id.
Secrets Management
API keys and credentials stored in secrets vault. Injected at runtime, never included in package or logs.