Schedule AI Agent Task CueAPI: Step by Step Tutorial

Your AI agent needs to run every morning at 9 AM to generate a market briefing. You set up a cron job, but three days later you discover the agent went quiet on Tuesday. No briefing was sent. Your users noticed before you did. This tutorial shows you how to schedule ai agent task cueapi with delivery confirmation, outcome tracking, and evidence collection. Never wonder if your agent worked again.

TL;DR: Build a scheduled AI agent task that reports what it actually did. Create a cue with retry logic, handle the webhook in your agent, report the outcome with evidence, and get real-time alerts when things break. Complete accountability in 6 steps.

Key Takeaways: - CueAPI delivers your task with signed payloads and at-least-once guarantee - Outcome tracking captures success/failure with evidence like tweet IDs or file paths - 3 retry attempts with exponential backoff (1, 5, 15 minutes) prevent silent failures - Evidence collection stores proof the business action actually happened - Sub-5 minute alerting tells you when your agent goes quiet

What You'll Build

A market briefing agent that runs every weekday at 9 AM. The agent generates a summary, posts it to social media, and reports back with the tweet ID as proof. You'll know within minutes if the agent fails, and you'll have evidence of every successful run.

Prerequisites

• Python 3.7+ environment
• A webhook endpoint (local tunnel, deployed server, or cloud function)
• 5 minutes to set up your first accountable agent task

ℹ️ Info: This tutorial works on any platform. Replit, Mac Mini, cloud server. Your agent runs wherever you put it. CueAPI makes it accountable wherever it runs.

Step 1: Get Your CueAPI Key

Sign up at https://dashboard.cueapi.ai/signup. Navigate to API Keys and create a new key. Copy the key starting with cue_sk_.

⚠️ Warning: Store your API key securely. Never commit it to version control.

Your key authenticates every request to CueAPI. Keep it safe.

Expected output:

cue_sk_1234567890abcdef1234567890abcdef

Step 2: Install HTTP Client

Install a HTTP client for API requests:

pip install requests

Or with curl, you'll use the REST API directly. Both approaches give you the same accountability features.

import requests
import os

✅ Success: HTTP client ready. Ready to create your first accountable agent task.

Step 3: Create Your First Cue

Understanding the Cue Structure

A cue is your agent's unit of accountable work. It contains the schedule, delivery configuration, retry policy, and outcome tracking settings.

Setting the Schedule

Create a cue that runs weekdays at 9 AM Eastern:

import requests
import os

def create_cue():
    url = "https://api.cueapi.ai/v1/cues"
    headers = {
        "Authorization": f"Bearer {os.getenv('CUEAPI_KEY')}",
        "Content-Type": "application/json"
    }
    
    cue_data = {
        "name": "market-briefing",
        "description": "Daily market summary and social post",
        "schedule": {
            "type": "recurring",
            "cron": "0 9 * * 1-5",
            "timezone": "America/New_York"
        },
        "transport": "webhook",
        "callback": {
            "url": "https://your-agent.com/briefing",
            "method": "POST",
            "headers": {"X-Secret": "your-webhook-secret"}
        },
        "payload": {"task": "generate_briefing", "format": "twitter"},
        "retry": {
            "max_attempts": 3,
            "backoff_minutes": [1, 5, 15]
        },
        "on_failure": {
            "email": True,
            "pause": False
        }
    }
    
    response = requests.post(url, headers=headers, json=cue_data)
    cue = response.json()
    print(f"Cue created: {cue['id']}")
    return cue

create_cue()

Equivalent curl request:

curl -X POST https://api.cueapi.ai/v1/cues \
  -H "Authorization: Bearer cue_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "market-briefing",
    "description": "Daily market summary and social post",
    "schedule": {
      "type": "recurring",
      "cron": "0 9 * * 1-5",
      "timezone": "America/New_York"
    },
    "transport": "webhook",
    "callback": {
      "url": "https://your-agent.com/briefing",
      "method": "POST",
      "headers": {"X-Secret": "your-webhook-secret"}
    },
    "payload": {"task": "generate_briefing", "format": "twitter"},
    "retry": {
      "max_attempts": 3,
      "backoff_minutes": [1, 5, 15]
    },
    "on_failure": {
      "email": true,
      "pause": false
    }
  }'

📝 Note: The cron expression 0 9 1-5 means "9 AM on weekdays." CueAPI supports standard cron syntax with timezone support.

Configuring the Callback

The callback URL is where CueAPI delivers your scheduled task. Your agent receives a signed payload with execution details.

