Quick Start
This guide helps you quickly deploy your first Agent and master the complete process for local debugging and production deployment of session requests.
Starting from a Template
Go to the console, select the Agents tab, and navigate to the Agent template selection page. You can start with a framework-based template or directly choose a template that fits your business scenario.
When creating a project from a template for the first time, you need to select a Git platform. For information on how to connect a Git platform, refer to the document Import Git Repository. After configuring the project information, click Create Now.
The deployment process will start automatically. We will create a repository in your GitHub account based on this template. You can clone this repository locally for further development and push changes as needed.
Starting a Project from the CLI
1. Installing
Install the CLI using npm:
npm install -g edgeone
You can check whether the installation is successful by using the
edgeone -v command. You can view all related commands by using the edgeone -h command.2. Creating a Project
You can quickly create a basic template based on the OpenAI Agents SDK using the following command.
edgeone makers create --template openai-agents-starter-node
If a project with the same name already exists, you can manually specify a project name using the command: edgeone makers create [project-name] --template openai-agents-starter-node.
3. Local Debugging
By default, running the command starts a service on the local port 8088. Both the Makers Agent service and the frontend project service run on the same port, eliminating the need for an additional proxy.
edgeone makers dev
You can access the Agent page via
http://localhost:8088/.You can access the local observability and traceability page via
http://localhost:8088/agent-metrics.
Refactoring an Existing Agent Project
If you already have your own Agent project and want to migrate it to our platform, you can deploy it in just three steps.
1. Adjusting the Directory Structure
Makers Agents uses a dedicated directory and follows the file-as-route convention. The directory name defaults to agents/ and can be customized through project configuration. Place each Agent's entry file at
agents/<name>/index.{js,ts,py}:your-project/├── agents/│ ├── researcher/│ │ ├── index.py # Main entry: handler(context)│ │ └── stop.py # Optional: Interruption handling│ └── customer-service/│ └── index.js└── edgeone.json
Files or directories prefixed with an underscore are private modules and do not generate routes.
2. Refactoring the Entry Point and Configuration
For your business code, you only need to change the entry point to handler(context). The platform injects all capabilities through the context object, eliminating the need to import any platform SDK. Then, declare the framework and other runtime parameters in edgeone.json (for detailed configuration, refer to the section below).
TS Example
export async function onRequest(context: any) {// Your Agent business logic}
Python Example
# Agent Entry Pointasync def handler(context):# Your Agent Business Logic
3. On-Demand Access to Store/Sandbox
Capability | Access Prerequisite | Documentation |
Conversation Storage | Requires the Agent to have memory capability. | |
Sandbox Tool | Access when you need to run commands / read/write files / operate a browser / run code. |
Local Debugging
1. Associating a Project
To synchronize the environment variables already configured in the console to your local debugging environment, run the link project command and enter the project name as prompted. The project name here refers to the Makers project name you created during the preparation phase.
edgeone makers link
2. Local Development
Go to the project root directory and run:
edgeone makers dev
The CLI starts the following simultaneously:
1. Local HTTP server (default:
http://localhost:8080)2. Local observability dashboard (default:
http://localhost:8080/agent-metrics)Deploying to Production
Git Deployment (Recommended)
1. Push your code to a remote repository (GitHub, Gitee, or Coding).
2. Import the project to EdgeOne Makers.
3. EdgeOne Makers automatically builds, deploys, and generates an online URL.
After your project is imported and deployed, a new deployment is automatically triggered for all commits to the specified production branch (default: "main"). See Git Integration for more information.
CLI Deployment
1. Install EdgeOne CLI and initialize it.
2. Run
edgeone makers deploy -n <project name> to deploy.npm install -g edgeoneedgeone loginedgeone makers deploy -n vite-react-demo
After a successful deployment, click the link in the Console to access the detailed build information and the deployed URL.
Session Management
The platform uses a
conversation_id to identify a continuous conversation, and all requests must carry it in the request header. It simultaneously drives three functions: session-sticky routing (agents/), conversation storage ownership (agents/ + cloud-functions/), and sandbox instance ownership (one sandbox per conversation).Generation Method
The client / business backend generates and maintains a globally unique ID (a UUID is sufficient) when creating a new conversation. When continuing a historical conversation, it directly retrieves and reuses the original
conversation_id.// Business generation (recommended): Use a UUID to guarantee global uniqueness and avoid conflicts.const conversationId = `conv_${crypto.randomUUID().replace(/-/g, '')}`;
Carrying Request Headers
Consistently pass it using the request header
Makers-Conversation-Id (required for all agents/* calls). It is recommended to globally inject it in the frontend fetch interceptor to avoid repetitive writing at each call point.// Invoke Agentawait fetch('/customer-service', {method: 'POST',headers: {'Content-Type': 'application/json','Makers-Conversation-Id': conversationId,}})
Request Header Format and Errors
The
Makers-Conversation-Id must meet the following requirements: a length of 6 to 36 characters, and only the characters 0-9, a-z, A-Z, -, _, and . are allowed. When the request header is missing or invalid, the Agent router returns a 400 error.Agent requests are also subject to concurrent session and site frequency limits. When a limit is exceeded, a
429 error is returned. Retry after backing off for the duration specified in the Retry-After response header. For a complete list of error codes, see Error Codes.edgeone.json Configuration
The
edgeone.json file in the project root directory controls the runtime parameters for the Agent and the sandbox:{"agents": {"framework": "openai-agents-sdk", // claude-agent-sdk / openai-agents-sdk / langgraph / crewai / deepagents"dir": "agents", // Optional. Defaults to "agents"."timeout": 300, // Optional. The maximum duration in seconds for a single run (30 ~ 3600)."sandbox": {"timeout": 300 // Optional. The maximum lifetime in seconds for a sandbox instance (300 ~ 3600).}}}
Field | Feature |
agents.framework | Determines the framework adaptation form of context.store / context.tools |
agents.dir | Agent source code directory, default agents/ |
agents.timeout | Maximum execution seconds for a single task |
agents.sandbox.timeout | Sandbox instance survival duration |