This page is part of an AI coding agent skill and is written for agents, not humans. For the human-readable Base44 docs, see the developer documentation.

base44 agents push

Push local AI agent configurations to Base44. Agents are conversational AI assistants that can interact with users, access your app’s entities, and call backend functions.

Syntax

npx base44 agents push [options]

Options

Option	Description	Required
`-y, --yes`	Skip confirmation prompt	No

Authentication

Required: Yes. If not authenticated, you’ll be prompted to login first.

What It Does

Reads all agent files from the base44/agents/ directory
Validates agent configurations
Displays the count of agents to be pushed
Asks for confirmation before replacing remote agents (unless -y/--yes is passed)
Uploads agents to the Base44 backend
Reports the results: created, updated, and deleted agents

Prerequisites

Must be run from a Base44 project directory
Project must have agent definitions in the base44/agents/ folder

Confirmation Prompt

This is a destructive, full-sync push: any remote agent not present locally is deleted. Before pushing, the CLI warns you and asks for confirmation:

$ npx base44 agents push

Found 2 agents to push
⚠ This will replace all remote agent configs with your local agents and delete any not present locally.
? Are you sure you want to continue? › Yes

In non-interactive mode (--json, CI/CD, no TTY), you must pass -y/--yes or the command throws.

Output

$ npx base44 agents push --yes

Found 2 agents to push
Pushing agents to Base44...

Created: support_agent
Updated: order_bot
Deleted: old_agent

✓ Agents pushed to Base44

Agent Synchronization

The push operation synchronizes your local agents with Base44:

Created: New agents that didn’t exist in Base44
Updated: Existing agents with modified configuration
Deleted: Agents that were removed from your local configuration

Warning: This is a full sync operation. Agents removed locally will be deleted from Base44.

Error Handling

If no agents are found in your project:

$ npx base44 agents push
No local agents found - this will delete all remote agents

If an agent has an invalid name:

$ npx base44 agents push
Error: Agent name must be lowercase alphanumeric with underscores

Agent Configuration Schema

Each agent file should be a .jsonc file in base44/agents/ with this structure:

{
  "name": "agent_name",              // Required: lowercase alphanumeric with underscores, 1-100 chars
  "description": "Brief description of what this agent does",  // Required: min 1 char
  "instructions": "Detailed instructions for the agent's behavior",  // Required: min 1 char
  "tool_configs": [                  // Optional: defaults to []
    // Entity tool - gives agent access to entity operations
    { "entity_name": "Task", "allowed_operations": ["read", "create", "update", "delete"] },
    // Backend function tool - gives agent access to a function
    { "function_name": "send_email", "description": "Send an email notification" }
  ],
  "memory_config": {                 // Optional: lets the agent remember facts across conversations
    "enabled": true,                 // Optional: defaults to true
    "scope": "both",                 // Optional: "global" | "user" | "both", defaults to "both"
    "include_other_conversation_context": false,  // Optional: defaults to false
    "instructions": null             // Optional: string or null, custom guidance on what to remember
  },
  "whatsapp_greeting": "Hello! How can I help you today?"  // Optional
}

Naming rules:

Agent names must match pattern: /^[a-z0-9_]+$/ (lowercase alphanumeric with underscores only, 1-100 characters)
- Valid: support_agent, order_bot, task_helper
- Invalid: Support-Agent, OrderBot, task helper
Agent file names must use underscores (matching the agent name)
- Valid: support_agent.jsonc, order_bot.jsonc
- Invalid: support-agent.jsonc (hyphens not allowed)
Entity names in tool_configs must use PascalCase (matching the entity’s name field)
- Valid: "entity_name": "Task", "entity_name": "TeamMember"
- Invalid: "entity_name": "task", "entity_name": "team_member"

Required fields:

name: Required, must follow naming rules above
description: Required, minimum 1 character
instructions: Required, minimum 1 character
tool_configs: Optional, defaults to empty array
memory_config: Optional, see Memory Configuration below
whatsapp_greeting: Optional

Memory Configuration

memory_config lets an agent remember facts across conversations. To disable memory, set "enabled": false explicitly — if you omit memory_config entirely, the backend applies its default and memory is enabled.

Field	Type	Default	Description
`enabled`	boolean	`true`	Whether the agent retains memory across conversations
`scope`	`"global"` \| `"user"` \| `"both"`	`"both"`	`"global"` shares memory across all end users, `"user"` scopes memory to each individual end user, `"both"` does both
`include_other_conversation_context`	boolean	`false`	Whether the agent can also draw on context from the user’s other conversations
`instructions`	string \| `null`	`null`	Optional custom instructions guiding what the agent should remember

"memory_config": {
  "enabled": true,
  "scope": "user",
  "include_other_conversation_context": false,
  "instructions": "Remember the user's preferred name and timezone."
}

Common Mistake: Wrong tool_configs Format

WRONG - Do NOT use tools with type and entity:

{
  "name": "my_agent",
  "tools": [                                    // ❌ WRONG
    { "type": "entity_query", "entity": "Task" }
  ]
}

CORRECT - Use tool_configs with entity_name and allowed_operations:

{
  "name": "my_agent",
  "tool_configs": [                             // ✅ CORRECT
    { "entity_name": "Task", "allowed_operations": ["read"] }
  ]
}

Best Practices for Agent Instructions

When giving agents access to entities, be explicit in the instructions about using the tools:

{
  "name": "support_agent",
  "instructions": "You are a helpful support agent.\n\nIMPORTANT: You have access to customer data through entity tools. When users ask about their orders or account:\n1. ALWAYS use the Order entity tool to query their order history\n2. Use the Customer entity tool to look up account details\n3. Analyze the data and provide personalized responses\n\nAlways query the relevant entities first before answering questions about user data.",
  "tool_configs": [
    { "entity_name": "Order", "allowed_operations": ["read"] },
    { "entity_name": "Customer", "allowed_operations": ["read"] }
  ]
}

Without explicit instructions to use the entity tools, the agent may not proactively query user data when asked.

Use Cases

After defining new agents in your project
When modifying existing agent configurations
To sync agent changes before testing
As part of your development workflow when agent behavior changes

Notes

This command syncs the agent configuration, not conversation data
Changes are applied to your Base44 project immediately
Make sure to test agent changes in a development environment first
Agent definitions are located in the base44/agents/ directory
Use base44 agents pull to download agents from Base44

​base44 agents push

​Syntax

​Options

​Authentication

​What It Does

​Prerequisites

​Confirmation Prompt

​Output

​Agent Synchronization

​Error Handling

​Agent Configuration Schema

​Memory Configuration

​Common Mistake: Wrong tool_configs Format

​Best Practices for Agent Instructions

​Use Cases

​Notes

base44 agents push

Syntax

Options

Authentication

What It Does

Prerequisites

Confirmation Prompt

Output

Agent Synchronization

Error Handling

Agent Configuration Schema

Memory Configuration

Common Mistake: Wrong tool_configs Format

Best Practices for Agent Instructions

Use Cases

Notes