Agent Lifecycle
An agent progresses through a defined lifecycle before it can serve traffic: you author it, validate it, generate its artifacts, and deploy it — first to dev, then promote it to test and prod. This page explains each stage, the environments involved, and the runtime controls (start, stop, promote, logs). It complements Creating an Agent, which covers the create form itself.
Lifecycle stages
Section titled “Lifecycle stages”Deployment moves through these stages, reflected in the agent’s status badge on the Agents list:
| Stage | Status | Meaning |
|---|---|---|
| Draft | draft |
Being authored; not yet validated |
| Validating | validating |
Validation in progress |
| Validated | validated |
Passed validation; ready to generate artifacts |
| Validation failed | validation_failed |
Validation found blocking issues |
| Generating artifacts | generating_artifacts |
Config files are being generated and committed |
| Artifacts ready | artifacts_generated |
Artifacts committed to git; ready to deploy |
| Deploying | deploying |
The deployment workflow is running |
| Deployed | deployed |
The serving endpoint (and any app/Slack) is live |
| Deployment failed | deployment_failed |
The deployment workflow failed |
| Deleted | deleted |
Removed from the environment |
Once deployed, a second, runtime dimension applies — Starting, Started, Stopping, or Stopped — reflecting whether the agent’s compute is running.
Validate
Section titled “Validate”Validation is a required pre-deploy check. From the create form select Validate; Nexa then:
-
Checks required fields — the LLM model, description, and orchestration prompt must be present, and temperature (0–2), max tokens, and timeout must be valid. It warns if no tools are selected or if a tool is in both the structured and unstructured lists.
-
Validates the bundle — Nexa validates the generated deployment bundle against your workspace without committing anything to git or deploying.
-
Records the result — on success the agent becomes Validated; on failure it becomes Validation Failed with error and warning details you can review in the Validation & Artifacts step.
Generate artifacts and deploy
Section titled “Generate artifacts and deploy”After validation, committing the agent generates its configuration artifacts (the agent config, metadata, deployment bundle definition, and — when enabled — the Streamlit app and Slack binding), commits them to the environment’s git branch, and dispatches the deployment.
In the create form, Create Agent performs the commit-and-deploy in one step. Deployment runs a workflow that registers the model and brings up the components:
| Component | When |
|---|---|
| Agent serving endpoint | Always |
| Streamlit app | When the Streamlit integration is on |
| Slack channel | When the Slack Endpoint integration is on |
Deployment cannot run before artifacts exist; if you try to deploy without generated artifacts, Nexa blocks it. Track progress in the Deployment step or the agent detail’s Deployment tab, either as a component Summary or the full Workflow Details logs.
Environments
Section titled “Environments”Nexa agents move through three environments, each bound to a git branch:
| Environment | Branch |
|---|---|
| dev | develop |
| test (also called staging) | release |
| prod | main |
A running Nexa instance is bound to one environment. On the agent detail and deployment views, the environment determines which endpoint, app, and logs you’re looking at.
Start and stop
Section titled “Start and stop”Once deployed, use the play/pause control on the agent card or row to manage its compute. It opens a modal listing the agent’s components and any dependent automations.
- Stop is atomic — it stops the serving endpoint, Streamlit app, and Slack bindings together. Confirm with Stop All.
- Start is selective — the agent endpoint always starts, and you choose which additional components (Streamlit app, Slack channel) to bring up. Confirm with Start Selected.
Start and stop poll for status, so you can close the modal and keep working while components come up or down.
Promote across environments
Section titled “Promote across environments”Promotion moves a specific agent version to the next environment. Select Promote from the agent’s overflow menu.
- Promotion is stepwise: dev → test, then test → prod. You can’t skip from dev to prod.
- Promoting opens a pull request from the source branch to the target branch. The target team reviews and approves the PR in GitHub, which triggers the deployment into that environment.
- Promoting to prod additionally requires the version to be deployed and healthy in test.
After you request a promotion, Nexa confirms it and opens the deployment progress view for the target environment. Promotion depends on your GitHub Integration and environment configuration.
Logs and traces
Section titled “Logs and traces”Nexa deep-links to the platform-hosted logs and traces rather than streaming them itself:
- Deployment logs / Workflow Details — the deployment workflow run, with per-job and per-step status and a link to the workflow run.
- Traces — the agent’s traces, opened from the Traces action when available.
- Component logs — the Streamlit app and Slack route link out to their hosted logs from the deployment progress panel.
Delete
Section titled “Delete”Deleting removes an agent version from the current environment. The confirm modal lists what will be removed — bundled Streamlit apps, Slack channel bindings, and dependent automations (which cascade). Confirm with Confirm delete; the agent shows Pending_Delete, then Deleted once the cleanup workflow completes. Deletion is environment-local — it only affects the environment you’re bound to.
Agents deploy as Databricks model serving endpoints; the Deployment logs open the deployment workflow run and Traces open the endpoint’s traces in the Databricks workspace.
The lifecycle, environments, and promotion flow are the same; agents deploy onto the equivalent Snowflake serving and app constructs.