Skip to content

Conversation

@wamimi
Copy link
Contributor

@wamimi wamimi commented Oct 31, 2025

What changed? Why?

This PR improves the Getting started with Chat Agents guide by restructuring it with a clear, logical flow that prevents confusion.

The Problem

The current documentation jumps between concepts without a clear workflow:

  • Shows "Installation" but doesn’t explain where to install
  • Shows "Usage" code but doesn’t explain where to put it
  • Tells users to create .env manually but doesn’t explain how to get the values (XMTP_WALLET_KEY, XMTP_DB_ENCRYPTION_KEY)
  • Missing the critical import dotenv/config, which causes XMTP_WALLET_KEY format errors

The Solution

Restructured the guide with a clear 6-step workflow:

  1. Clone the XMTP agent examples repository — Gives users a workspace and installs all dependencies
  2. Generate keys with npm run gen:keys — Automatically creates .env with all required values
  3. Create index.ts file — Clear instruction on where to put the code
  4. Add agent code — Includes the critical import dotenv/config line
  5. Run the agent — Use npx tsx --watch index.ts
  6. Test on xmtp.chat — Step-by-step testing instructions

Notes to reviewers

The new flow follows the natural developer journey:
setup workspace → generate credentials → write code → run → test.
This eliminates the confusion of “where do I put this?” and “how do I get these values?” that plagued the previous version.


How has it been tested?

Spun up documentation locally with mint dev
Tested locally and amde sure the agents runs and responds with Hello from my Base App Agent! 👋

- Add step-by-step workflow starting with cloning xmtp-agent-examples repo
- Add key generation step with npm run gen:keys
- Add critical import dotenv/config to prevent XMTP_WALLET_KEY errors
- Add clear instructions for creating index.ts file in project root
- Add step for running agent with npx tsx --watch index.ts
- Add detailed testing instructions for xmtp.chat
- Remove confusing manual env setup that didn't explain where to get values
@cb-heimdall
Copy link
Collaborator

🟡 Heimdall Review Status

Requirement Status More Info
Reviews 🟡 0/1
Denominator calculation
Show calculation
1 if user is bot 0
1 if user is external 0
2 if repo is sensitive 0
From .codeflow.yml 1
Additional review requirements
Show calculation
Max 0
0
From CODEOWNERS 0
Global minimum 0
Max 1
1
1 if commit is unverified 0
Sum 1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants