DinoAI Programmable Agents

Overview

• This feature is available on workspaces with DinoAI programmable agents enabled.

• Your API keys must have access to the DinoAI Agents API.

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

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).

Returns

# First party modules
from paradime import Paradime

# Create a Paradime client with your API credentials
paradime = Paradime(api_endpoint="API_ENDPOINT", api_key="API_KEY", api_secret="API_SECRET")

# 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

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.

Returns

# First party modules
from paradime import Paradime

# Create a Paradime client with your API credentials
paradime = Paradime(api_endpoint="API_ENDPOINT", api_key="API_KEY", api_secret="API_SECRET")

# 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

agent_session_id (str): The session ID of the running agent.

message (str): The follow-up message to send.

Returns

# First party modules
from paradime import Paradime

# Create a Paradime client with your API credentials
paradime = Paradime(api_endpoint="API_ENDPOINT", api_key="API_KEY", api_secret="API_SECRET")

# 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

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

Returns

# 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_key="API_KEY", api_secret="API_SECRET")

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