Step 0: Build a Conversational Entry Point for Your AI Agent

Overview

The article starts the Agent series with Step 0 , which delivers a single functional piece: a command‑line interface that can talk to an LLM through a Brain.chat() wrapper. It demonstrates how to organize the repository, externalize configuration, and verify basic multi‑turn dialogue.

Goals and Acceptance Criteria

Only the .env file needs to be edited to switch models or compatible endpoints (e.g., DeepSeek, Ollama).

After a conversation like “I am Xiao Ming → What is my name?”, the agent should answer “Xiao Ming”.

When the network fails or the API key is wrong, the terminal should show a readable error instead of a Python traceback.

The messages variable must always be a list[dict] containing role and content fields, leaving placeholders for future modules.

Project Structure

Initialize an empty directory and run git init. The final layout looks like:

mini-agent/
├── .env               # local secrets (do not commit)
├── .env.example       # template for users
├── .gitignore
├── requirements.txt
├── config.py           # loads environment variables
├── brain.py            # module 1: Brain wrapper
├── main.py             # CLI entry point
└── README.md           # optional usage notes

Branch/tag conventions: main always points to the latest runnable code, while tags article-00 … article-08 mark the incremental steps.

Brain Wrapper ( brain.py )

The Brain class receives a Settings dataclass (API key, model name, optional base URL, timeout). Its chat(messages) method injects a fixed system prompt, calls OpenAI.chat.completions.create with temperature=0.3 and max_tokens=1024, and converts any SDK exceptions ( RateLimitError, APIConnectionError, APIStatusError) into user‑friendly RuntimeError messages in Chinese. The method returns a ChatResult containing text, model, and optional usage token statistics.

CLI Entry ( main.py )

The run_cli() function loads settings, creates a Brain instance, and enters a while True loop:

Prompt the user ( input("You: ")).

Handle exit / quit / q or interrupt signals.

Append the user message to messages.

Call brain.chat(messages) and catch RuntimeError to print a readable error and roll back the last user entry.

Print the agent response and, if available, token usage ( prompt_tokens, completion_tokens, total_tokens).

Append the assistant reply to messages for the next turn.

The script ends when the user types an exit command.

Local Run Steps

Create a virtual environment and install openai>=1.40.0 and python-dotenv>=1.0.0 from requirements.txt.

Copy .env.example to .env and fill in OPENAI_API_KEY, OPENAI_MODEL, and optionally OPENAI_BASE_URL and OPENAI_TIMEOUT.

Run python main.py and try the three example rounds:

"You: 你好，介绍一下你能做什么" → Agent explains it is a pure dialogue assistant.

"You: 我叫小明，记住" → Agent confirms.

"You: 我叫什么名字？" → Agent replies "小明".

To test configuration switching, modify OPENAI_MODEL in .env, restart the script, and verify the new model connects.

Common Pitfalls

401 / invalid_api_key : Ensure .env is at the project root and the variable name is exactly OPENAI_API_KEY. Restart the script after changes.

Connection errors : Domestic connections to OpenAI often fail; switch to a compatible provider or use a proxy, and set the correct OPENAI_BASE_URL. For Ollama, confirm ollama serve is running and curl http://localhost:11434/v1/models returns data.

Empty model response : Some small models struggle with long system prompts; try a larger model or shorten the prompt. Also verify max_tokens is not set too low (default 1024 is usually sufficient).

Memory not retained across turns : The implementation keeps history only within the same process. Restarting python main.py clears messages by design.

Accidentally committing .env : Use git status to confirm it is ignored. If committed, rotate the key immediately and run git rm --cached .env.

Adding features too early : At Step 0, avoid introducing tools, LangChain, or FastAPI; they would blur module boundaries and complicate later orchestration steps.

Optional Streaming Output (Bonus)

For those who want to experiment with streaming, add a chat_stream method to Brain that yields incremental chunks and assembles the full text. The CLI would need to consume the generator and print each delta. Note that from Step 2 onward, when tool_call appears, the stream must be reassembled before processing JSON payloads.

Architecture Mapping

The article implements the "Brain" block of the overall Agent diagram, provides an in‑process short‑term memory via the messages list, and leaves placeholders for tools, orchestration loops, and engineering concerns (environment variables, error handling) to be filled in later modules.

Next Steps

Step 1 will introduce a ContextManager to handle token‑based sliding window truncation, expose token usage, and prepare slots for system, plan, and tool results. The repository will advance from tag article-00 to article-01 after committing the current changes.