Deploy Python API

The Deploy class runs, inspects, and tears down a deployment from Python.

from praisonai_deploy import Deploy

deploy = Deploy.from_yaml("agents.yaml")
result = deploy.deploy()
status = deploy.status()

Quick Start

From a YAML file

from praisonai_deploy import Deploy

deploy = Deploy.from_yaml("agents.yaml")
result = deploy.deploy()

From a config object

from praisonai_deploy import Deploy, DeployConfig, DeployType

config = DeployConfig(type=DeployType.API)
deploy = Deploy(config, agents_file="agents.yaml")
result = deploy.deploy()

Methods

Method	Returns	Description
`Deploy.from_yaml(agents_file="agents.yaml")`	`Deploy`	Build a `Deploy` from the `deploy:` section of a YAML file
`Deploy(config, agents_file="agents.yaml")`	`Deploy`	Build a `Deploy` from a `DeployConfig` object
`deploy(background=False)`	`DeployResult`	Execute the deployment
`plan()`	`dict`	Return the planned configuration without deploying
`status()`	`DeployStatus`	Return the current service state
`doctor()`	`DoctorReport`	Run readiness checks for the configured type
`destroy(force=False)`	`DestroyResult`	Tear down the deployment

For type: api, deploy() spawns the generated Flask server with sys.executable and passes env=os.environ.copy(), so the child inherits the caller’s interpreter and environment (OPENAI_API_KEY, etc.). No extra wiring is required to reach /chat.

Result Models

Each operation returns a typed model.

DeployResult

Field	Type	Description
`success`	`bool`	Whether the deployment succeeded
`message`	`str`	Human-readable result message
`url`	`Optional[str]`	Deployed service URL
`error`	`Optional[str]`	Error message if it failed
`metadata`	`Dict[str, Any]`	Additional metadata

DeployStatus

Field	Type	Default	Description
`state`	`ServiceState`	(required)	`running` / `stopped` / `pending` / `failed` / `not_found` / `unknown`
`url`	`Optional[str]`	`None`	Service URL/endpoint
`message`	`str`	`""`	Status message
`service_name`	`Optional[str]`	`None`	Service name
`provider`	`Optional[str]`	`None`	`api` / `docker` / `<any registered provider>`. Plugin providers surface here too, as their normalised name.
`region`	`Optional[str]`	`None`	Deployment region
`healthy`	`bool`	`False`	Whether the service is healthy
`instances_running`	`int`	`0`	Running instances
`instances_desired`	`int`	`0`	Desired instances
`created_at`	`Optional[str]`	`None`	Creation timestamp
`updated_at`	`Optional[str]`	`None`	Last update timestamp
`metadata`	`Dict[str, Any]`	`{}`	Provider-specific metadata

DeployStatus.to_dict() returns a JSON-serialisable dictionary.

Programmatic APIs

The registry — not the CloudProvider enum — is the authority on what is deployable.

from praisonai_deploy import (
    CloudProvider,           # built-in constants (aws, azure, gcp, fly, railway, render)
    coerce_cloud_provider,   # validate a name against the registry
    list_cloud_providers,    # every deployable name (built-ins + plugins)
)
from praisonai_deploy.providers import CloudProviderRegistry

Function	Returns	Description
`list_cloud_providers()`	`list[str]`	Every deployable name now. Built-ins first (declaration order), plugins appended sorted.
`coerce_cloud_provider(value)`	`CloudProvider \| str`	A `CloudProvider` member for built-ins, a normalised lowercase `str` for plugins. Raises `ValueError` with a registry-derived list on unknown names.
`CloudProviderRegistry.default()`	`CloudProviderRegistry`	The shared registry. Use `list_names()`, `register(name, cls)`, and `resolve(name)` for programmatic use.

from praisonai_deploy import list_cloud_providers, coerce_cloud_provider

print(list_cloud_providers())          # ['aws', 'azure', 'gcp', 'fly', 'railway', 'render', ...]
print(coerce_cloud_provider("AWS"))    # CloudProvider.AWS  (built-in keeps enum identity)
print(coerce_cloud_provider(" gcp "))  # CloudProvider.GCP  (stripped + lowercased)

DestroyResult

Field	Type	Description
`success`	`bool`	Whether the destroy succeeded
`message`	`str`	Result message
`resources_deleted`	`List[str]`	Deleted resource identifiers
`error`	`Optional[str]`	Error message if it failed
`metadata`	`Dict[str, Any]`	Additional metadata

Common Patterns

Read the status as JSON.

from praisonai_deploy import Deploy

deploy = Deploy.from_yaml("agents.yaml")
status = deploy.status()
print(status.to_dict())

Plan before deploying.

from praisonai_deploy import Deploy

deploy = Deploy.from_yaml("agents.yaml")
print(deploy.plan())  # dict describing the planned deployment

Tear down when finished.

from praisonai_deploy import Deploy

deploy = Deploy.from_yaml("agents.yaml")
result = deploy.destroy(force=True)
print(result.resources_deleted)

For type: api, destroy() finds the process on the API port with netstat -ano on Windows and lsof -ti :<port> on macOS/Linux, then terminates it with taskkill /PID <pid> /F or SIGTERM respectively. A missing discovery binary is treated as “no server running” (success=True); PIDs that can’t be killed leave success=False with the survivors in error=.

Best Practices

Check success before reading url

DeployResult.url is only set when success is True. Branch on result.success first.

Use to_dict() for logs and APIs

DeployStatus.to_dict() returns plain JSON types, ready to serialise into logs or an HTTP response.

Import from praisonai_deploy

Use from praisonai_deploy import Deploy — the praisonai.deploy path is a compatibility shim only.

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

Methods

Result Models

DeployResult

DeployStatus

Programmatic APIs

DestroyResult

Common Patterns

Best Practices

Config Reference

CLI Reference

Custom Providers

​Quick Start

​Methods

​Result Models

​DeployResult

​DeployStatus

​Programmatic APIs

​DestroyResult

​Common Patterns

​Best Practices

​Related

Config Reference

CLI Reference

Custom Providers

Quick Start

Methods

Result Models

DeployResult

DeployStatus

Programmatic APIs

DestroyResult

Common Patterns

Best Practices

Related