> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paradime.io/llms.txt
> Use this file to discover all available pages before exploring further.

# DinoAI Programmable Agents

### **Overview**

<Info>
  **Prerequisites:**

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

<Info>
  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.
</Info>

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.

<Tabs>
  <Tab title="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`.

    <Warning>
      `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).
    </Warning>
  </Tab>

  <Tab title="Returns">
    *`DinoaiAgentTriggerResult`*: Contains `ok`, `agent_session_id`, and `status` (always the literal string `"queued"` on accept — poll with `get_run` for live status).
  </Tab>
</Tabs>

```python theme={"system"}
# 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`.

<Tabs>
  <Tab title="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`.
  </Tab>

  <Tab title="Returns">
    *`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.
  </Tab>
</Tabs>

```python theme={"system"}
# 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.

<Tabs>
  <Tab title="Args">
    **`agent_session_id`** *`(str)`*: The session ID of the running agent.

    **`message`** *`(str)`*: The follow-up message to send.
  </Tab>

  <Tab title="Returns">
    *`DinoaiAgentTriggerResult`*: Contains `ok`, `agent_session_id`, and `status` (always `"queued"` on accept).
  </Tab>
</Tabs>

```python theme={"system"}
# 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.

<Tabs>
  <Tab title="Args">
    **`agent_session_id`** *`(str)`*: The session ID returned by `trigger_run` or `send_message`.
  </Tab>

  <Tab title="Returns">
    *`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`.
  </Tab>
</Tabs>

```python theme={"system"}
# 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}")
```


## Related topics

- [DinoAI Programmable Agents API](/developers/graphql-api/api-reference/dinoai-programmable-agents-api.md)
- [Paradime DinoAI Agent Trigger](/products/bolt/creating-schedules/command-settings/paradime-dinoai-agent-trigger.md)
- [DinoAI CLI](/developers/paradime-cli/dinoai-cli.md)
- [DinoAI Agent](/guides/paradime-101/getting-started-with-the-paradime-ide/dinoai-accelerating-your-analytics-engineering-workflow/dinoai-agent/index.md)
- [Programmable Agents](/products/dino-ai/programmable-agents/index.md)