Building Outcome Agents

Overview

Outcome agents are autonomous systems that manage tactics on behalf of advertisers. Think of an outcome agent as a specialized optimizer trained to buy media according to specific strategies and constraints. For example: “Using a brand story as targeting, acquire the lowest vCPM for banner ads. Don’t spend more than $5 CPM, but target$ 2.50 CPM and 85% viewability. Keep within the property list provided by the advertiser, and only buy in specified countries.”

What You’re Building

You’re implementing an outcome agent server that runs on YOUR infrastructure and exposes endpoints for:

Proposing tactics when campaigns are created (/get-proposals)
Accepting proposal assignments (/accept-proposal)
Receiving updates about tactic changes and performance feedback

This runs on YOUR infrastructure, not in Scope3’s codebase. Scope3’s platform will call your endpoints to collaborate with your agent.

How It Works in Practice

When setting up a campaign, Scope3:

Calls your /get-proposals endpoint with campaign details
Your agent analyzes the campaign and proposes tactics with budget capacity and pricing
Advertiser selects tactics (potentially from multiple outcome agents)
Scope3 calls your /accept-proposal endpoint to assign the tactic to you
Your agent manages the tactic: selects sales agents, creates media buys, optimizes delivery
Scope3 sends updates via your endpoints when tactics change or to provide performance feedback

Core Responsibilities

Your outcome agent IS responsible for:

Proposing tactics that fit campaign requirements
Creating and managing media buys via Scope3’s platform APIs
Ensuring delivery of the tactic’s budget
Optimizing toward campaign objectives
Responding to tactic updates and changes

Your outcome agent is NOT responsible for:

Creative management and approval (handled by advertiser)
Brand safety and suitability (handled by Scope3)

Your agent MAY:

Take a margin (fee) for services
Use proprietary accounts at sales agents
Leverage custom signals and data
Provide creative services (bundling a creative agent)

Pricing Models

Your agent can charge fees in three ways:

Passthrough

No markup on media costs. Makes sense when you control the underlying sales agent. Markup the cost of media buys by a percentage (e.g., 15%).

Cost Per Unit

Charge per impression/view/click/conversion, potentially different from underlying costs.

Implementation Guide

1. Implement Required Endpoints

Your server must implement these endpoints:

`/get-proposals` (POST)

Scope3 calls this when setting up a campaign. Analyze the campaign and respond with tactics you can handle. Request from Scope3:

{
  "campaignId": "camp_123",
  "budgetRange": {
    "min": 50000,
    "max": 150000,
    "currency": "USD"
  },
  "startDate": "2025-01-01T00:00:00Z",
  "endDate": "2025-01-31T23:59:59Z",
  "channels": ["display", "video"],
  "countries": ["US", "CA"],
  "objectives": ["awareness"],
  "brief": "Launch campaign for new product...",
  "brandManifest": {},
  "acceptedPricingMethods": ["cpm", "vcpm", "revshare"],
  "promotedOfferings": ["premium-inventory"],
  "seatId": "seat_456"
}

Your Response:

{
  "proposals": [
    {
      "tacticId": "premium-vcpm-display",
      "execution": "Target premium inventory at $2.50 vCPM with 85% viewability",
      "budgetCapacity": 50000,
      "pricing": {
        "method": "vcpm",
        "rate": 2.50,
        "currency": "USD"
      },
      "sku": "premium-vcpm",
      "customFieldsRequired": [
        {
          "fieldName": "targetVCPM",
          "fieldType": "number",
          "description": "Target vCPM in USD"
        }
      ]
    }
  ]
}

`/accept-proposal` (POST)

Scope3 calls this when your proposal is accepted and you are assigned to manage a tactic. Accept or decline the assignment. Request from Scope3:

{
  "tacticId": "premium-vcpm-display",
  "tacticContext": {
    "budget": 50000,
    "budgetCurrency": "USD",
    "startDate": "2025-01-01T00:00:00Z",
    "endDate": "2025-01-31T23:59:59Z",
    "channel": "display",
    "countries": ["US"],
    "creatives": [
      {
        "creativeId": "cr_001",
        "format": "banner_300x250",
        "assetUrl": "https://cdn.scope3.com/creative.jpg"
      }
    ],
    "brandStandards": {}
  },
  "brandAgentId": "ba_123",
  "seatId": "seat_456",
  "customFields": {
    "targetVCPM": 2.5
  }
}

Your Response:

{
  "acknowledged": true
}

Or decline:

{
  "acknowledged": false,
  "reason": "Insufficient budget for effective optimization"
}

`/tactic-context-updated` (POST)

Scope3 calls this when a tactic is modified (budget, schedule, etc.). Your agent MUST handle these changes. Request from Scope3:

{
  "tacticId": "premium-vcpm-display",
  "tactic": {
    "budget": 60000,
    "startDate": "2025-01-01T00:00:00Z"
  },
  "patch": [
    {
      "op": "replace",
      "path": "/budget",
      "value": 60000
    }
  ]
}

Your Response: 200 OK

`/tactic-creatives-updated` (POST)

Scope3 calls this when creatives are added, removed, or modified.

`/tactic-feedback` (POST)

Scope3 sends performance feedback to help you optimize. Your agent MAY use this to adjust tactics. Request from Scope3:

{
  "tacticId": "premium-vcpm-display",
  "startDate": "2025-01-01T00:00:00Z",
  "endDate": "2025-01-07T23:59:59Z",
  "deliveryIndex": 95,
  "performanceIndex": 110
}

deliveryIndex: 100 = on target, <100 = under-delivering
performanceIndex: 100 = maximum performance

2. Authentication

Your server must authenticate Scope3’s requests. Supported methods:

API Key: Scope3 sends X-API-Key header
Bearer Token: OAuth-based JWT authentication
Basic Auth: Username/password

Provide your authentication requirements when registering your media agent with Scope3.

3. Use Scope3’s Platform APIs

To manage tactics, your agent calls Scope3’s platform APIs:

Get Sales Agent Products

curl https://api.agentic.scope3.com/rest/v1/get-products \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"channels": ["display"], "countries": ["US"]}'

Create Media Buy

curl https://api.agentic.scope3.com/rest/v1/create-media-buy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "tacticId": "premium-vcpm-display",
    "productId": "prod_456",
    "budget": 10000
  }'

Update Tactic Targeting

curl https://api.agentic.scope3.com/rest/v1/update-targeting \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "tacticId": "premium-vcpm-display",
    "segments": ["premium-auto-enthusiasts"],
    "frequencyCap": {"impressions": 5, "period": "day"}
  }'

See the main API Reference for all available endpoints.

4. Example Implementation

Here’s a basic media agent server:

const express = require('express');
const app = express();

app.use(express.json());

// Middleware to authenticate Scope3's requests
app.use((req, res, next) => {
  const apiKey = req.headers['x-api-key'];
  if (apiKey !== process.env.SCOPE3_API_KEY) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
});

// Propose tactics for campaigns
app.post('/get-proposals', async (req, res) => {
  const { campaignId, budgetRange, channels, seatId } = req.body;

  // Analyze campaign and determine if we can handle it
  const canHandle = await analyzeCampaign({ channels, budgetRange });

  if (!canHandle) {
    return res.json({ proposals: [] });
  }

  // Propose tactics with pricing
  res.json({
    proposals: [
      {
        tacticId: generateTacticId(),
        execution: "Our optimization strategy...",
        budgetCapacity: calculateCapacity(budgetRange),
        pricing: {
          method: "vcpm",
          rate: 2.50,
          currency: "USD"
        }
      }
    ]
  });
});

// Accept or decline proposal assignment
app.post('/accept-proposal', async (req, res) => {
  const { tacticId, proposalId, tacticContext, customFields, proposal_context } = req.body;

  try {
    // Set up tactic management
    await setupTactic(tacticId, proposalId, tacticContext, customFields, proposal_context);

    // Acknowledge assignment
    res.json({ acknowledged: true });

    // Start optimization process (async)
    optimizeTactic(tacticId).catch(console.error);
  } catch (error) {
    res.json({
      acknowledged: false,
      reason: error.message
    });
  }
});

// Handle tactic updates
app.post('/tactic-context-updated', async (req, res) => {
  const { tacticId, tactic, patch } = req.body;

  await updateTacticConfig(tacticId, patch);

  res.status(200).send();
});

// Handle performance feedback
app.post('/tactic-feedback', async (req, res) => {
  const { tacticId, deliveryIndex, performanceIndex } = req.body;

  if (deliveryIndex < 90) {
    await adjustBudgetAllocation(tacticId);
  }

  res.status(200).send();
});

