Pi Agent: First Chat
Last updated: 2026-08-31
Hello World is always the first step with a new tool. This lesson makes Pi Agent actually "speak."
1. CLI Quick Chat
The simplest way after installation is command-line chat:
BASH
pi-agent chat "Hello, please introduce yourself"
Output:
TEXT
📖 Display only
Pi Agent v0.8.0
Provider: deepseek (deepseek-chat)
Hello! I'm Pi Agent, a lightweight AI agent framework. I can help you
answer questions, call tools, and execute tasks. Chatting with me is
like talking to an AI partner that can take action!
(1) Specify Provider
BASH
pi-agent chat --provider openai --model gpt-4o "Explain quantum entanglement"
(2) Specify Skill
BASH
pi-agent chat --skill code_review "Review this Python code"
2. Python Code Chat
A more flexible approach uses the Python API:
(1) Simplest Chat
PYTHON
from pi_agent import Agent
agent = Agent(name="hello")
response = agent.chat("Hello, Pi Agent!")
print(response)
(2) Multi-Turn Conversation
PYTHON
from pi_agent import Agent
agent = Agent(name="tutor", system_prompt="You are a Python programming tutor")
r1 = agent.chat("What are list comprehensions?")
print(r1)
r2 = agent.chat("Give me a practical example")
print(r2)
r3 = agent.chat("What are the advantages over for loops?")
print(r3)
(3) Structured Response
PYTHON
from pi_agent import Agent
agent = Agent(name="structured")
response = agent.chat(
"List 5 programming languages with their names and invention years",
response_format="json"
)
print(type(response)) # <class 'dict'>
3. Message Format
Pi Agent uses standard message format internally:
PYTHON
messages = [
{"role": "system", "content": "You are a coding assistant"},
{"role": "user", "content": "What are decorators?"},
{"role": "assistant", "content": "Decorators are..."},
{"role": "user", "content": "Can you give an example?"}
]
| Role | Description |
|---|---|
| system | System prompt, defines Agent behavior |
| user | User input |
| assistant | Agent response |
| tool | Tool call result |
4. System Prompt
System prompts define the Agent's "persona" and behavioral boundaries:
Example 1: Different Agent Roles (Difficulty: ⭐)
PYTHON
from pi_agent import Agent
coder = Agent(
name="coder",
system_prompt="You are a Python expert. Respond concisely with code and key explanations only"
)
teacher = Agent(
name="teacher",
system_prompt="You are a patient programming teacher. Explain concepts with analogies and step-by-step breakdowns"
)
q = "What are generators?"
print("=== Coder ===")
print(coder.chat(q))
print("=== Teacher ===")
print(teacher.chat(q))
5. Streaming Output
For long responses, streaming lets you see results in real-time:
PYTHON
from pi_agent import Agent
agent = Agent(name="stream")
for chunk in agent.chat_stream("Write a poem about programming"):
print(chunk, end="", flush=True)
Alice compared modes: "Streaming is so much better — no staring at a blank screen waiting."
6. Response Object Details
The chat() method returns more than just text:
PYTHON
from pi_agent import Agent
agent = Agent(name="meta")
response = agent.chat("1+1=?")
print(response.text) # "2"
print(response.model) # "deepseek-chat"
print(response.usage) # {"prompt_tokens": 12, "completion_tokens": 3}
print(response.tool_calls) # [] (records if tools were called)
print(response.finish_reason) # "stop"
FAQ
Q chat() or chat_stream()?
A Use chat() for short Q&A, chat_stream() for long text generation. Streaming doesn't affect the result, only user experience.
Q Does multi-turn context grow indefinitely?
A No. Pi Agent manages the context window automatically, truncating oldest messages when the limit is exceeded. Set context_window when creating an Agent.
Q How to force the Agent to use tools?
A Set tool_choice="required", or explicitly instruct "Please use the search tool to find..." in your message.
Summary
- CLI:
pi-agent chatfor quick chat; Python:Agent.chat()for programmatic use - Supports multi-turn conversations, structured responses, streaming output
- System prompts define Agent persona; messages follow the role/content standard
- Response objects include text, model info, token usage, and other metadata
Exercises
- Basic (Difficulty: ⭐): Send a message using both CLI and Python, compare the experience.
- Intermediate (Difficulty: ⭐⭐): Create two Agents with different system_prompts, get different styles of answers to the same question.
- Advanced (Difficulty: ⭐⭐⭐): Implement a "real-time typewriter" effect using streaming output.
