add-example-agent

# Add Example Agent ## Overview Examples under [examples/](../../../examples/) are the fastest way users learn Bindu. Each is a self-contained mini-project demonstrating one integration pattern. Follow existing structure — users and agents discover examples by convention, so inconsistency hurts discoverability. ## Inputs - `<name>`: kebab-case slug, e.g. `pdf-research-agent`, `weather-research`. - `<framework>`: Python (agno, langchain, langgraph, crewai) or TypeScript (openai, langchain). - `<purpose>`: one-sentence "what this demonstrates". ## Safety - Never commit `.env` files. Only `.env.example` with placeholder values and `# pragma: allowlist secret` to bypass pre-commit. - Never hardcode API keys, even in comments. - Never introduce paid-only services without a free-tier alternative. Examples must be runnable by a new user within minutes. - Never hardcode ports — default to `3773` with `BINDU_PORT` override. ## Execution Contract 1. Pick a matching template from existing examples. 2. Create the directory with the required file set. 3. Wire the handler to `bindufy()` with consistent config. 4. Write a README following the four-section pattern below. 5. Update parent indexes. 6. Test end-to-end in a clean environment before committing. ## Steps ### 1. Pick a template Find an existing example in the same framework and match its layout: - Python — simple: [examples/beginner/](../../../examples/beginner/) - Python — multi-agent: [examples/agent_swarm/](../../../examples/agent_swarm/) - Python — agno: [examples/medical_agent/](../../../examples/medical_agent/) - Python — langgraph: [examples/langgraph_blog_writing_agent/](../../../examples/langgraph_blog_writing_agent/) - TypeScript — openai: [examples/typescript-openai-agent/](../../../examples/typescript-openai-agent/) - TypeScript — langchain: [examples/typescript-langchain-agent/](../../../examples/typescript-langchain-agent/) ### 2. Create the directory ``` examples/<name>/ ├── README.md ├── .env.example ├── main.py # or index.ts for TypeScript ├── pyproject.toml # or package.json └── skills/ # optional, only if agent advertises skills └── <skill>/ └── skill.yaml ``` ### 3. Wire the handler Python handler signature: ```python def handler(messages: list[dict[str, str]]) -> str | dict: ... ``` TypeScript handler signature: ```typescript async (messages: ChatMessage[]) => Promise<string | HandlerResponse> ``` Call `bindufy(config, handler)` at the bottom of the entry file. Follow the config shape from the template example — don't invent new keys. ### 4. Write README.md Four sections, in this order: - **What it does** — one or two sentences. - **Prerequisites** — API keys, external services. Link docs for each. - **Setup** — `cp .env.example .env`, fill-in list, install command. - **Run** — `uv run python main.py` or `npx tsx index.ts`, plus one example curl against `localhost:3773`. ### 5. Update parent indexes - Add a row to [examples/README.md](../../../examples/README.md). - If this is a new framework, add it to the main [README.md](../../../README.md) framework table. ### 6. Test in a clean environment ```bash # Python cd examples/<name> uv venv --python 3.12.9 source .venv/bin/activate uv pip install -e . python main.py & sleep 3 curl -X POST http://localhost:3773/ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","method":"message/send","id":"test","params":{"message":{"role":"user","kind":"message","parts":[{"kind":"text","text":"Hello"}],"messageId":"1","contextId":"1","taskId":"1"}}}' ``` If response arrives and the DID signature is present in `metadata`, the example is good. ### 7. Commit One commit covering the whole example. Conventional commit: ``` feat(examples): add <name> — <one-line purpose> ``` ## Never do - **Never copy-paste secrets** from another example's `.env.example`. Each example lists its own required vars. - **Never skip the README** — an example without a README is invisible. - **Never introduce a new pattern** (auth flow, storage backend, deployment target) without matching docs in [docs/](../../../docs/). Examples showcase existing patterns, not unreleased ones.