agent-scaffolds 0.1.1

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 — agent-scaffolds

Small scaffolding project and tooling for building AgentHub agents on top of the Ascender framework. It includes a command-line copilot TUI, 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

Include your chosen license here (e.g. MIT). If you don't want to add one yet, consider adding an explicit UNLICENSED or MIT file so consumers know how the code may be used.

---

If you'd like, I can also:

• Add a minimal __init__.py under src/agenthub and export the public API,
• Update pyproject.toml to declare the package layout and optional extras,
• Add a tiny setup/packaging guide or Makefile for common dev tasks. Tell me which you'd prefer next.