Hyperfold AI

Your First Agent

Build and deploy a negotiator agent that can haggle with customers in real-time.

Overview

In this tutorial, you'll create a Negotiator Agent—the "Salesperson" of your agentic store. This agent sits at the edge, receiving ACP queries from buyer agents. Unlike traditional e-commerce, it doesn't blindly accept orders; it calculates margin in real-time and can negotiate prices.

Prerequisites: Make sure you've completed the Installation guide and have an initialized project.

The agent you'll build will be able to:

  • Check real-time inventory levels
  • Apply dynamic pricing based on stock and competition
  • Negotiate discounts within margin guardrails
  • Generate secure payment links via Stripe SPT

Create the Agent

Create a new file at agents/negotiator.py with the following code:

python
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
# agents/negotiator.py
from openai_agents import Agent, Runner, Tool
from hyperfold.tools import InventoryTool, PricingPolicyTool, StripePaymentTool
from hyperfold.context import get_session_context
 
# 1. Define Capability Tools
inventory_tool = InventoryTool(scope="read_only")
pricing_tool = PricingPolicyTool(strategy="dynamic_margin")
payment_tool = StripePaymentTool(capability="checkout_link")
 
# 2. Define Dynamic Logic (The Brain)
def negotiator_logic(step_input, context):
    """
    Core reasoning loop for price negotiation.
    """
    floor_price = context.get("floor_price")
    competitor_price = context.get("competitor_price")
 
    system_prompt = f"""
    You are a negotiator for an online store.
    Current Floor Price: ${floor_price}.
    Competitor Price: ${competitor_price}.
 
    Rules:
    1. If the user's offer is > Floor Price, ACCEPT.
    2. If the user's offer is < Floor Price, COUNTER with (Floor + 10%).
    3. If inventory is 'Overstock', be more aggressive (lower margin ok).
    """
    return system_prompt
 
# 3. Instantiate the Agent
negotiator = Agent(
    name="Hyperfold Negotiator V1",
    model="gpt-4o",
    tools=[inventory_tool, pricing_tool, payment_tool],
    instructions=negotiator_logic
)
 
# 4. Deployment Handler (Cloud Run Entrypoint)
def handle_acp_request(request):
    session_ctx = get_session_context(request.headers['session_id'])
    runner = Runner(agent=negotiator)
 
    response = runner.run(
        input=request.json['message'],
        context_variables=session_ctx
    )
 
    return response.to_acp_format()

Understanding the Code

1. Capability Tools

Tools define what actions the agent can take. InventoryTool checks stock levels, PricingPolicyTool retrieves margin rules, andStripePaymentTool generates checkout links.

2. Dynamic Logic

The negotiator_logic function generates system instructions based on real-time context. Floor prices and competitor data are injected at runtime from Firestore and Redis.

3. Agent Instantiation

The Agent class from OpenAI Agents SDK bundles the model, tools, and instructions together. The agent can reason about inputs and call tools as needed.

4. Request Handler

The handle_acp_request function is the Cloud Run entrypoint. It receives ACP-formatted requests, runs the agent, and returns ACP-compliant responses.

Deploy to Cloud

Deploy your agent to Hyperfold Cloud with a single command:

bash
1
2
3
4
5
6
7
8
$ hyperfold agent deploy ./agents/negotiator.py --name=sales-bot-01
> [Build] Containerizing... Uploading to Registry...
> [Cloud Run] Deploying revision sales-bot-01-v1...
> [SUCCESS] Service URL: https://sales-bot-01-xyz.agents.hyperfold.io
 
$ hyperfold agent list
ID              ROLE         STATUS   HITS (24h)  AVG_LATENCY
sales-bot-01    Negotiator   ACTIVE   0           --

The deploy command:

  1. Packages your Python code into a container
  2. Uploads it to Google Container Registry
  3. Deploys to Cloud Run with auto-scaling
  4. Registers the agent with Hyperfold's orchestration layer

Configure the Agent Prompt

You can hot-swap the agent's system instructions without redeploying:

bash
1
2
3
4
5
6
7
8
9
10
11
12
# Create a prompt file
cat > prompts/sales.txt << 'EOF'
You are a friendly but firm sales agent.
Always try to upsell when possible.
Never go below the floor price.
EOF
 
# Update the agent
hyperfold agent prompt set --agent="sales-bot-01" --file="./prompts/sales.txt"
 
> [Firestore] System Instruction updated.
> [Live Status] Agent behavior updated instantly. No redeploy required.

Test Your Agent

Use the simulation tool to test your agent with different buyer personas:

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
$ hyperfold sim chat --persona="frugal_shopper" --agent="sales-bot-01"
> [Sim] Spawning Persona: Frugal Shopper
> [Sim] Connecting to Agent: sales-bot-01...
 
[You]: I'm looking for running shoes under $100
 
[Agent]: I have the 'AeroRun X2' normally priced at $140.
         Given your budget, I can offer it at $115 today.
 
[You]: That's still over my budget. Can you do $95?
 
[Agent]: I understand you're looking for value. The best I can do
         is $105 - that's 25% off and includes free shipping.
 
[You]: Deal! I'll take it.
 
> [System] ACP Checkout Triggered.
> [System] Order #9910 Created in Spanner.
> [SUCCESS] Negotiation completed. Final price: $105.00

Available buyer personas for testing:

PersonaBehavior
frugal_shopperAlways seeks discounts, has strict budget limits
premium_buyerValues quality over price, open to upsells
bulk_purchaserBuys in quantity, expects volume discounts
comparison_shopperMentions competitor prices, needs convincing

View Chain of Thought Logs

See what your agent is "thinking" during negotiations:

bash
1
2
3
4
5
6
7
8
$ hyperfold agent logs sales-bot-01 --tail
 
[INFO] Request: Discount 15% on SKU_991.
[DATA] Inventory: High (Overstocked).
[DATA] Policy: Allow up to 20% disc on overstock.
[THOUGHT] Margin is healthy. I can offer 10% off if they buy now.
[ACTION] ACCEPT OFFER.
[OUT] ACP Response 200 OK.

Next Steps

Congratulations! You've deployed your first negotiator agent. Here's what to explore next:

Negotiator Deep Dive

Advanced pricing strategies and margin calculations

Import Products

Add your catalog with AI-powered tagging

Connect Shopify

Sync orders back to your existing store

Cookbook

Real-world recipes and advanced patterns