app.listen(3000, () => {
  console.log('Media agent server running on port 3000');
});

5. Register with Scope3

Once your server is running, register with Scope3:

curl -X POST https://api.agentic.scope3.com/rest/v1/outcome-agent-register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vCPM Optimizer Pro",
    "description": "Optimizes for lowest vCPM with high viewability",
    "endpointUrl": "https://media-agent.yourcompany.com",
    "authenticationType": "API_KEY",
    "supportedChannels": ["display", "video"],
    "supportedCountries": ["US", "CA", "GB"]
  }'

Best Practices

Endpoint Reliability

Respond within 10 seconds
Return proper HTTP status codes
Handle retries gracefully (Scope3 retries with exponential backoff)
Implement idempotency for all operations

Budget Management

Don’t over-allocate budget across media buys
Monitor delivery closely
Pause under-performing buys quickly
Leave 10-15% buffer for fluctuations

Optimization Strategy

Start conservative, scale winners
Use historical data when available
Respect brand standards and targeting constraints
Document your optimization logic for transparency

Error Handling

Decline tactics you can’t fulfill
Provide clear error messages
Maintain fallback strategies
Log all interactions for debugging

Testing Your Agent

Before going live:

Endpoint testing - Verify all required endpoints respond correctly
Tactic proposal logic - Test with various campaign types and budgets
Budget allocation - Ensure you don’t over-commit
Optimization - Validate with historical data
Edge cases - Handle budget changes, creative updates, pauses

Use Scope3’s staging environment for testing (contact your account manager for access).

Going Live

Once tested:

Deploy your media agent server to production
Register with Scope3 production environment
Request review from Scope3 team
Monitor initial campaigns closely
Gather feedback and iterate

Support Resources

API Documentation: See Outcome Agent API Reference
OpenAPI Spec: Download outcome-agent-openapi.yaml
Platform APIs: See main API Reference for calling Scope3
Technical Support: [email protected]
Partnership Inquiries: [email protected]

Getting Started

Publisher Integration

Ad Network Integration

Outcome Agent Integration

Signals Management

Overview

What You’re Building

How It Works in Practice

Core Responsibilities

Pricing Models

Passthrough

Cost Per Unit

Implementation Guide

1. Implement Required Endpoints

`/get-proposals` (POST)

`/accept-proposal` (POST)

`/tactic-context-updated` (POST)

`/tactic-creatives-updated` (POST)

`/tactic-feedback` (POST)

2. Authentication

3. Use Scope3’s Platform APIs

Get Sales Agent Products

Create Media Buy

Update Tactic Targeting

4. Example Implementation

5. Register with Scope3

Best Practices

Endpoint Reliability

Budget Management

Optimization Strategy

Error Handling

Testing Your Agent

Going Live

Support Resources

Getting Started

Publisher Integration

Ad Network Integration

Outcome Agent Integration

Signals Management

​Overview

​What You’re Building

​How It Works in Practice

​Core Responsibilities

​Pricing Models

​Passthrough

​Revenue Share

​Cost Per Unit

​Implementation Guide

​1. Implement Required Endpoints

​/get-proposals (POST)

​/accept-proposal (POST)

​/tactic-context-updated (POST)

​/tactic-creatives-updated (POST)

​/tactic-feedback (POST)

​2. Authentication

​3. Use Scope3’s Platform APIs

​Get Sales Agent Products

​Create Media Buy

​Update Tactic Targeting

​4. Example Implementation

​5. Register with Scope3

​Best Practices

​Endpoint Reliability

​Budget Management

​Optimization Strategy

​Error Handling

​Testing Your Agent

​Going Live

​Support Resources

Overview

What You’re Building

How It Works in Practice

Core Responsibilities

Pricing Models

Passthrough

Revenue Share

Cost Per Unit

Implementation Guide

1. Implement Required Endpoints

`/get-proposals` (POST)

`/accept-proposal` (POST)

`/tactic-context-updated` (POST)

`/tactic-creatives-updated` (POST)

`/tactic-feedback` (POST)

2. Authentication

3. Use Scope3’s Platform APIs

Get Sales Agent Products

Create Media Buy

Update Tactic Targeting

4. Example Implementation

5. Register with Scope3

Best Practices

Endpoint Reliability

Budget Management

Optimization Strategy

Error Handling

Testing Your Agent

Going Live

Support Resources