agent-scaffolds 0.1.5

agent-scaffolds

Ascender Framework Project

Overview

This project is built using the Ascender Framework, a structured FastAPI-based framework designed for modular and scalable applications.

---

Ascender — AgentHub SDK

Small scaffolding project and tooling for building AgentHub agents on top of the Ascender framework. It includes a command-line copilot TUI, ATTP protocol SDK, MCP server provider helpers, and a scaffold template for creating agent manifests.

This README covers quick setup, development, how to run the copilot TUI, and notes about packaging the project as a library.

Prerequisites

• Python 3.11 (recommended)
• Poetry (for dependency and packaging)

Using a dedicated virtual environment for development is recommended:

python3.11 -m venv .venv
source .venv/bin/activate
poetry install

If you prefer Poetry's own virtualenv handling, run:

poetry config virtualenvs.create true
poetry install

Development / Running the app

• To run the web server (development):

# (example; your project may expose a different entrypoint)
poetry run ascender run serve

• To run the Copilot TUI:

poetry run ascender run copilot run            # reuse latest chat session
poetry run ascender run copilot run --subject "My Session"  # start named session

TUI commands inside the copilot:

• /new <name> — create and switch to a new chat
• /select <n> — switch to chat number n
• /refresh — reload chat list from the server
• /exit or /quit — quit the TUI

The copilot supports streaming responses; it will show token-by-token updates when the ATTP client provides a streaming response.

Install & use as a library

You can install the published package directly:

pip install agent-scaffolds
# or with poetry
poetry add agent-scaffolds

Wiring into an Ascender app (example)

In your bootstrap.py, provide the MCP server and copilot CLI so they register with your Ascender application:

from ascender.core.cli_engine import useCLI
from agenthub.cli.copilot import CopilotCLI
from agenthub.mcp.server import provideMCP

appBootstrap = {
   "providers": [
      # ... your other providers ...
      useCLI(CopilotCLI),
      provideMCP("agenthub"),  # mounts MCP at /agenthub
   ]
}

Then run your app (e.g. poetry run ascender run serve) and access the MCP endpoint at /agenthub.

Packaging as a library

This repository is a normal Python package layout under src/agenthub. If you want to publish the project as a reusable library (PyPI or private index):

1. Ensure pyproject.toml exposes the package by setting packages/include or by using Poetry's default packages = [{ include = "agenthub" }] with package-dir = { "" = "src" } if needed.
2. Build and publish with Poetry:

poetry build
poetry publish --build

After publishing you can install it via pip or poetry add in other projects.

Quick local install for testing

pip install -e src
# or with poetry in another project
poetry add ../path/to/agent-scaffolds

Environment variables

The AgentHub config loader reads these variables (with the shown defaults):

• AGENTHUB__BASE_URL (default http://localhost:8000)
• AGENTHUB__ATTP_URL (default attp://localhost:6563)
• AGENTHUB__AGT_KEY (default demo token)
• AGENTHUB__ORGANIZATION_ID (default 1)

Set them in your shell or .env before running the server or copilot, e.g.:

export AGENTHUB__BASE_URL="https://your-agenthub"
export AGENTHUB__ATTP_URL="attp://your-attp-host:6563"
export AGENTHUB__AGT_KEY="your_agent_token"
export AGENTHUB__ORGANIZATION_ID=123

Notes about using this project as a library

Pros:

• Encapsulates Copilot UI, tools, and MCP wiring so other apps can reuse them.
• Packaged code is easy to install and import (e.g. import agenthub).

Potential drawbacks / gotchas:

• Side-effects on import: some modules register providers or mount ASGI apps (e.g. lifecycle hooks). Avoid importing top-level modules that perform runtime startup actions; prefer importing explicit factory functions.
• Event loop / ASGI lifecycle: the MCP provider starts a task group on application startup. When used inside another ASGI app you must ensure the host application calls the startup/shutdown handlers (FastAPI/Starlette do this automatically) so the MCP run context can initialize.
• Dependency conflicts: publishing a library exposes its declared dependencies to downstream projects. Keep dependency ranges conservative and document any optional extras.
• CLI vs library split: the package contains CLI entrypoints that assume a full Ascender application. If consumers only want a library API, provide a small public surface (agenthub.sdk, agenthub.tools) and keep CLI wiring isolated.

Recommendations:

• Avoid side-effectful code at import time. Provide explicit init/provide functions (factories) that host apps call during startup.
• Document required runtime steps (e.g. call provideMCP(...) from your Ascender bootstrap or mount the MCP app at /agenthub).
• Use extras in pyproject.toml for optional features (e.g. [tool.poetry.extras]) to separate heavy optional dependencies like certain ATTP client versions.

Contributing

Contributions welcome. Please open PRs against the main branch. Include tests and update the changelog/README for non-trivial changes.

License

This project is licensed under the MIT License. See the LICENSE file for details.