feat(agentstudio): add conversations commands via official SDK

[cmarguta-alg]

🤔 What

Adds algolia agentstudio conversations so you can list, get, export, delete, and purge Agent Studio conversations through the official Go SDK.

🤷 Why

#289 shipped the Agents resource. Conversations is the next sibling module under agentstudio (not nested under agents), using the same SDK client.

🔍 How

Section Group	Change
Commands	Register algolia agentstudio conversations with list/get/export/delete/purge calling the matching SDK methods.
Safety	delete and purge require --confirm off TTY. purge also requires --start-date and/or --end-date so the delete is bounded.

list/get/export print JSON. Dates are YYYY-MM-DD. IDs in examples are UUID-shaped. No file reads or writes.

🧪 Testing

Stacked on #289. Merge that first, or check out this branch which includes it.

Reads and deletes need an API key with logs (admin keys skip the CLI ACL check). Replace <APP_ID> and <agent-id> with an Agent Studio app that already has conversations. Agent and conversation IDs are UUIDs. Pass --application-id if the selected profile app does not resolve.

Quick checks

task build
go test ./pkg/cmd/conversations/... ./pkg/cmd/agentstudio ./pkg/cmd/root -count=1
./algolia agentstudio conversations --help
./algolia agentstudio conversations list --help
./algolia agentstudio conversations purge --help

Expect tests green, conversations beside agents under agentstudio, and subcommands list, get, export, delete, purge. purge --help states a date bound is required.

Scenario 1 — list, get, export

Action: list conversations, get one, export a date range.

./algolia agentstudio conversations list <agent-id> --application-id <APP_ID> --page 1 --limit 20
./algolia agentstudio conversations get <agent-id> <conversation-id> --application-id <APP_ID>
./algolia agentstudio conversations export <agent-id> --application-id <APP_ID> --start-date 2020-01-01

Expectation: list returns data[] and pagination. get returns that conversation with a messages array. export prints a JSON array of full conversations.

Scenario 2 — delete confirmation (failure mode)

Action: delete without --confirm in a non-TTY, then with --confirm.

./algolia agentstudio conversations delete <agent-id> <conversation-id> --application-id <APP_ID>
./algolia agentstudio conversations delete <agent-id> <conversation-id> --application-id <APP_ID> --confirm
./algolia agentstudio conversations get <agent-id> <conversation-id> --application-id <APP_ID>

Expectation: the first command errors with --confirm required when non-interactive shell is detected and the conversation still exists. The second exits 0. get then fails because the conversation is gone.

Scenario 3 — purge requires a date bound (failure mode)

Action: purge without a date, then with --end-date and --confirm.

./algolia agentstudio conversations purge <agent-id> --application-id <APP_ID> --confirm
./algolia agentstudio conversations purge <agent-id> --application-id <APP_ID> --end-date 1970-01-01 --confirm

Expectation: the first command errors with `--start-date` or `--end-date` is required and does not call the API. The second exits 0 (may delete nothing if no conversations match).

⚠️ Dependencies

• Stacked on #289 (lw-oct-agent-studio-1).
• Target application must have Agent Studio. Conversation commands need the logs ACL.
• No new environment variables.

Made with Cursor

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 58 complexity · 37 duplication

Metric	Results
Complexity	58
Duplication	37

View in Codacy

_{TIP This summary will be updated as you push new changes.}

[cmarguta-alg]

Status: 🟢 pass · 🔴 fail · 🟡 inconclusive (unable to test full functionality due to missing required data)

Personal QA Agent — retest of #288 with a real conversation

Verdict: merge-ready. Previously 🟡 Scenario 1/2 (no conversations, no provider) are now 🟢.

Retested the conversations command surface (from the stacked lw-oct-agent-studio-3 tree) on app VUX4PAGOPD. Seeded data by publishing agent d40699ad-… with provider 80e4966a-… (Anthropic) and sending one completion via the SDK (CreateAgentCompletion — not a CLI command in this slice). The provider was not deleted.

Results

Check	Status	Notes
task build / unit tests (prior run)	🟢	Unchanged
Command tree / UUID help / completion / missing args	🟢	Prior run
Scenario 1 list --page 1 --limit 20	🟢	data.length = 1, pagination 1/20, totalCount 1. Conversation id alg_cnv_miss_… (not a UUID)
Scenario 1 get	🟢	Same id; messages length 2 (user, assistant)
Scenario 1 export --start-date 2020-01-01 and export with no dates	🟢	JSON array of 1 full conversation including messages
Scenario 2 delete without --confirm in non-TTY	🟢	Confirm required; get still succeeded
Scenario 2 delete --confirm, then get	🟢	Exit 0; subsequent get 404; list then empty
Scenario 3 purge --confirm with no date	🟢	Prior run: date bound required, no API call
Purge --end-date 1970-01-01 --confirm	🟢	Prior run: bounded no-op
Interactive delete/purge prompts	🟡	Non-TTY; --confirm / -y tested

The seeded conversation was deleted as part of Scenario 2. The QA agent was deleted afterward. Provider left in place.

Non-blocking nits

• Live conversation IDs are alg_cnv_…, not UUID-shaped like the help examples. Commands accept them.
• No client-side YYYY-MM-DD check; bad dates are API 422.
• Flag errors print the root usage tree.
• List payload includes analyticsDegraded; unit fixtures omit it.

— Personal QA Agent