Deploying

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:

# 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 for provider-specific setup.

Deploy

# 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

# Check deployments for an environment
agnt5 deployments --environment production

# Tail the worker logs
agnt5 logs <deployment-id> --follow

Deployment logs

View logs for the entire deployment — all runs, worker startup, and system events.

CLI

agnt5 logs <deployment-id>
agnt5 logs <deployment-id> --follow    # live stream
agnt5 logs <deployment-id> --tail 50  # last 50 lines

API

GET https://api.agnt5.com/api/v1/deployments/<deployment_id>/logs

curl 'https://api.agnt5.com/api/v1/deployments/<deployment_id>/logs' \
  -H "X-API-KEY: <token>"

For a live stream (SSE):

curl -N 'https://api.agnt5.com/api/v1/deployments/<deployment_id>/logs/tail' \
  -H "X-API-KEY: <token>" \
  -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

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):

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:

Listing runs from the CLI

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:

# 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: <token>. See Creating an X-API-KEY to generate one.

curl 'https://api.agnt5.com/api/v1/analytics/runs?project_id=<project_id>&status=completed&limit=20' \
  -H "X-API-KEY: <token>"

Describing a run from the CLI

agnt5 inspect runs describe <runId>

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/<run_id>?project_id=<project_id>

curl 'https://api.agnt5.com/api/v1/analytics/runs/<run_id>?project_id=<project_id>' \
  -H "X-API-KEY: <token>"

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

agnt5 inspect trace -r <runId>

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:

# Flat list — useful for long traces
agnt5 inspect trace -r <runId> --flat

# Show span attributes (inputs/outputs, LLM params)
agnt5 inspect trace -r <runId> --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 <runId> or the run detail API response.

GET https://api.agnt5.com/api/v1/traces/<trace_id>

curl 'https://api.agnt5.com/api/v1/traces/<trace_id>' \
  -H "X-API-KEY: <token>"

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

agnt5 inspect logs -r <runId>

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:

# Only errors
agnt5 inspect logs -r <runId> --severity ERROR

# Live streaming (useful while a run is in progress)
agnt5 inspect logs -r <runId> --follow

Getting logs via the API

GET https://api.agnt5.com/api/v1/runs/<run_id>/logs

curl 'https://api.agnt5.com/api/v1/runs/<run_id>/logs?limit=50' \
  -H "X-API-KEY: <token>"

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 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:

agnt5 inspect runs ls --status failed --since 1h
agnt5 inspect runs describe <runId>
agnt5 inspect logs -r <runId> --severity ERROR
agnt5 inspect trace -r <runId>

Watch a workflow as it executes:

# In one terminal: stream the logs
agnt5 inspect logs -r <runId> --follow

# Or watch the run list update
agnt5 inspect runs ls --component my_workflow -w

Export a trace for offline analysis:

agnt5 inspect trace -r <runId> --json > trace.json