DinoAI Programmable Agents

Overview

Prerequisites:

This feature is available on workspaces with DinoAI programmable agents enabled.
Your API keys must have access to the DinoAI Agents API.

These examples authenticate with an account API key (api_secret="prdm_cmp_..." plus workspace_uid), which requires paradime-io 6.0.0 or later. Legacy workspace API keys (api_key + api_secret) are still supported. See Getting Started.

The DinoAI Agents module lets you drive DinoAI programmable agents from Python. This module offers a comprehensive set of tools to trigger agent runs from YAML-defined agents, send ad-hoc prompts, follow up on a live session with new messages, poll for run state, and block until a run completes.

Trigger an agent run

Triggers a DinoAI programmable agent run. At least one of agent or message must be provided.

Args
Returns

agent (Optional[str]): Name of the YAML-defined agent to load (matches the file name under .dinoai/agents/ without the .yml extension).message (Optional[str]): Custom prompt appended to the agent’s context. When only agent is provided, the run starts with the agent’s role/goal/backstory.slack_channel (Optional[str]): Slack channel ID the run should post into (e.g. "C0123456789"). Must be provided together with slack_thread.slack_thread (Optional[str]): Slack thread timestamp the run should reply in (e.g. "1714142436.001200"). Must be provided together with slack_channel.

slack_channel and slack_thread must be supplied together — passing only one will be rejected by the API. Omit both to leave Slack routing to the agent’s YAML configuration (if any).

DinoaiAgentTriggerResult: Contains ok, agent_session_id, and status (always the literal string "queued" on accept — poll with get_run for live status).

# First party modules
from paradime import Paradime

# Create a Paradime client with your API credentials
paradime = Paradime(api_endpoint="API_ENDPOINT", api_secret="prdm_cmp_...", workspace_uid="WORKSPACE_UID")

# Trigger a named agent with an opening message
result = paradime.dinoai_agents.trigger_run(
    agent="data-quality-checker",
    message="Check stg_orders for missing not_null tests.",
)

print(result.agent_session_id)

Trigger an agent run and wait for completion

Triggers a DinoAI agent run and blocks until it reaches COMPLETED or FAILED.

Args
Returns

agent (Optional[str]): Name of the YAML-defined agent to load.message (Optional[str]): Custom prompt appended to the agent’s context.slack_channel (Optional[str]): Slack channel ID. Must be provided together with slack_thread.slack_thread (Optional[str]): Slack thread timestamp. Must be provided together with slack_channel.timeout (int): Maximum seconds to wait before raising TimeoutError. Defaults to 3600.poll_interval (int): Seconds between status polls. Defaults to 10.

DinoaiAgentRun: The final run state, including status, all messages, child_session_ids, and workspace_uid.Raises DinoaiAgentRunFailedException if the run finishes with status FAILED, and TimeoutError if the run does not complete within timeout seconds.

# First party modules
from paradime import Paradime

# Create a Paradime client with your API credentials
paradime = Paradime(api_endpoint="API_ENDPOINT", api_secret="prdm_cmp_...", workspace_uid="WORKSPACE_UID")

# Trigger a named agent and block until it completes
run = paradime.dinoai_agents.trigger_run_and_wait(
    agent="data-quality-checker",
    message="Focus on stg_orders",
)

print(f"Status: {run.status}")
for msg in run.messages:
    print(f"[{msg.role}] {msg.content}")

Send a follow-up message

Sends a follow-up message to an active DinoAI agent session. The agent pod stays alive for up to 24 hours since the last message; follow-ups resume the same conversation with full context.

Args
Returns

agent_session_id (str): The session ID of the running agent.message (str): The follow-up message to send.

DinoaiAgentTriggerResult: Contains ok, agent_session_id, and status (always "queued" on accept).

# First party modules
from paradime import Paradime

# Create a Paradime client with your API credentials
paradime = Paradime(api_endpoint="API_ENDPOINT", api_secret="prdm_cmp_...", workspace_uid="WORKSPACE_UID")

# Send a follow-up to an existing session
paradime.dinoai_agents.send_message(
    agent_session_id="xwzdneft6emspe0f",
    message="Now also check stg_customers and post a summary to Slack.",
)

Get an agent run

Fetches the current state of a DinoAI agent run.

Args
Returns

agent_session_id (str): The session ID returned by trigger_run or send_message.

DinoaiAgentRun: Contains ok, status (one of QUEUED, RUNNING, COMPLETED, FAILED), messages (each with ts as a float epoch timestamp, role, content), child_session_ids (sub-agents spawned during the run), and workspace_uid.

# First party modules
from paradime import Paradime
from paradime.apis.dinoai_agents.types import DinoaiAgentRunStatus

# Create a Paradime client with your API credentials
paradime = Paradime(api_endpoint="API_ENDPOINT", api_secret="prdm_cmp_...", workspace_uid="WORKSPACE_UID")

# Poll the current state of a session
run = paradime.dinoai_agents.get_run(agent_session_id="xwzdneft6emspe0f")

print(f"Status: {run.status}")
for msg in run.messages:
    print(f"[{msg.role}] {msg.content}")

# Inspect child sessions (sub-agents spawned during the run)
for child_id in run.child_session_ids:
    child_run = paradime.dinoai_agents.get_run(agent_session_id=child_id)
    print(f"Child {child_id} status: {child_run.status}")

​Overview

​Trigger an agent run

​Trigger an agent run and wait for completion

​Send a follow-up message

​Get an agent run

Overview

Trigger an agent run

Trigger an agent run and wait for completion

Send a follow-up message

Get an agent run