{"id":45157437,"url":"https://github.com/couchbase-examples/agent-catalog-quickstart","last_synced_at":"2026-02-20T05:02:46.870Z","repository":{"id":298404679,"uuid":"999864730","full_name":"couchbase-examples/agent-catalog-quickstart","owner":"couchbase-examples","description":"This repository provides a quickstart guide for using the Agent Catalog with Capella Model Services and Couchbase.","archived":false,"fork":false,"pushed_at":"2025-11-12T18:09:42.000Z","size":3859,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-12T18:26:09.337Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/couchbase-examples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-10T23:04:56.000Z","updated_at":"2025-11-12T18:09:46.000Z","dependencies_parsed_at":"2025-07-22T04:26:24.716Z","dependency_job_id":"3c917868-13f5-4a0d-bcf6-6449110838a6","html_url":"https://github.com/couchbase-examples/agent-catalog-quickstart","commit_stats":null,"previous_names":["couchbase-examples/agent-catalog-quickstart"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/couchbase-examples/agent-catalog-quickstart","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fagent-catalog-quickstart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fagent-catalog-quickstart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fagent-catalog-quickstart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fagent-catalog-quickstart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/couchbase-examples","download_url":"https://codeload.github.com/couchbase-examples/agent-catalog-quickstart/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fagent-catalog-quickstart/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29641929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T03:21:14.183Z","status":"ssl_error","status_checked_at":"2026-02-20T03:18:24.455Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-20T05:02:40.298Z","updated_at":"2026-02-20T05:02:46.864Z","avatar_url":"https://github.com/couchbase-examples.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Catalog Quickstart\n\nThis repository provides a quickstart guide for using the Agent Catalog with Capella Model Services and Couchbase.\n\n## Prerequisites\n\n- Python 3.12+\n- Poetry ([Installation Guide](https://python-poetry.org/docs/#installation))\n- Git (for repository management)\n- An OpenAI API Key (or other LLM provider)\n- Couchbase Capella account (or local Couchbase installation)\n\n## Quick Start\n\nTwo ways to get running fast. Choose one.\n\n### 1) Full repo setup (script)\n\n```bash\ngit clone --recursive https://github.com/couchbaselabs/agent-catalog-quickstart.git\ncd agent-catalog-quickstart\nbash scripts/setup.sh --yes               # add --skip-testing to speed up\n\n# pick an agent and configure env\ncd notebooks/hotel_search_agent_langchain\ncp .env.sample .env \u0026\u0026 $EDITOR .env\n\n# run\npoetry run python main.py\n```\n\n### 2) Per-agent setup (fastest)\n\n```bash\n# from repo root\npoetry -C notebooks/flight_search_agent_langraph install --no-root\ncp notebooks/flight_search_agent_langraph/.env.sample notebooks/flight_search_agent_langraph/.env\n$EDITOR notebooks/flight_search_agent_langraph/.env\npoetry -C notebooks/flight_search_agent_langraph run python main.py\n```\n\n### 3) Installation Methods \u0026 Package Management\n\n#### **Recommended: pipx for CLI (Isolated)**\n\nFor the cleanest installation that avoids system conflicts:\n\n```bash\n# Install pipx if not available\nbrew install pipx  # macOS\n# or: python3 -m pip install --user pipx\n\n# Use the proper pipx setup script\nbash scripts/setup_pipx.sh\n```\n\n**Benefits:**\n\n- Isolated environments prevent conflicts\n- Clean separation between CLI tools and project dependencies\n- Works with externally managed Python environments (Homebrew, system Python)\n\n#### **Alternative: Global pip installs (PyPI)**\n\n⚠️ **Note**: This method may conflict with externally managed environments. Use only if pipx fails.\n\n```bash\n# Install Agent Catalog packages (add --break-system-packages if needed)\npip3 install agentc agentc-core agentc-cli agentc-langchain agentc-langgraph agentc-llamaindex\n\n# Install Arize Phoenix and evaluation dependencies\npip3 install \"arize-phoenix[evals]\" arize arize-otel openinference-instrumentation-langchain openinference-instrumentation-openai openinference-instrumentation-llama-index\n\n# Fix OpenTelemetry version conflicts (if needed)\npip3 install --upgrade opentelemetry-instrumentation-asgi opentelemetry-instrumentation-fastapi opentelemetry-util-http\n```\n\nThen run the per-agent commands under \"2) Per-agent setup (fastest)\" above.\n\n#### **Development Note**\n\nThese packages are currently installed from source during development. Once agentc packages are available on PyPI, the installation will be simplified to standard pip/pipx commands.\n\n### Working with Git Submodules\n\nThis repository uses git submodules to manage the Agent Catalog dependency. If you encounter issues:\n\n```bash\n# If you cloned without --recursive, initialize submodules manually:\ngit submodule update --init --recursive\n\n# Update submodules to latest versions:\ngit submodule update --remote\n\n# Verify submodules are properly initialized:\ngit submodule status\n```\n\n**Note**: The `agent-catalog` directory is managed as a submodule and should not be manually edited.\n\n## Per-Agent Details\n\nEach example is independent and includes code, prompts, tools, and evals.\n\n### 🛩️ Flight Search Agent (`notebooks/flight_search_agent_langraph/`)\n\n- Framework: LangGraph\n- Install: `poetry -C notebooks/flight_search_agent_langraph install --no-root`\n- Run: `poetry -C notebooks/flight_search_agent_langraph run python main.py`\n\n### 🏨 Hotel Support Agent (`notebooks/hotel_search_agent_langchain/`)\n\n- Framework: LangChain\n- Install: `poetry -C notebooks/hotel_search_agent_langchain install --no-root`\n- Run: `poetry -C notebooks/hotel_search_agent_langchain run python main.py`\n\n### 🗺️ Landmark Search Agent (`notebooks/landmark_search_agent_llamaindex/`)\n\n- Framework: LlamaIndex\n- Install: `poetry -C notebooks/landmark_search_agent_llamaindex install --no-root`\n- Run: `poetry -C notebooks/landmark_search_agent_llamaindex run python main.py`\n\n## Environment Configuration\n\nEach agent needs its own `.env` file with your credentials:\n\n```bash\n# Copy the sample file and edit it\ncp .env.sample .env\n# Edit .env with your actual credentials\n```\n\n**Required files:**\n\n- `notebooks/flight_search_agent_langraph/.env`\n- `notebooks/hotel_search_agent_langchain/.env`\n- `notebooks/landmark_search_agent_llamaindex/.env`\n\nFor complete environment configuration examples (Capella vs Local), see **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md#environment-configuration-examples)**.\n\n## Usage\n\n```bash\n# run with a query\npoetry -C notebooks/hotel_search_agent_langchain run python main.py \"Find hotels in Paris with free breakfast\"\n\n# run evaluations (Arize)\npoetry -C notebooks/hotel_search_agent_langchain run python evals/eval_arize.py\n```\n\n### Using Global CLI (After Full Setup)\n\nIf you installed the global CLI:\n\n```bash\ncd notebooks/hotel_search_agent_langchain\n\n# Initialize Agent Catalog\nagentc init\n\n# Index your agent\nagentc index .\n\n# Publish your agent (requires clean git)\ngit add . \u0026\u0026 git commit -m \"Your changes\"\nagentc publish\n\n# Run the agent\npython main.py \"Find hotels in Paris with free breakfast\"\n```\n\n## Agent Catalog CLI Commands\n\n| Command          | Description                                          |\n| ---------------- | ---------------------------------------------------- |\n| `agentc init`    | Initialize agent catalog in current directory        |\n| `agentc index .` | Index the current agent directory                    |\n| `agentc publish` | Publish agent to catalog (requires clean git status) |\n| `agentc --help`  | Show all available commands                          |\n| `agentc env`     | Show environment configuration                       |\n\n## Troubleshooting\n\nHaving issues? Check our comprehensive troubleshooting guide: **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)**\n\n### Quick Fixes\n\n- \"No module named 'agentc'\": ensure you ran `poetry -C notebooks/\u003cagent\u003e install --no-root` and are executing with Poetry (`poetry run ...`).\n- Evaluation deps missing: run the agent-specific Poetry install again; eval deps are included per agent.\n- Poetry issues: delete the agent’s `poetry.lock` and run `poetry -C notebooks/\u003cagent\u003e install --no-root`.\n- Environment errors: copy `.env.sample` to `.env` in the agent folder and fill in credentials.\n- CLI not found after script: restart your shell or run `export PATH=\"$PATH:$HOME/.local/bin\"`; rerun `bash scripts/setup.sh --yes` if needed.\n- Submodule issues: run `git submodule update --init --recursive` to initialize the agent-catalog dependency.\n\nFor detailed solutions, environment configuration examples, and debugging commands, see **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)**.\n\n## Development\n\n### Adding New Agents\n\n1. Create a new directory under `notebooks/`\n2. Add your agent code, prompts, and tools\n3. Create appropriate configuration files (`pyproject.toml`, `.env`)\n4. Install Agent Catalog: `pip3 install agentc agentc-core agentc-cli agentc-langchain agentc-langgraph agentc-llamaindex`\n5. Install root dependencies: `poetry install`\n6. Run `poetry install --no-root` in the new directory\n7. Run `agentc init` and `agentc index .`\n\n### Evaluation\n\nRun evaluations with Arize:\n\n```bash\npoetry run python evals/eval_arize.py\n```\n\n## Repository Resources\n\n### 📚 Documentation (`docs/`)\n\nComprehensive guides and references for working with the Agent Catalog ecosystem:\n\n| Document | Purpose |\n|---|---|\n| **[PYPROJECT_GUIDE.md](docs/PYPROJECT_GUIDE.md)** | Complete guide to `pyproject.toml` configuration |\n| **[AGENTC_GUIDE.md](docs/AGENTC_GUIDE.md)** | Agent Catalog CLI and usage documentation |\n| **[PYTHON_LINUX.md](docs/PYTHON_LINUX.md)** | Linux Python setup and pip troubleshooting |\n| **[PYTHON_MAC.md](docs/PYTHON_MAC.md)** | macOS Python environment setup guide |\n| **[CAPELLA_MODELS.md](docs/CAPELLA_MODELS.md)** | Couchbase Capella model services integration |\n| **[EVALUATION_FRAMEWORKS_COMPARISON.md](docs/EVALUATION_FRAMEWORKS_COMPARISON.md)** | Comparison of AI evaluation frameworks |\n\n**Quick access:**\n```bash\n# View documentation\nls docs/                    # List all documentation files\ncat docs/PYPROJECT_GUIDE.md # Read specific guide\n```\n\n### 🛠️ Templates (`templates/`)\n\nReady-to-use templates for creating Agent Catalog components:\n\n| Template | Purpose | Usage |\n|---|---|---|\n| **`prompt_template.yaml`** | Agent prompt templates | Create new prompts with proper structure |\n| **`python_function_template.py`** | Python tool functions | Build custom tools and utilities |\n| **`semantic_search_template.yaml`** | Couchbase vector search | Set up semantic search functionality |\n| **`sqlpp_query_template.sqlpp`** | Database queries | Create SQL++ queries for Couchbase |\n| **`http_request_template.yaml`** | HTTP/API requests | Build HTTP request tools |\n| **`agentc_command_notes.txt`** | CLI command reference | AgentC command examples |\n\n**Using templates:**\n```bash\n# Copy template for new component\ncp templates/prompt_template.yaml prompts/my_new_prompt.yaml\ncp templates/python_function_template.py tools/my_new_tool.py\n\n# Edit with your specific requirements\n$EDITOR prompts/my_new_prompt.yaml\n```\n\n### 🔧 Shared Resources (`shared/`)\n\nCommon utilities and configurations used across all agents:\n\n| File | Purpose |\n|---|---|\n| **`agent_setup.py`** | Common agent initialization and setup utilities |\n| **`couchbase_client.py`** | Couchbase database connection and client management |\n| **`capella_model_services_langchain.py`** | LangChain integration with Capella model services |\n| **`capella_model_services_llamaindex.py`** | LlamaIndex integration with Capella model services |\n| **`__init__.py`** | Package initialization for shared utilities |\n\n**Using shared resources:**\n```python\n# Import shared utilities in your agent\nfrom shared.couchbase_client import get_couchbase_client\nfrom shared.agent_setup import initialize_agent\nfrom shared.capella_model_services_langchain import get_langchain_llm\n```\n\n### 📋 Scripts (`scripts/`)\n\nAutomation and setup scripts for the repository:\n\n| Script | Purpose |\n|---|---|\n| **`setup.sh`** | Full repository setup and installation |\n| **`setup_pipx.sh`** | Clean pipx-based installation (recommended) |\n| **`scope_copy.py`** | Utility for copying agent scopes |\n\n**Using scripts:**\n```bash\n# Run setup scripts\nbash scripts/setup.sh --yes           # Full setup\nbash scripts/setup_pipx.sh           # Clean pipx setup\npython scripts/scope_copy.py         # Utility script\n```\n\n## Architecture\n\nEach example agent follows this structure:\n\n```\nnotebooks/agent_name/\n├── main.py              # Main agent implementation\n├── pyproject.toml       # Poetry dependencies (requires poetry install)\n├── .env                 # Environment configuration\n├── prompts/             # Agent prompts and templates\n├── tools/               # Agent tools and functions\n├── data/                # Data loading and processing\n└── evals/               # Evaluation scripts\n```\n\n## Contributing\n\nThis is a quickstart repository. For contributing to the main Agent Catalog:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Ensure all poetry dependencies are installed\n5. Commit changes (required for publishing)\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Fagent-catalog-quickstart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcouchbase-examples%2Fagent-catalog-quickstart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Fagent-catalog-quickstart/lists"}