> 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-10-08 --- 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` - A project directory linked to your AGNT5 project (`agnt5 init` or `agnt5 link `). Commands such as `agnt5 deploy`, `agnt5 secrets`, and `agnt5 inspect` read the project from the current directory. --- ## 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, read, and delete secrets agnt5 secrets list agnt5 secrets get OPENAI_API_KEY agnt5 secrets delete OPENAI_API_KEY --force ``` Run from within your project directory, no `--project` flag needed. Your worker reads each secret as an environment variable with the secret's name. Secrets are read when a deployment starts, so deploy after you add or change one. To use different values per environment, see [Environment-scoped secrets](/docs/run/environments.md#environment-scoped-secrets). ### 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 (asks for confirmation) agnt5 deploy --env production ``` Terminal output: ``` ok Bundle (1.4s) Deploying... ok Deployment created (2.7s) Waiting for deployment to become ready... Replicas active, switching traffic to this deployment... ok Ready (49.3s) - 1/1 replica(s) active, preview routes to this deployment note This deployment stops after 1 hour, at about 22:15 UTC. Deploy with --env production, or set --max-run-duration, to keep it running. https://app.agnt5.com/projects//deployments/ Logs: agnt5 logs ``` The deployment URL links directly to the deployment in Studio. Use the `agnt5 logs` command printed in the output to tail the worker logs. Useful flags: | Flag | Description | |---|---| | `--env ` | Target environment. Defaults to `preview`. | | `--replicas`, `--min-replicas`, `--max-replicas` | Set the number of worker replicas, or the autoscaling bounds. | | `--max-run-duration ` | How long the workers run, for example `30m`, `1h`, or `forever`. Preview deployments stop after 1 hour; staging and production run until you replace them. | | `--dry-run` | Validate the configuration and show what would be deployed. | | `--no-wait` | Return as soon as the deployment is created. | | `--interactive=false` | Skip prompts, including the production confirmation, for CI. | --- ## Verify ```bash # List recent deployments for the project agnt5 deployment list # Show the current deployment's status, replicas, and traffic agnt5 deployment status # Show scheduling and image errors, if any agnt5 deployment errors # List the components the deployment registered agnt5 components --env preview agnt5 components --env preview --type workflow # Tail the worker logs agnt5 logs --follow ``` --- ## Deployment logs View logs for the entire deployment: all runs, worker startup, and system events. ```bash agnt5 logs agnt5 logs --follow # live stream agnt5 logs --tail 50 # last 50 lines agnt5 logs --since 30m # only recent lines agnt5 logs --timestamps # include timestamps ``` --- ## 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. ### Via the CLI The CLI uses `https://gw.agnt5.com` as its default gateway. Use `--type` to select the component type and `--env` to target a deployed environment. ```bash # Run a workflow agnt5 run travel_booking_workflow \ --type 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 # Run a function (streams output as it runs) agnt5 run summarize_itinerary \ --type function \ --input '{"trip_id": "abc123"}' \ --env production # Run a tool agnt5 run search_flights \ --type tool \ --input '{"departure_id": "LAX", "arrival_id": "JFK", "outbound_date": "2026-06-28", "return_date": "2026-06-30", "adults": 2}' \ --env production # 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 for 2 adults"}' \ --env production ``` **Component types and output behaviour:** Streaming changes how you observe a run, not whether the run is durable. See [Streaming output and durability](/docs/run/streaming-output.md) for the persistence and reconnect contract. | `--type` | Default | Output | |---|---|---| | `function` | Yes | Streams as SSE — output prints to the terminal as it arrives | | `workflow` | No | Returns final JSON output when the run completes | | `tool` | No | Returns the tool result as JSON | | `agent` | No | Returns the agent reply as JSON; input must include a `"message"` field | Pass `--type` for every component that is not a function. Run `agnt5 components --env --type workflow` to list the names a deployment registered. **Capturing output:** all component types print JSON to stdout. Use shell redirection to save or pipe results: ```bash agnt5 run travel_booking_workflow --type workflow \ --input '{"message": "..."}' --env production > result.json agnt5 run search_flights --type tool \ --input '{"adults": 2}' --env production | jq '.flights[0]' ``` ### Via the API Call the gateway at `https://gw.agnt5.com` with a service key. Copy the curl command from the component in Studio, or write it yourself. Replace the `X-API-KEY` value with your service key (see [Create a service key](/docs/build/local-development.md#create-a-service-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-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."}' ``` `X-DEPLOYMENT-ID` selects the deployment to run against. A key created for a single environment (`agnt5 service-keys create --project --environment `) runs against that environment's live deployment, so you can leave the header out: ```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_..." \ -d '{"message": "..."}' ``` The response reports the run's result: ```json { "run_id": "", "status": "completed", "output": { "...": "the component's return value" }, "error": null, "duration_ms": 824 } ``` Every component type can also start a run and return at once, stream the run's events, or run a batch. See [Run a component](/docs/api-reference/runs-and-traces/run-a-component.md) and the other gateway endpoints under [Runs & Traces](/docs/api-reference/runs-and-traces.md). --- ## 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 | `queued`, `started`, `paused`, `completed`, `failed`, `cancelled` | | 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 ──────────────────────────────────────────────────────────────────────────────────────────────────────────── 01a00000-0000-7000-8000-000000000001 travel_booking_workflow workflow completed 27.8s 9 min ago 1 run (1 completed) ``` Filter by status, component, type, and time window, or watch the list refresh. See [Inspect & logs](/docs/cli/inspect.md#agnt5-inspect-runs-ls) for every flag. ```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 --output json | jq '.data[].run_id' ``` ### Listing runs via the API `GET https://gw.agnt5.com/v1/runs` lists runs with the same service key, filtered by status, component, and time. See [List runs (gateway)](/docs/api-reference/runs-and-traces/list-gateway-runs.md) for the query parameters and response. ### Describing a run from the CLI ```bash agnt5 inspect runs describe ``` Output: ``` Run: 01a00000-0000-7000-8000-000000000001 ────────────────────────────────────────────────── 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: 01a000000000700080000000000000a1 Next steps: agnt5 inspect logs -r 01a00000.. agnt5 inspect trace -r 01a00000.. ``` Pass `--output json` for machine-readable output. ### Getting a run via the API `GET https://gw.agnt5.com/v1/runs/` returns the run record, and `GET /v1/runs//output` returns its final output. See [Get a run (gateway)](/docs/api-reference/runs-and-traces/get-a-gateway-run.md) and [Get run output](/docs/api-reference/runs-and-traces/get-run-output.md). ### 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. --- ## 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: 01a000000000700080000000000000a1 (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. See [Inspect & logs](/docs/cli/inspect.md#agnt5-inspect-trace) for every flag. ```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 as JSON ```bash agnt5 inspect trace -r --output json ``` The spans are under `data.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. --- ## 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 ``` See [Inspect & logs](/docs/cli/inspect.md#agnt5-inspect-logs) for every flag. ```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 as JSON ```bash agnt5 inspect logs -r --output json ``` The entries are under `data.items`. Each has `body` (the log message), `severity`, `ts_ns` (timestamp), `trace_id`, and `span_id`. --- ## Promote a deployment After verifying and testing, promote the same deployment to another environment. The image is reused, nothing is rebuilt, and the target environment keeps serving its current deployment until the promoted one is ready. ```bash agnt5 deployment promote --latest --env staging agnt5 deployment promote --env production --yes ``` Output: ``` ok Promotion started: my-worker-a1b2 -> staging (new deployment ) Waiting for the promoted deployment to become ready... ok Ready (35.2s) - 1/1 replica(s) active, staging routes to this deployment ``` After a promotion, compare the new deployment with the one it replaced: ```bash agnt5 deployment checks --env staging ``` You can also promote and roll back from the deployment page in Studio, which you reach from the deployment URL printed in the terminal. See [Environments](/docs/run/environments.md) for how promotion, rollback, scaling, and environment-scoped secrets work. --- ## 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. ### 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 --- ## 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 --output json > trace.json ``` --- ## Machine-readable output Every CLI command prints text on a terminal and JSON when its output is piped or redirected. Pass `--output json` (or `-o json`) to choose JSON explicitly. JSON output wraps the payload in `{"data": ...}`, so a list of runs is `.data[]`: ```bash agnt5 inspect runs ls --output json | jq '.data[].run_id' ``` See [Configuration](/docs/cli/configuration.md#global-flags) for output precedence and the JSON envelope.