> ## 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

> Trigger DinoAI programmable agent runs from Python, send prompts and follow-ups, poll status, and wait for completion using the paradime-io SDK.

### **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.

<ParamField path="agent" type="Optional[str]">
  Name of the YAML-defined agent to load (matches the file name under `.dinoai/agents/` without the `.yml` extension).
</ParamField>

<ParamField path="message" type="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.
</ParamField>

<ParamField path="slack_channel" type="Optional[str]">
  Slack channel ID the run should post into (e.g. `"C0123456789"`). Must be provided together with `slack_thread`.
</ParamField>

<ParamField path="slack_thread" type="Optional[str]">
  Slack thread timestamp the run should reply in (e.g. `"1714142436.001200"`). Must be provided together with `slack_channel`.
</ParamField>

<ParamField path="base_branch" type="Optional[str]">
  Git branch the agent checks out before creating its working branch. Defaults to the repository's default branch.
</ParamField>

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

<ResponseField name="Returns" type="DinoaiAgentTriggerResult">
  Contains `ok`, `agent_session_id`, and `status` (always the literal string `"queued"` on accept — poll with `get_run` for live status).
</ResponseField>

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

<ParamField path="agent" type="Optional[str]">
  Name of the YAML-defined agent to load.
</ParamField>

<ParamField path="message" type="Optional[str]">
  Custom prompt appended to the agent's context.
</ParamField>

<ParamField path="slack_channel" type="Optional[str]">
  Slack channel ID. Must be provided together with `slack_thread`.
</ParamField>

<ParamField path="slack_thread" type="Optional[str]">
  Slack thread timestamp. Must be provided together with `slack_channel`.
</ParamField>

<ParamField path="base_branch" type="Optional[str]">
  Git branch the agent checks out before creating its working branch. Defaults to the repository's default branch.
</ParamField>

<ParamField path="timeout" type="int" default="3600">
  Maximum seconds to wait before raising `TimeoutError`.
</ParamField>

<ParamField path="poll_interval" type="int" default="10">
  Seconds between status polls.
</ParamField>

<ResponseField name="Returns" type="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.
</ResponseField>

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

<ParamField path="agent_session_id" type="str" required>
  The session ID of the running agent.
</ParamField>

<ParamField path="message" type="str" required>
  The follow-up message to send.
</ParamField>

<ResponseField name="Returns" type="DinoaiAgentTriggerResult">
  Contains `ok`, `agent_session_id`, and `status` (always `"queued"` on accept).
</ResponseField>

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

<ParamField path="agent_session_id" type="str" required>
  The session ID returned by `trigger_run` or `send_message`.
</ParamField>

<ResponseField name="Returns" type="DinoaiAgentRun">
  Contains `ok`, `status` (one of `QUEUED`, `RUNNING`, `COMPLETED`, `FAILED`, or `EXPIRED` — `EXPIRED` is terminal and means the agent pod never started), `messages` (each with `ts` as a string epoch timestamp, `role`, `content`), `child_session_ids` (sub-agents spawned during the run), and `workspace_uid`.
</ResponseField>

```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)
- [DinoAI CLI](/developers/paradime-cli/dinoai-cli.md)
- [Build and deploy DinoAI agents from the app](/changelog/2026-08-05/build-agents-in-the-app.md)
- [Triggering from the API](/products/dino-ai/programmable-agents/api-reference.md)
- [Bolt Pipeline Healer](/guides/programmable-agents/bolt-pipeline-healer.md)