Triggering from the API

Programmable Agents can be triggered from your own code over GraphQL or with the Paradime Python SDK. The endpoints are the same — pick whichever fits your stack.

• GraphQL — full reference and cURL examples in Developers → GraphQL API → DinoAI Programmable Agents API.

• Python SDK — full reference and Python examples in Developers → Python SDK → DinoAI Programmable Agents.

Prerequisites

• An agent defined under .dinoai/agents/.yml in your repository — see YAML Configuration.

• An API key with DinoAI Agent capabilities.

GraphQL — quick example

curl -X POST $PARADIME_API_ENDPOINT \
  -H "X-API-KEY: $PARADIME_API_KEY" \
  -H "X-API-SECRET: $PARADIME_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation Trigger($agent: String, $message: String) { triggerDinoaiAgentRun(agent: $agent, message: $message) { ok agentSessionId status } }",
    "variables": {"agent": "data-quality-checker", "message": "Focus on stg_orders"}
  }'

Save the returned agentSessionId and poll with dinoaiAgentRun(agentSessionId: $id) until status reaches COMPLETED or FAILED. See the full GraphQL reference for the trigger, poll, and follow-up operations.

---

Python SDK — quick example

from paradime import Paradime

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_and_wait(
    agent="data-quality-checker",
    message="Focus on stg_orders",
)

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

See the full Python SDK reference for trigger_run, trigger_and_wait, send_message, and get_run.

Related

• Quick Start — End-to-end first-run walkthrough

• Triggering from Bolt — Alternative invocation path via a Bolt schedule

• Agent-to-Agent Delegation — Multi-agent workflows