> ## Documentation Index > Fetch the complete documentation index at: https://docs.base44.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. 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](/developers). # 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 ```bash theme={null} 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 1. Reads all agent files from the `base44/agents/` directory 2. Validates agent configurations 3. Displays the count of agents to be pushed 4. Asks for confirmation before replacing remote agents (unless `-y`/`--yes` is passed) 5. Uploads agents to the Base44 backend 6. 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: ```bash theme={null} $ 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 ```bash theme={null} $ 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: ```bash theme={null} $ npx base44 agents push No local agents found - this will delete all remote agents ``` If an agent has an invalid name: ```bash theme={null} $ 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: ```jsonc theme={null} { "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](#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 | ```jsonc theme={null} "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`: ```jsonc theme={null} { "name": "my_agent", "tools": [ // ❌ WRONG { "type": "entity_query", "entity": "Task" } ] } ``` **CORRECT** - Use `tool_configs` with `entity_name` and `allowed_operations`: ```jsonc theme={null} { "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: ```jsonc theme={null} { "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