> For the complete documentation index, see [llms.txt](/llms.txt). > A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt). --- title: Local development description: Run your worker locally with agnt5 dev, reload it as you edit, and trigger it from Studio, the CLI, or the API. last_verified: 2026-10-06 --- `agnt5 dev` runs your worker on your machine and connects it to AGNT5. Once it is running, you can trigger workflows, functions, tools, and agents from Studio in the browser, from the CLI, or over the API. The examples on this page use the travel booking template. --- ## Run your worker Run `agnt5 dev` from your project root. It starts the worker command from your `agnt5.yaml` and registers everything your project defines. **Prerequisites:** - Dependencies installed: **Python:** ```bash uv sync ``` **TypeScript:** ```bash npm install ``` **Go:** ```bash go mod download ``` - Your API keys in a `.env` file in the project root. `agnt5 dev` loads it for the worker: ```bash OPENAI_API_KEY=sk-... ``` **Start:** ```bash agnt5 dev ``` The terminal shows the dev session, your project, the worker command, the coordinator it connected to, the directories being watched, and your Studio link, followed by the components that registered: ``` ╭──────────────────────────────────────────────────╮ │ ⭓ agnt5 dev │ │ 20261006-aedffb · managed │ │ ~/projects/travel_booking │ ╰──────────────────────────────────────────────────╯ session travel_booking (directory name) project travel-booking worker uv run --no-sync python app.py (pid 25762) coordinator http://grpc.agnt5.com:3418 watch 6 dirs · .py .ts .js .go .env studio https://app.agnt5.com/projects//environment/local/session/travel_booking/components customer-service v1.0.0 ──────────────────────────────────────── ◆ workflows (1) └── travel_booking_workflow ● agents (1) └── travel_booking_agent ◇ tools (3) ├── create_itinerary ├── search_flights └── search_hotels ──────────────────────────────────────── ``` Each project's `agnt5.yaml` sets the worker command, for example `uv run --no-sync python app.py` for Python, `npx tsx app.ts` for TypeScript, and `go run .` for Go. **Studio:** the banner prints a `studio` link for your dev session. Open it to launch the browser UI. From there you can trigger workflows, run individual functions and agents, and watch traces, all without writing any extra code. ### Reload as you edit `agnt5 dev` watches your project (`.py`, `.ts`, `.js`, `.go`, and `.env` files) and restarts the worker when something changes, whether it runs in the foreground or the background: - **Code changes:** save a source file and the worker restarts and re-registers, usually within a couple of seconds. - **Environment variable changes:** update your `.env` and the worker restarts with the new values, usually within a couple of seconds. Pass `--no-watch` to turn file watching off. ### Run in the background Add `-d` to start the worker in the background, and manage it with these commands: ```bash agnt5 dev -d # start the worker in the background agnt5 dev status # show the session, worker, and Studio link agnt5 dev logs # show the worker logs (-f to follow, -n to set the line count) agnt5 dev stop # stop it ``` > Set deployment secrets separately when you deploy, for example with `agnt5 secrets set --name OPENAI_API_KEY --type api_key --stdin`. --- ## Studio Studio is the browser UI for triggering workflows, watching traces, and responding to human-in-the-loop pauses. Open it with the `studio` link that `agnt5 dev` prints when it starts. ### Triggering a workflow 1. Open the `studio` link from the terminal in your browser. 2. Select `travel_booking_workflow` from the workflow list. 3. Set the input: ```json { "message": "2 adults are traveling from Los Angeles (LAX) to New York (JFK), departing on June 28, 2026, and returning on June 30, 2026." } ``` 4. Click **Run workflow**. The run appears immediately in the Runs view. Click into it to see the live trace. ### Watching a trace As the workflow runs, the trace tree updates in real time. Each node shows its duration, inputs, and outputs. Click a node to expand the full detail, including agent tool calls and LLM responses. ![Screenshot of the AGNT5 Studio trace view for a completed travel_booking_workflow run. The left panel shows the trace tree with workflow, agent iterations, LLM calls, and tool calls. The right panel shows the input and the agent's final output with flight options.](/docs/integrations/Trace-dev-light.png) _The trace tree updates in real time as the workflow runs. Expand any node to inspect inputs, outputs, and LLM token usage._ --- ## Create a service key The API authenticates requests with a service key passed in the `X-API-KEY` header. Keys start with `agnt5_sk_`. Create one before you call the API. > The key is shown only once. Copy it to a secure location immediately. You cannot retrieve it again. ### Via Studio 1. Open Studio and go to your project. 2. Click **Settings** in the left sidebar. 3. Navigate to **Service Keys**. 4. Click **Create service key**, give it a name, and confirm. 5. Copy the key and save it somewhere secure. ### Via the CLI ```bash agnt5 service-keys create --name "my-service-key" --project ``` A key gets the `run` scope by default, which lets it execute workflows and functions. Pass `--scopes` to change this, and `--expires-in` (for example `24h` or `7d`) to make the key expire. Revoke a key with `agnt5 service-keys revoke `. --- ## Run from the CLI Use `agnt5 run` to trigger a component directly from the terminal. Without extra flags, it routes to your local dev worker. ```bash # Run a function (streams output as it arrives) agnt5 run hello_world --input '{"name": "Alice"}' # Run a workflow agnt5 run travel_booking_workflow \ --type workflow \ --input '{"message": "2 adults traveling from LAX to JFK, June 28–30"}' # Run a tool agnt5 run search_flights \ --type tool \ --input '{"departure_id": "LAX", "arrival_id": "JFK", "adults": 2}' # Run an agent — input must include a "message" field agnt5 run travel_booking_agent \ --type agent \ --input '{"message": "Find me flights from LAX to JFK in late June"}' ``` Functions stream output to the terminal as they run. Workflows, tools, and agents return JSON when the execution completes. Pass `--type` for every component that is not a function; `agnt5 components --dev` lists the names your local worker registered. The result goes to standard output as JSON, and the run ID goes to standard error. Pipe or redirect the output for scripting: ```bash agnt5 run search_flights --type tool --input '{"adults": 2}' | jq '.flights[0]' agnt5 run my_workflow --type workflow --input '{}' > result.json ``` To run against a deployed environment instead of the local worker, add `--env `, or target a specific deployment with `--deployment-id `. See [Deploying](/docs/run/deploying.md#via-the-cli) for the full reference. --- ## Trigger over the API You can trigger any workflow or function with `curl`. The easiest way to get the exact command, with your workspace ID and deployment ID already filled in, is to copy it from Studio: 1. Open Studio and navigate to the component you want to run. 2. Click the **copy curl** button on the component. 3. Paste it into your terminal and replace the `X-API-KEY` value with your service key. The copied command looks like this: ```bash curl -X POST 'https://gw.agnt5.com/v1/workflows/travel_booking_workflow/run' \ -H "Content-Type: application/json" \ -H "X-API-KEY: agnt5_sk_..." \ -H "X-WORKSPACE-ID: " \ -H "X-DEPLOYMENT-ID: " \ -d '{"message": "2 adults are traveling from Los Angeles (LAX) to New York (JFK), departing on June 28, 2026, and returning on June 30, 2026."}' ``` Functions use the same request at `/v1/functions//run`. See [Run a component](/docs/api-reference/runs-and-traces/run-a-component.md) for the full reference. To target your local dev worker, set `X-DEPLOYMENT-ID` to its deployment ID, which `agnt5 dev` saves in `.agnt5/dev-deployment-id` in your project. The response reports the run's result: ```json { "run_id": "", "status": "completed", "output": { "...": "the component's return value" }, "error": null, "duration_ms": 2166 } ``` ## Next steps - [Deploying](/docs/run/deploying.md): move your worker into an AGNT5 environment. - [CLI overview](/docs/cli/overview.md): see every `agnt5` command. - [Human-in-the-loop](/docs/build/human-in-the-loop.md): respond to workflow pauses from Studio.