aws / aws/agentcore-cli

Add a local Developer Web UI (`agentcore web`)

Open
#2,061 7 comments 6 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
283
Forks
95
Avg merge
1d 2h
Merged PRs (30d)
183

Description

## Summary

Add a local, browser-based **Developer Web UI** to the AgentCore CLI — a visual counterpart to `agentcore dev`, similar in spirit to the [Google ADK `adk web`](https://google.github.io/adk-docs/get-started/quickstart/) developer UI. It would let developers chat with any agent in their project, hold multiple persistent sessions, and watch tool calls, sub-agent delegation, reasoning, token usage and cost stream live in the browser — no deployment required.

Today the fastest way to exercise an agent locally is the terminal (`agentcore dev` / `agentcore invoke`). That's great for quick checks, but it's hard to inspect *how* a multi-tool, multi-agent run actually behaved: which tools were called, in what order, with what inputs/outputs, which ones failed, and what it cost. A browser UI makes that inspectable at a glance.

## Motivation

- **Faster local iteration** — pick an agent, chat, and re-run without wiring up scripts.
- **Observability while developing** — see the live tool log and a per-response trace instead of scrolling raw stdout.
- **Debuggability** — failed tool calls (timeouts, bad SQL, missing columns) are visible with their exact input/output.
- **Cost/perf awareness** — latency, in/out tokens, cycles, tool-call count, model id and estimated cost per response.
- **Parity with other agent frameworks** — developers coming from Google ADK expect a `web` dev surface.

## Proposed capabilities

A new `agentcore web` command launches a FastAPI + SSE server on `localhost` (default port 8502) and opens the browser. Reuses the same local credential resolution as `agentcore dev`.

**Three-pane workspace:**

![Web UI overview](https://raw.githubusercontent.com/fxerkan/agentcore-cli/feat/web-command/docs/screenshots/agentcore-webui.png)

- **Left — Agents & Sessions:** agent picker, plus create/switch/delete of independent chat sessions (each keeps its own history), and a "Clear Agent Cache" action to reload agent code from disk after local edits.
- **Center — Chat & live log:** the conversation, with a live tool-call log that expands while a response streams and a "Copy logs" action for bug reports.
- **Right — Trace & Metrics:** per-response latency, cost, in/out tokens, cycles, tool-call count, model id, and an expandable ordered tool trace.

**Agent selection** — every agent in the project (including sub-agents) is selectable:

![Agent selection](https://raw.githubusercontent.com/fxerkan/agentcore-cli/feat/web-command/docs/screenshots/agentcore-webui-agent-selection.png)

**Live tool logs** — each call shows a status icon (success / warning / error) and elapsed time, so failures are obvious mid-run:

![Live tool logs](https://raw.githubusercontent.com/fxerkan/agentcore-cli/feat/web-command/docs/screenshots/agentcore-webui-call_logs.png)

**Trace inspection** — expand any tool call to see its JSON input/output; SQL-backed tools render the exact SQL that ran:

| Input & output | SQL executed |
| --- | --- |
| ![Trace input/output](https://raw.githubusercontent.com/fxerkan/agentcore-cli/feat/web-command/docs/screenshots/agentcore-webui-traces.png) | ![SQL trace](https://raw.githubusercontent.com/fxerkan/agentcore-cli/feat/web-command/docs/screenshots/agentcore-webui-traces-sql.png) |

## Scope / non-goals

- Local development aid only — binds to `localhost`, deploys nothing, and changes no AWS resources beyond invoking the developer's own agents.
- Not a production or hosted dashboard.

## Acceptance criteria

- [ ] `agentcore web [--port ]` starts the UI, auto-selecting a free port if the default is busy, and opens the browser.
- [ ] Agents (and sub-agents) in the project are discoverable and selectable.
- [ ] Multiple persistent sessions per agent (create / switch / delete).
- [ ] Live streaming of text, tool calls, and reasoning via SSE.
- [ ] Per-response trace + metrics (latency, tokens, cycles, tool calls, cost, model).
- [ ] Graceful error surfaces when `uvicorn` is missing.
- [ ] Docs page describing the feature with screenshots.

Happy to contribute the implementation (a working prototype exists on a branch).

Contributor guide

Open the contributing guide

Research direction

Start by reading the existing `agentcore dev` and `agentcore invoke` command entry points, then review the working prototype mentioned in the issue. Map the proposed `agentcore web` command, FastAPI/SSE server, browser workspace, session handling, and agent discovery against the acceptance criteria. Done means the command launches locally and the listed UI, streaming, metrics, error handling, and documentation behaviors are covered.

Written by the indexing model from the issue text.

Assessment

Tech stack
fastapi, typescript
Domain
backend, cli, documentation, frontend, observability
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.