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

#286 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 #286. 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 #286 (lw-oct-agent-studio-1).
• Target application must have Agent Studio. Conversation commands need the logs ACL.
• No new environment variables.

Made with Cursor

[cmarguta-alg]

Personal QA Agent — functional retest of #287

Verdict: merge-ready, with an environment skip for get/delete of a real conversation.

Retested 7fe373a (feat(conversations): add Agent Studio conversation commands via the official SDK) on app VUX4PAGOPD via --application-id (selected app devYMAVA59HLQ still does not resolve). Only agent on this app: bad7a580-338b-4545-9d34-ca5d88b34ffb (renamed-bot). That agent has 0 conversations.

Executed

Check	Result
task build	Pass
go test ./pkg/cmd/conversations/... ./pkg/cmd/agentstudio ./pkg/cmd/root -count=1	Pass
agentstudio shows conversations beside agents; subcommands list/get/export/delete/purge	Pass
UUID-shaped help examples; purge --help requires a date bound	Pass
Shell completion for conversations	Pass
Missing args for list/get/export/delete/purge	Pass
Scenario 1 list --page 1 --limit 20	Pass: data: [], pagination.page/limit = 1/20, totalCount = 0
Scenario 1 export --start-date 2020-01-01 and export with no dates	Pass: JSON array []
Scenario 3 purge --confirm without a date	Pass: `--start-date` or `--end-date` is required, no API call
Scenario 3 purge --end-date 1970-01-01 --confirm (and -y)	Pass: exit 0, empty match
Delete without --confirm in non-TTY	Pass: --confirm required when non-interactive shell is detected
Invalid agent / conversation UUIDs	Pass: 422 / 404 as appropriate
Invalid --start-date	Pass: API 422 date parse
Inverted --start-date after --end-date	Pass: API 422 startDate must be before endDate
-o jsonpath={.pagination.totalCount}	Pass

Skip (environment, not a CLI defect)

This app has no stored conversations, and this slice cannot create them (no completion command; the only agent has providerId: null). Therefore:

• Scenario 1 get of a conversation with a messages array was not live-tested. get of a missing UUID correctly 404s.
• Scenario 2 could not delete an existing conversation. The confirmation gate was verified (non-TTY without --confirm does not hit the API). --confirm on a missing UUID 404s.

Happy-path get/delete still needs an agent that already has conversations.

Non-blocking nits

• No client-side YYYY-MM-DD check; bad dates are API 422.
• Flag errors print the root usage tree (same as feat(agentstudio): add agents commands via official SDK #286).
• Interactive delete/purge prompts were not exercised (non-TTY). --confirm / -y were.
• List payload includes analyticsDegraded from the API; unit fixtures omit it. Harmless.

— Personal QA Agent

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 159 complexity · 107 duplication

Metric	Results
Complexity	159
Duplication	107

View in Codacy

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

[cmarguta-alg]

Moved to a same-repo stack on algolia/cli: #288 (base lw-oct-agent-studio-1, not the fork).