Hyperfold AI
Back

Dec 18, 2025

Building a Negotiator Agent

H
Hyperfold Team
AgentsNegotiationPricing

Introduction

The Negotiator Agent is the core of Hyperfold's agentic commerce platform. It handles product discovery, price negotiation, and checkout flows with buyer agents following the Agentic Commerce Protocol (ACP).

In this cookbook, you'll build a fully functional Negotiator Agent that can negotiate prices dynamically based on customer context, maintain margin guardrails, and suggest product bundles.

Project Setup

First, initialize a new Hyperfold agent project:

bash
1
2
3
4
5
6
7
8
9
# Create new agent project
$ hyperfold agents init negotiator-agent --template=negotiator
 
# Install dependencies
$ cd negotiator-agent && pnpm install
 
# Configure your environment
$ cp .env.example .env
# Add your OPENAI_API_KEY and GCP credentials

Agent Structure

The agent uses decorators from the Actions SDK to define its behavior. Here's the core structure:

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import { HyperfoldAgent, OnACPEvent } from '@hyperfold/sdk';
import { getProduct, calculateDynamicPrice, getCustomerContext } from '@hyperfold/tools';
 
@HyperfoldAgent({
  name: 'negotiator-agent',
  version: '1.0.0',
  model: 'gpt-4o',
  systemPrompt: `You are a sales negotiation agent for Acme Sports.
Your goal is to maximize revenue while maintaining customer satisfaction.
- Always be professional and helpful
- Offer reasonable discounts based on customer tier
- Suggest bundles when appropriate
- Never go below the floor price`
})
export class NegotiatorAgent {
  @OnACPEvent('search')
  async handleSearch(query: string, filters: any) {
    // Semantic product search implementation
  }
 
  @OnACPEvent('quote')
  async handleQuote(productId: string, offer: number) {
    // Price negotiation logic
  }
 
  @OnACPEvent('checkout.init')
  async handleCheckoutInit(items: CartItem[]) {
    // Checkout initialization
  }
}

Pricing Logic

The pricing logic determines how your agent responds to offers. This includes customer-tier discounts, margin guardrails, and counter-offer strategies:

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
// pricing-logic.ts
import { calculateDynamicPrice, getCustomerContext } from '@hyperfold/tools';
 
interface PricingContext {
  customerId?: string;
  offerPrice: number;
  product: Product;
}
 
export async function negotiatePrice(ctx: PricingContext) {
  const { customerId, offerPrice, product } = ctx;
 
  // Get customer context for personalized pricing
  const customer = customerId
    ? await getCustomerContext(customerId)
    : { tier: 'standard', purchaseHistory: 0 };
 
  // Calculate dynamic price with margin guardrails
  const pricing = await calculateDynamicPrice(product, {
    customerTier: customer.tier,
    purchaseHistory: customer.purchaseHistory,
  });
 
  // Determine response based on offer vs. floor
  if (offerPrice >= pricing.suggested) {
    return {
      status: 'accept',
      price: offerPrice,
      message: 'Great! I can do that price for you.'
    };
  }
 
  if (offerPrice >= pricing.floor) {
    // Counter-offer between their offer and our suggested
    const counterPrice = Math.round(
      (offerPrice + pricing.suggested) / 2 * 100
    ) / 100;
 
    return {
      status: 'counter_offer',
      price: counterPrice,
      reasoning: `Based on your ${customer.tier} membership, I can offer ${counterPrice}`,
    };
  }
 
  // Below floor - reject with hint
  return {
    status: 'reject',
    reason: 'Price below minimum threshold',
    floorHint: `Our best possible price is around $${pricing.floor}`,
  };
}
Always enforce margin guardrails. The floor price should never be crossed regardless of negotiation pressure.

ACP Endpoints

Your agent automatically exposes ACP endpoints when deployed. Buyer agents discover these via your manifest at /.well-known/acp/manifest.json.

  • POST /acp/search - Semantic product search
  • POST /acp/quote - Price negotiation
  • POST /acp/checkout/init - Initialize checkout
  • POST /acp/checkout/finalize - Complete purchase

Deployment

Deploy your agent to production:

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Deploy the negotiator agent
$ hyperfold agents deploy ./negotiator-agent
 
> [Build] Compiling TypeScript...
> [Package] Creating container image...
> [Deploy] Pushing to Cloud Run...
> [Configure] Setting up ACP endpoints...
 
✓ Agent deployed!
 
  Name:     negotiator-agent
  URL:      https://negotiator-xyz.run.app
  ACP:      https://negotiator-xyz.run.app/.well-known/acp/manifest.json
 
# Verify ACP manifest
$ curl https://negotiator-xyz.run.app/.well-known/acp/manifest.json
Your Negotiator Agent is now live! Test it with the simulation command or connect a real buyer agent.