Expected output:

{
  "id": "cue_7890abcd1234efgh",
  "name": "market-briefing",
  "status": "active",
  "next_execution": "2024-03-25T14:00:00Z"
}

Step 4: Handle the Execution

Receiving the Webhook

Your agent receives this payload when the cue fires:

{
  "execution_id": "exec_1234567890abcdef",
  "cue_id": "cue_7890abcd1234efgh",
  "scheduled_at": "2024-03-25T14:00:00Z",
  "attempt": 1,
  "payload": {"task": "generate_briefing", "format": "twitter"},
  "signature": "sha256=abc123..."
}

Handle it in your agent:

from flask import Flask, request, jsonify
import hmac
import hashlib
import os

app = Flask(__name__)

@app.route('/briefing', methods=['POST'])
def handle_briefing():
    # Verify signature
    signature = request.headers.get('X-CueAPI-Signature')
    body = request.get_data()
    expected = hmac.new(
        os.getenv('WEBHOOK_SECRET').encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    
    if not hmac.compare_digest(f"sha256={expected}", signature):
        return jsonify({"error": "Invalid signature"}), 401
    
    execution_data = request.json
    execution_id = execution_data['execution_id']
    
    # Your agent logic here
    try:
        briefing = generate_market_briefing()
        tweet_id = post_to_twitter(briefing)
        
        # Report success with evidence
        report_outcome(execution_id, True, tweet_id, briefing[:100])
        return jsonify({"status": "success"})
        
    except Exception as e:
        # Report failure
        report_outcome(execution_id, False, None, str(e))
        return jsonify({"status": "error"}), 500

def generate_market_briefing():
    # Your AI agent logic
    return "Market opened strong at 9 AM. Tech stocks up 2.1%."

def post_to_twitter(content):
    # Your Twitter API logic
    return "1234567890123456789"  # Tweet ID

📝 Note: Always verify the signature to ensure the request came from CueAPI. This prevents malicious webhook calls.

Reporting the Outcome

Tell CueAPI what your agent actually did:

def report_outcome(execution_id, success, tweet_id, summary):
    import requests
    
    outcome_data = {
        "success": success,
        "result": summary,
        "metadata": {"tweet_id": tweet_id} if tweet_id else None
    }
    
    response = requests.post(
        f"https://api.cueapi.ai/v1/executions/{execution_id}/outcome",
        headers={
            "Authorization": f"Bearer {os.getenv('CUEAPI_KEY')}",
            "Content-Type": "application/json"
        },
        json=outcome_data
    )
    return response.json()

Using requests:

import requests
import os

def report_outcome(execution_id, success, result, metadata=None, summary=None):
    url = f"https://api.cueapi.ai/v1/executions/{execution_id}/outcome"
    headers = {
        "Authorization": f"Bearer {os.getenv('CUEAPI_KEY')}",
        "Content-Type": "application/json"
    }
    
    data = {
        "success": success,
        "result": result,
        "metadata": metadata,
        "summary": summary
    }
    
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# Report success
report_outcome(
    "exec_1234567890abcdef",
    success=True,
    result="Posted market briefing to Twitter",
    metadata={"tweet_id": "1234567890123456789"},
    summary="Market opened strong, tech up 2.1%"
)

Expected output:

{
  "execution_id": "exec_1234567890abcdef",
  "outcome_recorded_at": "2024-03-25T14:02:15Z",
  "success": true
}

Step 5: Add Evidence for Verification

Append evidence to prove the business action happened:

def append_evidence(execution_id, external_id, result_url, result_type, summary):
    url = f"https://api.cueapi.ai/v1/executions/{execution_id}/evidence"
    headers = {
        "Authorization": f"Bearer {os.getenv('CUEAPI_KEY')}",
        "Content-Type": "application/json"
    }
    
    data = {
        "external_id": external_id,
        "result_url": result_url,
        "result_type": result_type,
        "summary": summary
    }
    
    response = requests.patch(url, headers=headers, json=data)
    return response.json()

# Add the tweet as evidence
append_evidence(
    "exec_1234567890abcdef",
    external_id="1234567890123456789",
    result_url="https://twitter.com/yourhandle/status/1234567890123456789",
    result_type="tweet",
    summary="Market briefing posted successfully"
)

With curl:

curl -X PATCH https://api.cueapi.ai/v1/executions/exec_1234567890abcdef/evidence \
  -H "Authorization: Bearer cue_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "1234567890123456789",
    "result_url": "https://twitter.com/yourhandle/status/1234567890123456789",
    "result_type": "tweet",
    "summary": "Market briefing posted successfully"
  }'

