assistant-template

Template project for building new assistants on top of assistant_core.

What This Template Includes

• A SingleAgent graph built with BuilderContext.create(...).
• A basic AgentNode with a simple system prompt.
• DateTimeBuilder wiring so each run has current date/time context.
• A runnable CLI entrypoint with an auto-generated thread_id per execution.
• A project architecture reference in ARCHITECTURE.md.

Project Structure

assistant-template/
	assistant_template/
		__init__.py
		agent.py
		main.py
	.env.example
	ARCHITECTURE.md
	pyproject.toml
	README.md

Quickstart

1. Install dependencies:

poetry install

2. Configure environment:

cp .env.example .env
# edit .env and set OPENAI_API_KEY

3. Run the template assistant in interactive mode:

poetry run assistant-template

You can now chat with the assistant directly from the CLI. Use /exit or /quit to end the session.

4. Optional one-shot usage:

poetry run assistant-template --message "What time is it now?"

The CLI generates a random thread_id automatically for each execution and reuses it for that run.

Using As A Dependency

You can consume this template, or a project derived from it, directly from GitHub without publishing to PyPI.

Poetry

[tool.poetry.dependencies]
my-assistant = { git = "https://github.com/your-org/your-repo.git", tag = "v0.1.0" }

pip

pip install "git+https://github.com/your-org/your-repo.git@v0.1.0"

The packaged distribution includes only the runtime package under assistant_template/ plus standard package metadata.

Development Commands

Use Makefile commands similar to assistant and assistant_core:

make format
make lint

These run black, isort, and flake8 with project settings.

Optional Configuration

LangSmith Tracing (Optional)

To enable observability and debugging with LangSmith, update your .env file:

LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
LANGSMITH_API_KEY=your_actual_api_key_here
LANGSMITH_PROJECT=your_project_name_here

LangSmith tracing is disabled by default. Set LANGSMITH_TRACING=true only if you have a LangSmith account and want to see traces in your dashboard.

Dependency Locking Policy

This template commits poetry.lock.

• Why: reproducible installs, stable CI, and a consistent starting point for new projects.
• When to update: only when intentionally changing dependencies (for example, bumping assistant_core tag or adding/removing packages).
• For derived projects: keep the lock file for reproducibility, or regenerate it intentionally if your project needs a different dependency baseline.

Build API

Use build_assistant_graph(openai_api_key, checkpointer=None, store=None, agent_factory=None) from assistant_template.agent to obtain a compiled LangGraph app:

from assistant_template.agent import build_assistant_graph

# Use defaults (MemorySaver and InMemoryStore)
graph = build_assistant_graph("your-openai-api-key")

Custom Checkpointer and Store

Provide custom implementations for persistent storage:

from langgraph.checkpoint.postgres import PostgresCheckpointer
from langgraph.store.postgres import PostgresStore

checkpointer = PostgresCheckpointer(conn_string="...")
store = PostgresStore(conn_string="...")

graph = build_assistant_graph(
    "your-openai-api-key",
    checkpointer=checkpointer,
    store=store,
)

Parameters:

• openai_api_key (str): Required. OpenAI API key for the model.
• checkpointer (optional): Custom checkpointer for conversation state persistence. Defaults to MemorySaver (in-memory).
• store (optional): Custom store for long-term data persistence. Defaults to InMemoryStore (in-memory).
• agent_factory (optional): Custom agent factory callable used to create the AgentNode. Defaults to the template's internal factory.

Extending This Template

• Add custom builders and register them on SingleAgent in assistant_template/agent.py.
• Group related tools in builder classes by domain.
• Keep builder logic in build(context) and avoid runtime state in builders.