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.

Optional[str]

Name of the YAML-defined agent to load (matches the file name under .dinoai/agents/ without the .yml extension).

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.

Optional[str]

Slack channel ID the run should post into (e.g. "C0123456789"). Must be provided together with slack_thread.

Optional[str]

Slack thread timestamp the run should reply in (e.g. "1714142436.001200"). Must be provided together with slack_channel.

Optional[str]

Git branch, tag or commit SHA the agent checks out before creating its working branch. Defaults to the repository’s default branch.

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.

Optional[str]

Name of the YAML-defined agent to load.

Optional[str]

Custom prompt appended to the agent’s context.

Optional[str]

Slack channel ID. Must be provided together with slack_thread.

Optional[str]

Slack thread timestamp. Must be provided together with slack_channel.

Optional[str]

Git branch, tag or commit SHA the agent checks out before creating its working branch. Defaults to the repository’s default branch.

int

default:"3600"

Maximum seconds to wait before raising TimeoutError.

int

default:"10"

Seconds between status polls.

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.

str

required

The session ID of the running agent.

str

required

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.

str

required

The session ID returned by trigger_run or send_message.

bool

default:"False"

Also return steps, every step so far with the tool calls, as the session panel in the app shows them, and startup_steps, the checklist while the agent pod boots. Added in SDK 6.8.0.

bool

default:"False"

With include_steps, also return each tool’s input and output. They can hold raw query results and file contents.

int

With include_steps, return only the steps with a greater index. Pass the last index you read to poll for new steps.

int

With include_steps, cut each step’s text at this length. Defaults to the backend’s limit.

DinoaiAgentRun

Contains ok, status (one of QUEUED, RUNNING, COMPLETED, FAILED, or EXPIRED; EXPIRED is terminal and means the agent pod never started), messages (what the agent delivered, each with ts as a string epoch timestamp, role, content), child_session_ids (sub-agents spawned during the run), and workspace_uid. With include_steps, also steps (each a DinoaiAgentStep with index, role, tool_name, tool_input, content, and truncated) and startup_steps (each a DinoaiAgentStartupStep with label and done). Both are None unless requested, or when the steps couldn’t be read.

# 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}")

API Keys & Access

GraphQL API

Python SDK

Paradime CLI

Webhooks

Virtual Environments

DinoAI Programmable Agents

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

Overview

Trigger an agent run

Trigger an agent run and wait for completion

Send a follow-up message

Get an agent run