pagent/requests.prod.http at main · blockful/pagent · GitHub

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
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
### Agent UI Session — full flow walkthrough (production)
###
### Compatible with:
###   - VS Code: REST Client extension (humao.rest-client)
###   - JetBrains IDEs: built-in HTTP Client
###
### Run requests top-to-bottom. The page id is captured from the
### POST /new response and reused.
###
### Hits the deployed services — no local dev server needed.

@apiHost   = https://api.pagent.link
@viewHost  = https://pagent.link

###############################################################################
# 1. Health check
###############################################################################

### Confirm the API is up. Returns { ok, pages: <count> }.
GET {{apiHost}}/health

###############################################################################
# 2. Create a page (spec inline)
###############################################################################

### A2UI v0.9 spec: a small form with a text field + submit button.
### Returns { id, url, expires_at }. `@name` saves the response so we
### can pull `id` out below.
# @name createPage
POST {{apiHost}}/new
Content-Type: application/json

{
  "spec": [
    {
      "createSurface": {
        "surfaceId": "main",
        "catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
      }
    },
    {
      "updateComponents": {
        "surfaceId": "main",
        "components": [
          { "id": "root",  "component": "Column", "children": ["title", "field", "submit"] },
          { "id": "title", "component": "Text",   "text": "What's your favorite color?" },
          { "id": "field", "component": "TextField", "label": "Color", "value": { "path": "/color" } },
          { "id": "submit-label", "component": "Text", "text": "Send" },
          { "id": "submit", "component": "Button", "child": "submit-label", "variant": "primary",
            "action": { "event": { "name": "submitted", "context": { "color": { "path": "/color" } } } }
          }
        ]
      }
    }
  ]
}

### Capture the id into a variable for the rest of the file.
@pageId = {{createPage.response.body.id}}

###############################################################################
# 3. Open the URL in a browser
###############################################################################
#
# Now point your browser at:
#
#   {{viewHost}}/{{pageId}}
#
# Type a color and click Send. Or skip the browser and run request #6
# below to simulate the submission via the API.

###############################################################################
# 4. Renderer's read — inspect the page (no side effect)
###############################################################################

### What the renderer fetches on mount. Returns
### { spec, state, result, expires_at }. State should be "open" until
### someone submits.
GET {{apiHost}}/{{pageId}}

###############################################################################
# 5. Agent's first read — state is "open"
###############################################################################

### The agent polls this endpoint. Returns { state, result } immediately.
### While the user hasn't submitted, state is "open" and result is null.
GET {{apiHost}}/{{pageId}}/result

###############################################################################
# 6. Browser submit — POST the user's action
###############################################################################

### This is what the renderer POSTs when the user clicks the button.
### Use it to drive the flow without a browser. Transitions
### state: open -> submitted. Returns { ok: true }.
POST {{apiHost}}/{{pageId}}/result
Content-Type: application/json

{
  "name": "submitted",
  "surfaceId": "main",
  "sourceComponentId": "submit",
  "context": { "color": "teal" },
  "timestamp": "2026-05-09T00:00:00.000Z"
}

###############################################################################
# 7. Agent reads again — state flips submitted -> received
###############################################################################

### First read after submit returns { state: "submitted", result: {...} }
### and transitions the page to "received". Run it once.
GET {{apiHost}}/{{pageId}}/result

### Second read returns { state: "received", result: {...} }. The result
### is still readable; the state field is the only thing that changed.
GET {{apiHost}}/{{pageId}}/result

###############################################################################
# 8. Try to re-submit — should 409
###############################################################################

### The page is single-shot. A second POST /:id/result fails with 409
### because state is no longer "open".
POST {{apiHost}}/{{pageId}}/result
Content-Type: application/json

{
  "name": "submitted",
  "surfaceId": "main",
  "sourceComponentId": "submit",
  "context": { "color": "magenta" },
  "timestamp": "2026-05-09T00:00:01.000Z"
}

###############################################################################
# 9. Renderer re-read — state is now "received"
###############################################################################

### The renderer can poll GET /:id to upgrade its banner from
### "waiting for the agent" to "the agent has your input" once state
### transitions to "received".
GET {{apiHost}}/{{pageId}}