Errors and troubleshooting

​

Handle gateway failures

import { AgentGatewayError } from "@phaseo/agent-sdk";

try {
  await agent.run({ input, client });
} catch (error) {
  if (error instanceof AgentGatewayError) {
    console.error(error.status, error.requestId, error.reason);
  }
  throw error;
}

​

Handle schema failures

import { AgentSchemaValidationError } from "@phaseo/agent-sdk";

try {
  await agent.run({ input, client });
} catch (error) {
  if (error instanceof AgentSchemaValidationError) {
    console.error(error.target, error.message);
  }
  throw error;
}

​

Inspect the failed run

• result.run.status
• result.run.error
• the latest step’s status, error, and modelAttempts
• requestId and nativeResponseId for correlation with gateway logs

​

Common checks

• Confirm PHASEO_API_KEY is available to the server process.
• Give each tool a unique, stable id.
• Use exact tool-call IDs when approving, rejecting, or supplying manual output.
• Keep model retries bounded; validation and approval failures should not retry blindly.
• Persist paused run state before returning control to a browser or queue worker.

​

Related guides

• Lifecycle hooks
• DevTools
• State and approval