Monitor & troubleshoot
On this page
A deployment has two separate health signals. Runtime compatibility tells you whether a version can load and run. Agent health tells you whether components in the editable source agent need an update.
Is my agent healthy?
Runtime compatibility asks, "Will this version run?" Arkus checks each version before it goes live. A failed check leaves the current version in place.
Agent health asks, "Does my source agent need an update?" The builder can flag outdated components in the editable agent. Updating them does not change the live deployment until you redeploy.
Keeping these signals separate helps you choose the right fix. A healthy source agent can still contain a component that deployments do not support. A compatible live version can also stay online while you update the source agent.
What you can and can't deploy
Most components used to build an agent can run in a deployment. These visible components are not supported:
| Component | What to do |
|---|---|
| API Request | Remove it or replace it with a supported integration before you deploy. |
| MCP Tools | Remove it or replace it with a supported tool before you deploy. |
| SQL Database | Remove it or move the database step outside the deployed agent. |
| UI Block | Remove it. A deployed agent returns data through the Runtime API rather than rendering builder UI blocks. |
| Python Interpreter | Remove it or move the Python step outside the deployed agent. |
| Run Flow | Replace it by adding the required steps directly to the agent before you deploy. |
If a deploy reports an unsupported component, return to the source agent, replace that component, save, and try again.
Fix a deploy that will not go live
The compatibility check failed
Likely cause: The version contains an unsupported component, a broken connection, or a component that cannot load with its saved settings.
Fix:
- Read the failure details and deployment logs.
- Open the source agent and check its components and connections.
- Replace unsupported components and repair broken connections.
- Save and test the agent in the builder.
- Redeploy.
The failed version does not replace the version that is already live.
The deploy keeps preparing
Likely cause: Arkus is still copying files, knowledge, or other version data.
Fix: Leave the current version running and check the deployment again. If preparation later fails, use the failure details and logs before you retry.
A saved connection needs attention
Likely cause: A credential is missing, invalid, or needs to be reconnected.
Fix: Return to the source agent, update or reconnect the saved credential, test the component, and redeploy.
Keep a live agent healthy
The agent health card checks components in the editable source agent. It may suggest updates when a component definition has changed.
Review the suggested changes before you apply them. Test the updated agent with realistic inputs, such as a sample clinical guideline question or a de-identified patient report. Then redeploy to create a new frozen version.
The live version stays unchanged until the new version passes its compatibility check.
Read deployment logs
Deployment logs show operational events such as publishes, failures, status changes, and API-key changes. Error entries contain sanitized summaries that help you understand what failed.
Logs do not contain consumer transcripts. Use them to diagnose how the deployment operated, not to read the messages sent through it.
Understand usage and limits
Several guardrails can stop a request:
| What you see | What it means | What to do |
|---|---|---|
| Too many messages | The app sent more requests than the current rate allows. | Wait for the time in Retry-After, then try again. |
| Deployment paused | The owner paused new runtime requests. | Resume the deployment and allow about a minute for the change to take effect. |
| Out of credits | The owner's balance reached zero. | Add credits before sending more billable work. |
| Missing API key | The key is missing or empty. | Check that the server sends the x-api-key header. |
| Request not found | The key is invalid or revoked, or the requested deployment or session is unavailable to it. | Check the server-side secret or create a new deployment API key. |
| Deployment unavailable | The active version cannot serve requests. | Check runtime compatibility and deployment logs. |
The default message limit is 60 messages in 60 seconds for one deployment consumer. Limits on simultaneous runs are disabled by default, but your environment may enable them.
Where to go next
- Deploy & manage to redeploy, restore a version, pause, or delete.
- Integrate the API to handle streaming replies and errors in your app.