✅ Success: Evidence recorded. You now have verified success, not just reported success.

Expected output:

{
  "evidence_id": "evd_abcd1234efgh5678",
  "execution_id": "exec_1234567890abcdef",
  "recorded_at": "2024-03-25T14:02:30Z"
}

Step 6: Test and Monitor

Viewing Execution History

Check your executions in the CueAPI dashboard or via API:

def get_executions(cue_id, limit=10):
    url = f"https://api.cueapi.ai/v1/cues/{cue_id}/executions"
    headers = {
        "Authorization": f"Bearer {os.getenv('CUEAPI_KEY')}"
    }
    params = {"limit": limit}
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Get recent executions
executions = get_executions("cue_7890abcd1234efgh", limit=10)

for execution in executions['data']:
    print(f"Execution {execution['id']}: {execution['outcome']['success']}")
    if execution['evidence']:
        print(f"  Evidence: {execution['evidence']['result_url']}")

Setting Up Failure Alerts

CueAPI sends you an email when your cue fails. You configured this with "on_failure": {"email": True}. You can also add webhook alerts:

def update_cue(cue_id, updates):
    url = f"https://api.cueapi.ai/v1/cues/{cue_id}"
    headers = {
        "Authorization": f"Bearer {os.getenv('CUEAPI_KEY')}",
        "Content-Type": "application/json"
    }
    
    response = requests.patch(url, headers=headers, json=updates)
    return response.json()

# Update cue to add webhook alerts
update_cue("cue_7890abcd1234efgh", {
    "on_failure": {
        "email": True,
        "webhook": "https://your-monitoring.com/alert"
    }
})

📝 Note: Alerts fire after all retry attempts are exhausted. You get one alert per failed execution, not per retry.

Platform Scheduler vs CueAPI Comparison

The key difference: platform schedulers fire jobs into the void. CueAPI creates accountability between your schedule and your agent's work.

Common Pitfalls

Pitfall 1: Not verifying webhook signatures Your agent should always verify the signature to prevent malicious requests. See the Flask example above for proper signature verification.

Pitfall 2: Forgetting to report outcomes If your agent doesn't call the outcome endpoint, CueAPI marks the execution as "no outcome reported." This counts as an accountability gap.

Pitfall 3: Reporting success too early Report the outcome after your business action completes, not when the webhook is received. The outcome represents whether the work actually happened.

⚠️ Warning: Don't report success when your agent starts. Report success when your agent finishes the actual work.

Next Steps

Now you have an accountable AI agent. Here's what to explore next:

1. Add verification: Use CueAPI's outcome tracking to automatically check if your evidence is valid
2. Scale up: Create multiple cues for different agent tasks
3. Monitor trends: Track success rates and execution timing in the dashboard
4. Handle dependencies: Chain cues together for multi-step agent workflows

This tutorial taught you the fundamental pattern: Schedule -> Deliver -> Confirm. Your agent now runs reliably, reports what it did, and proves the work happened. That's the difference between hoping your agent worked and knowing it did.

Try it yourself. Free tier available. Get started at https://dashboard.cueapi.ai/signup and make your agents accountable.

Frequently Asked Questions

How long does CueAPI wait for my agent to report the outcome?

CueAPI waits for your agent to report the outcome. You should report outcomes within a reasonable timeframe after receiving the webhook to maintain accountability.

What happens if my webhook endpoint is down?

CueAPI retries the webhook delivery 3 times with exponential backoff (1, 5, 15 minutes). If all attempts fail, you get a failure alert and the execution is marked as failed delivery.

Can I pause a cue temporarily?

Yes. You can update your cue settings or set "pause": true in the failure settings to auto-pause after failures. Paused cues don't generate new executions until you resume them.

How do I test my webhook locally?

Use ngrok, localtunnel, or similar tools to expose your local server. Point the cue's callback URL to the public tunnel URL. CueAPI needs a publicly accessible endpoint to deliver webhooks.

What's the difference between metadata and evidence?

Metadata is structured data you send with the outcome report. Evidence is append-only proof that business actions happened. Use metadata for debugging info, evidence for verification that work actually completed.

Sources

• CueAPI API Reference: Full REST API documentation: https://docs.cueapi.ai/api-reference/overview/
• Replit: Cloud development platform: https://replit.com

About the author: Govind Kavaturi is co-founder of Vector, a portfolio of AI-native products. He believes the next phase of the internet is built for agents, not humans.