> 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: Deploying description: Deploy your worker to a managed AGNT5 environment, then verify it and observe runs, traces, logs, and metrics from the CLI, API, and Studio. last_verified: 2026-06-06 --- Deploy your worker to a managed environment with a single command. The managed worker runs on AGNT5's infrastructure, your laptop is no longer in the loop. --- ## Prerequisites - Authenticated: `agnt5 auth login` --- ## Set secrets and integrations Set your secrets and integrations before deploying so the worker has everything it needs on first start. ### Secrets **Via Studio:** 1. Open your project in Studio. 2. Go to **Settings** -> **Secrets**. 3. Add your secrets (e.g. `OPENAI_API_KEY`). **Via the CLI:** ```bash # Set a secret (prompted securely) agnt5 secrets set --name OPENAI_API_KEY --type api_key # Or pipe from stdin echo "sk-..." | agnt5 secrets set --name OPENAI_API_KEY --type api_key --stdin # List all secrets for the project agnt5 secrets list ``` Run from within your project directory, no `--project` flag needed. ### Integrations To connect an AI provider or an inbound webhook source: 1. Open your project in Studio. 2. Go to **Settings → Integrations**. 3. Click **Add Integration** and follow the setup steps. See [AI providers](/docs/integrations/ai-providers.md) for provider-specific setup. --- ## Deploy ```bash # Deploy to preview (default) agnt5 deploy # Deploy to staging agnt5 deploy --env staging # Deploy to production agnt5 deploy --env production ``` Terminal output: ``` Warning: You are deploying to PRODUCTION Environment: production Continue with production deployment? (y/N): y Deploying to workspace: A5 ok Bundle (1.1s) ok Deploy (3.1s) https://app.agnt5.com/projects/a3e7af1d-c453-4124-be15-f72bd658889d/deployments/3547b7d0-f5cf-4648-a02c-516333305170 Logs: agnt5 logs 3547b7d0-f5cf-4648-a02c-516333305170 ``` The deployment URL links directly to the deployment in Studio. Use the `agnt5 logs` command printed in the output to tail the worker logs. --- ## Verify ```bash # Check deployments for an environment agnt5 deployments --environment production # Tail the worker logs agnt5 logs --follow ``` --- ## Deployment logs View logs for the entire deployment — all runs, worker startup, and system events. ### CLI ```bash agnt5 logs agnt5 logs --follow # live stream agnt5 logs --tail 50 # last 50 lines ``` ### API ``` GET https://api.agnt5.com/api/v1/deployments//logs ``` ```bash curl 'https://api.agnt5.com/api/v1/deployments//logs' \ -H "X-API-KEY: " ``` For a live stream (SSE): ```bash curl -N 'https://api.agnt5.com/api/v1/deployments//logs/tail' \ -H "X-API-KEY: " \ -H "Accept: text/event-stream" ``` --- ## Testing after deployment ### Via Studio Open your project in Studio and go to **Components**. Use the environment switcher at the top to select the environment you deployed to (Development, Staging, or Production). You can also pick a specific deployment from the list below. Set the input and click **Run Workflow** to trigger a run against the deployed worker. _[screenshot: Components page with environment switcher showing Development, Staging, Production]_ ### Via the CLI ```bash agnt5 run travel_booking_workflow \ --input '{"message": "2 adults are traveling from Los Angeles (LAX) to New York (JFK), departing on June 28, 2026, and returning on June 30, 2026."}' \ --env production ``` ### Via the API Copy the curl command directly from the component in Studio — it includes the correct workspace ID and deployment ID for the selected environment. Replace the `X-API-KEY` with your service key (see [Creating an X-API-KEY](/docs/build/local-development.md#creating-an-x-api-key)): ```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: d03e6b5f-da6a-43e6-9533-f492175f554a" \ -H "X-DEPLOYMENT-ID: 9a0e18d6-c4a3-464d-b114-9d63f67fd8cd" \ -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."}' ``` --- ## Runs A **run** is a single execution of a workflow, function, or agent. Every trigger — from Studio, the CLI, or the API — creates a run. Each run records: | Field | Description | |---|---| | Run ID | Unique identifier for the execution | | Component | Name and type (workflow, function, agent) | | Status | `pending`, `running`, `completed`, `failed` | | Duration | Total wall-clock time | | Queue time | Time the run spent waiting before execution started | | Steps | Number of checkpointed steps completed | | Retries | How many function retries were triggered | | LLM calls | Number of model calls made | | LLM cost | Estimated cost in USD | | Error | Error type and category (on failure) | ### Listing runs from the CLI ```bash agnt5 inspect runs ls ``` Output: ``` RUN ID COMPONENT TYPE STATUS DURATION STARTED ──────────────────────────────────────────────────────────────────────────────────────────────────────────── 019e98f0-d4a1-76e1-9177-46d5c004ab6e travel_booking_workflow workflow completed 27.8s 9 min ago 1 run (1 completed) ``` **Flags:** | Flag | Description | |---|---| | `--status ` | Filter by status: `completed`, `failed`, `running`, `pending` | | `--component ` | Filter by component name | | `--component-type ` | Filter by type: `COMPONENT_TYPE_WORKFLOW`, `COMPONENT_TYPE_FUNCTION`, `COMPONENT_TYPE_AGENT` | | `--since ` | Limit to a time window, e.g. `1h`, `24h`, `7d` | | `--limit ` | Maximum runs to show (default: 20) | | `-w` | Watch mode — auto-refreshes every 2 seconds | | `--json` | Machine-readable output | ```bash # Only failed runs in the last hour agnt5 inspect runs ls --status failed --since 1h # All runs for a specific workflow, live agnt5 inspect runs ls --component travel_booking_workflow -w # Pipe to jq agnt5 inspect runs ls --json | jq '.[].run_id' ``` ### Listing runs via the API ``` GET https://api.agnt5.com/api/v1/analytics/runs ``` Requires `X-API-KEY: `. See [Creating an X-API-KEY](/docs/build/local-development.md#creating-an-x-api-key) to generate one. | Query parameter | Description | |---|---| | `project_id` | Your project UUID (required) | | `status` | Filter: `completed`, `failed`, `running`, `pending` | | `component_name` | Filter by component name | | `component_type` | Filter by type | | `since` | RFC 3339 timestamp — only runs after this time | | `limit` | Max results | ```bash curl 'https://api.agnt5.com/api/v1/analytics/runs?project_id=&status=completed&limit=20' \ -H "X-API-KEY: " ``` ### Describing a run from the CLI ```bash agnt5 inspect runs describe ``` Output: ``` Run: 019e98f0-d4a1-76e1-9177-46d5c004ab6e ────────────────────────────────────────────────── Component: travel_booking_workflow (workflow) Status: completed Duration: 27.8s Queue time: 7ms Enqueued: 9 min ago Started: 9 min ago Ended: 9 min ago Trace ID: 019e98f0d4a575d39c4a866f753cb8ab Next steps: agnt5 inspect logs -r 019e98f0.. agnt5 inspect trace -r 019e98f0.. ``` Pass `--json` for machine-readable output. ### Getting a run via the API ``` GET https://api.agnt5.com/api/v1/analytics/runs/?project_id= ``` ```bash curl 'https://api.agnt5.com/api/v1/analytics/runs/?project_id=' \ -H "X-API-KEY: " ``` ### Runs in Studio Open your project in Studio and navigate to **Runs** in the left sidebar. The runs list shows all executions for the project. Click any row to open the run detail page, which shows status, timing, step count, LLM usage, and a link into the trace. _[screenshot: Runs list page showing run ID, component, status, duration columns]_ _[screenshot: Run detail page showing status, timing, steps, LLM usage, and Trace link]_ --- ## Traces A **trace** is the full execution timeline for a run — a tree of spans showing what happened, in what order, and how long each part took. Each span captures one unit of work: a workflow step, a function call, an agent iteration, an LLM request, or a tool call. Spans nest under their parent — a workflow span contains step spans, which contain function spans, and so on. ### Viewing a trace from the CLI ```bash agnt5 inspect trace -r ``` Output (tree view): ``` Trace: 019e98f0d4a575d39c4a866f753cb8ab (27.9s) workflow.travel_booking_workflow [27.9s] python_component_execution [27.9s] agent.travel_booking_agent [27.0s] chat openai/gpt-5-mini [8.9s] tool.search_flights [197ms] tool.search_hotels [3.0s] chat openai/gpt-5-mini [2.7s] tool.create_itinerary [61ms] chat openai/gpt-5-mini [10.6s] ``` Error spans are highlighted in red. **Flags:** | Flag | Description | |---|---| | `-r ` | Run ID to show the trace for (required) | | `--flat` | Flat list sorted by start time instead of a tree | | `--verbose` | Also print span attributes (inputs, outputs, model names, token counts) | | `--json` | Raw trace JSON | ```bash # Flat list — useful for long traces agnt5 inspect trace -r --flat # Show span attributes (inputs/outputs, LLM params) agnt5 inspect trace -r --verbose ``` ### Getting a trace via the API Use the `trace_id` from the run record. You can find it in the output of `agnt5 inspect runs describe ` or the run detail API response. ``` GET https://api.agnt5.com/api/v1/traces/ ``` ```bash curl 'https://api.agnt5.com/api/v1/traces/' \ -H "X-API-KEY: " ``` Returns an array of spans. Each span has `name`, `start_ns`, `end_ns`, `status_code`, and an `attrs` JSON string with inputs, outputs, model names, and token counts. ### Trace in Studio Navigate to a run in Studio and click the **Trace** tab. The trace renders as an interactive tree — click any node to expand its inputs, outputs, and attributes. For agent runs, each reasoning iteration and tool call appears as a nested span. LLM spans show the model name, token counts, and cost. The trace updates in real-time while a run is in progress. _[screenshot: Trace tab showing the interactive span tree with a node expanded to reveal inputs, outputs, and LLM token counts]_ --- ## Logs Logs are structured output emitted during a run, scoped to the execution that produced them. ### Viewing logs from the CLI ```bash agnt5 inspect logs -r ``` Output: ``` 17:59:40.449 INFO Executing component (stream) 17:59:40.453 INFO Orchestrator: DISPATCH 17:59:40.993 INFO Travel booking workflow - message: 2 adults are traveling... 17:59:50.379 INFO Searching flights: LAX -> JFK on 2026-06-28 17:59:50.517 INFO Found 3 flight options 17:59:50.746 INFO Searching hotels in New York, NY: 2026-06-28 to 2026-06-30 17:59:53.639 INFO Found 3 hotel options 17:59:56.918 INFO Creating itinerary for New York, NY (2026-06-28 to 2026-06-30) 18:00:08.099 INFO Travel booking agent completed 18:00:08.395 INFO Released active dispatch on owning peer ``` **Flags:** | Flag | Description | |---|---| | `-r ` | Run ID to fetch logs for (required) | | `--severity ` | Filter: `DEBUG`, `INFO`, `WARN`, `ERROR` | | `-f` / `--follow` | Stream new log lines in real-time (polls every 2s) | | `--tail ` | Show only the last N lines | | `--json` | Raw JSON log entries | ```bash # Only errors agnt5 inspect logs -r --severity ERROR # Live streaming (useful while a run is in progress) agnt5 inspect logs -r --follow ``` ### Getting logs via the API ``` GET https://api.agnt5.com/api/v1/runs//logs ``` | Query parameter | Description | |---|---| | `limit` | Max log lines to return (default: 100) | ```bash curl 'https://api.agnt5.com/api/v1/runs//logs?limit=50' \ -H "X-API-KEY: " ``` Returns `{ "items": [...], "count": N, "next_offset": N }`. Each item has `body` (the log message), `severity`, `ts_ns` (timestamp), `trace_id`, and `span_id`. --- ## Promote via Studio After verifying and testing, open the deployment URL printed in the terminal. From the deployment page in Studio you can promote the deployment to staging or production without running any commands. You can also roll back to a previous deployment from the same page. See [Environments](/docs/run/environments.md) for how promotion, rollback, scaling, and environment-scoped secrets work. _[screenshot: deployment page showing promote to staging/production]_ --- ## Metrics Metrics aggregate run data across time to show trends. They are available in Studio under **Analytics** and **Metrics**. ### Analytics (Studio) The **Analytics** page shows a high-level summary for the selected time window. **Summary cards:** - Total executions - Success rate - P95 latency - Total LLM cost **Charts:** - Executions over time (area chart, broken down by status) - Latency over time (P95) - LLM usage by model - Top errors by frequency Use the time range picker to switch between preset windows (`1h`, `3h`, `24h`, `7d`, `30d`) or a custom date range. _[screenshot: Analytics page showing summary cards (total executions, success rate, P95 latency, LLM cost) and charts below]_ ### Metrics (Studio) The **Metrics** page gives per-component breakdowns with finer control. **Filters:** - **Deployment** — scope to a specific deployment - **Component** — scope to a specific function, workflow, or agent - **Status** — filter runs included in the aggregates **Controls:** - **Granularity** — bucket size for charts: `auto`, `1m`, `5m`, `1h`, `1d` - **Auto-refresh** — automatically reload at a set interval - **UTC** — display timestamps in UTC instead of local time _[screenshot: Metrics page showing deployment/component/status filters and per-component latency and execution charts]_ --- ## Common workflows **Find why a run failed:** ```bash agnt5 inspect runs ls --status failed --since 1h agnt5 inspect runs describe agnt5 inspect logs -r --severity ERROR agnt5 inspect trace -r ``` **Watch a workflow as it executes:** ```bash # In one terminal: stream the logs agnt5 inspect logs -r --follow # Or watch the run list update agnt5 inspect runs ls --component my_workflow -w ``` **Export a trace for offline analysis:** ```bash agnt5 inspect trace -r --json > trace.json ```