93 lines
2.4 KiB
Markdown
93 lines
2.4 KiB
Markdown
# TJWaterAgentExperimental
|
|
|
|
Experimental opencode-based Agent service for TJWater UI orchestration.
|
|
|
|
This repository is intentionally separate from the production `TJWaterAgent`
|
|
history. It does not include user authentication or the old `tjwater-cli`
|
|
bridge. Runtime requests use a local default context and can later be wired to a
|
|
real auth provider through `src/context/`.
|
|
|
|
## Current Boundaries
|
|
|
|
- No Keycloak / metadata auth context.
|
|
- No required `Authorization` or `X-Project-Id` headers.
|
|
- No `cli/`, no `tjwater_cli` opencode tool, no free-form CLI command bridge.
|
|
- Agent visual output is expressed through `agent-ui@1` UIEnvelope events.
|
|
- Backend data tools are not fully reintroduced yet; missing business data must
|
|
be reported honestly by the Agent.
|
|
|
|
## Main API
|
|
|
|
```text
|
|
GET /health
|
|
GET /api/v1/agent/chat/models
|
|
GET /api/v1/agent/chat/ui-registry
|
|
POST /api/v1/agent/chat/session
|
|
GET /api/v1/agent/chat/sessions
|
|
GET /api/v1/agent/chat/session/:session_id
|
|
GET /api/v1/agent/chat/session/:session_id/stream
|
|
POST /api/v1/agent/chat/stream
|
|
POST /api/v1/agent/chat/abort
|
|
```
|
|
|
|
`POST /api/v1/agent/chat/stream` returns SSE. Important events:
|
|
|
|
| event | Purpose |
|
|
| --- | --- |
|
|
| `progress` | Agent planning/tool progress |
|
|
| `token` | Assistant text delta |
|
|
| `ui_envelope` | Structured UI description for trusted frontend rendering |
|
|
| `tool_call` | Deprecated compatibility/debug event |
|
|
| `permission_request` | Runtime permission request |
|
|
| `question_request` | Runtime/user clarification request |
|
|
| `done` | Run completed |
|
|
| `error` | Run failed or aborted |
|
|
|
|
## Local Context
|
|
|
|
The service uses `src/context/localContext.ts`.
|
|
|
|
Defaults:
|
|
|
|
```text
|
|
AGENT_LOCAL_USER_ID=local-user
|
|
AGENT_LOCAL_PROJECT_ID=local-project
|
|
AGENT_LOCAL_NETWORK=local-network
|
|
```
|
|
|
|
Optional request headers can override the local context during experiments:
|
|
|
|
```text
|
|
X-Agent-Local-User
|
|
X-Agent-Local-Project
|
|
X-Agent-Local-Network
|
|
X-Trace-Id
|
|
```
|
|
|
|
## UIEnvelope
|
|
|
|
The registry is exposed at:
|
|
|
|
```text
|
|
GET /api/v1/agent/chat/ui-registry
|
|
```
|
|
|
|
Visual opencode tools are mapped by the service:
|
|
|
|
- `show_chart` -> `chart`
|
|
- `locate_features`, `zoom_to_map`, `render_junctions`, `apply_layer_style` -> `map_action`
|
|
- `view_history`, `view_scada` -> `registered_component`
|
|
|
|
See [docs/agent-ui-protocol.md](docs/agent-ui-protocol.md).
|
|
|
|
## Development
|
|
|
|
```bash
|
|
bun install
|
|
bun run dev
|
|
bun run check
|
|
bun test tests/**/*.test.ts
|
|
```
|
|
|
|
`bun run check` typechecks the service and `.opencode` tools.
|