Task Design & Prompting

Quick Reference

Clear instructions = better results. Be specific about sources, data fields, and output format.

✅ Good: Specific & Structured

JavaScript
Python
HTTPie

const result = await session.runTask(`
    Find iPhone 15 Pro prices on:
    - Amazon.com
    - BestBuy.com
    - Apple.com

    For each retailer, provide:
    - Base price (128GB model)
    - Availability (in stock / out of stock)
    - Product URL

    Return as JSON array:
    [{"retailer": "Amazon", "price": 999.99, "available": true, "url": "..."}]
`);

result = session.run_task("""
    Find iPhone 15 Pro prices on:
    - Amazon.com
    - BestBuy.com
    - Apple.com

    For each retailer, provide:
    - Base price (128GB model)
    - Availability (in stock / out of stock)
    - Product URL

    Return as JSON array:
    [{"retailer": "Amazon", "price": 999.99, "available": true, "url": "..."}]
""")

http POST https://api.agi.tech/v1/sessions/$SESSION/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Find iPhone 15 Pro prices on: Amazon.com, BestBuy.com, Apple.com. For each retailer, provide: Base price (128GB model), Availability (in stock / out of stock), Product URL. Return as JSON array."

❌ Bad: Vague & Unstructured

JavaScript
Python
HTTPie

const result = await session.runTask('Check iPhone prices');

result = session.run_task("Check iPhone prices")

http POST https://api.agi.tech/v1/sessions/$SESSION/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Check iPhone prices"

Always Request JSON

Request structured output for easy parsing.

JavaScript
Python
HTTPie

const result = await session.runTask(`
    Extract product info and return as JSON:
    {"name": "...", "price": 99.99, "in_stock": true, "url": "..."}
    
    Return ONLY valid JSON, no markdown.
`);

result = session.run_task("""
    Extract product info and return as JSON:
    {"name": "...", "price": 99.99, "in_stock": true, "url": "..."}
    
    Return ONLY valid JSON, no markdown.
""")

http POST https://api.agi.tech/v1/sessions/$SESSION/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Extract product info and return as JSON: {\"name\": \"...\", \"price\": 99.99, \"in_stock\": true, \"url\": \"...\"}. Return ONLY valid JSON, no markdown."

Break Down Complex Tasks

Split complex workflows into smaller steps.

JavaScript
Python
HTTPie

const session = await client.createSession('agi-0');
try {
    // Step 1: Get specs
    const specs = await session.runTask('Find iPhone 15 Pro specifications. Return JSON.');
    
    // Step 2: Find prices
    const prices = await session.runTask('Find iPhone 15 Pro prices on Amazon, Best Buy, Apple. Return JSON array.');
} finally {
    await session.delete();
}

with client.session("agi-0") as session:
    # Step 1: Get specs
    specs = session.run_task("Find iPhone 15 Pro specifications. Return JSON.")
    
    # Step 2: Find prices
    prices = session.run_task("Find iPhone 15 Pro prices on Amazon, Best Buy, Apple. Return JSON array.")

# Step 1: Get specs
http POST https://api.agi.tech/v1/sessions/$SESSION/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Find iPhone 15 Pro specifications. Return JSON."

# Step 2: Find prices
http POST https://api.agi.tech/v1/sessions/$SESSION/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Find iPhone 15 Pro prices on Amazon, Best Buy, Apple. Return JSON array."

Handle Edge Cases

Tell agents how to handle missing data.

JavaScript
Python
HTTPie

const result = await session.runTask(`
    Find product prices on Amazon.
    
    If out of stock: Set "available": false
    If price not found: Set "price": null
    If product doesn't exist: Return {"error": "Product not found"}
    
    Always return valid JSON.
`);

result = session.run_task("""
    Find product prices on Amazon.
    
    If out of stock: Set "available": false
    If price not found: Set "price": null
    If product doesn't exist: Return {"error": "Product not found"}
    
    Always return valid JSON.
""")

http POST https://api.agi.tech/v1/sessions/$SESSION/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Find product prices on Amazon. If out of stock: Set \"available\": false. If price not found: Set \"price\": null. If product doesn't exist: Return {\"error\": \"Product not found\"}. Always return valid JSON."

Key Principles

Be Specific

Provide exact sources, formats, and data fields

Request JSON

Always request structured output for easy parsing

Break It Down

Split complex workflows into smaller steps

Handle Edge Cases

Tell agents how to handle missing data

Next Steps

Session Management

Managing sessions effectively

Use Cases

Real-world examples

Getting Started

Use Cases

Best Practices

Advanced

Troubleshooting

Quick Reference

✅ Good: Specific & Structured

❌ Bad: Vague & Unstructured

Always Request JSON

Break Down Complex Tasks

Handle Edge Cases

Key Principles

Be Specific

Request JSON

Break It Down

Handle Edge Cases

Next Steps

Session Management

Use Cases

Getting Started

Use Cases

Best Practices

Advanced

Troubleshooting

​Quick Reference

​✅ Good: Specific & Structured

​❌ Bad: Vague & Unstructured

​Always Request JSON

​Break Down Complex Tasks

​Handle Edge Cases

​Key Principles

Be Specific

Request JSON

Break It Down

Handle Edge Cases

​Next Steps

Session Management

Use Cases

Quick Reference

✅ Good: Specific & Structured

❌ Bad: Vague & Unstructured

Always Request JSON

Break Down Complex Tasks

Handle Edge Cases

Key Principles

Next Steps