Setting Up a Python Environment and API Keys for Agent Development

A reliable setup for agent development has four parts: an isolated virtual environment, API keys loaded from environment variables, a pinned list of dependencies, and a tiny smoke test that proves the model call works. Getting these right once saves hours of confusing errors later, especially when you try several frameworks that want different package versions.

Create a virtual environment

Agent libraries move fast and often pin their own versions of shared packages such as pydantic and httpx. Installing two frameworks into the same environment is a common source of conflicts. Make one environment per project.

mkdir agent-lab && cd agent-lab
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

On Windows, activate with .venv\Scripts\activate. If you use the uv tool, uv venv and uv pip install do the same job faster. Check that which python points inside .venv before you install anything.

Store API keys safely

Never paste a key into source code. Put it in a .env file, add that file to .gitignore, and load it at start-up.

# .env
ANTHROPIC_API_KEY=your-key-here
OPENAI_API_KEY=your-key-here

echo ".env" >> .gitignore
echo ".venv/" >> .gitignore
pip install python-dotenv

Most agent frameworks read the standard variable names directly. The Anthropic client reads ANTHROPIC_API_KEY and the OpenAI client reads OPENAI_API_KEY. Calling load_dotenv() at the top of your script puts the values from the file into the process environment so those clients can find them.

Install a framework and pin it

pip install anthropic pydantic-ai
pip freeze > requirements.txt

Committing requirements.txt means a teammate, a CI job or your future self can rebuild the exact environment. For libraries that change quickly, this step matters more than it does for stable ones.

Write a smoke test

Before building anything, confirm that a model call works. This isolates key and network problems from framework problems.

# smoke_test.py
from dotenv import load_dotenv
import anthropic

load_dotenv()

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=100,
    messages=[{"role": "user", "content": "Reply with the single word: ready"}],
)
print(message.content[0].text)

Run python smoke_test.py. You should see the word ready. If you get an authentication error, the key is missing or wrong. If you get a connection error, check your network or proxy settings.

Choose a project layout

Even a small agent project benefits from structure. This layout keeps tools, prompts and entry points apart:

agent-lab/
  .env
  .gitignore
  requirements.txt
  src/
    agent.py        # builds the agent
    tools.py        # plain functions used as tools
    prompts.py      # system prompt strings
  tests/
    test_tools.py
  main.py           # entry point

Keeping tools as plain functions in their own module has a real payoff. You can unit test them without any model, and you can reuse them between frameworks, which later posts rely on.

Common setup problems

• Wrong Python: the shell finds a system Python instead of the environment's. Re-activate and check which python.
• Key not loaded: load_dotenv() was called after the client was created, or the file is in another directory.
• Version conflicts: two frameworks requiring different pydantic ranges. Use separate environments.
• Committed secrets: if a key reaches a repository, revoke it immediately and create a new one.
• Async errors: several frameworks expose async APIs; calling them from a notebook may need await directly rather than asyncio.run.

With the environment ready, the next posts start with LangChain, the best-known library in this space.

Why isolation matters more for agents

Agent projects pull in many dependencies at once: a model client, a framework, a vector store client, a web framework for serving and test tools. Each has its own idea of which versions of shared libraries are acceptable. A virtual environment keeps that mess out of your system Python and makes the project reproducible. It also lets you throw an experiment away: delete the folder, create a new one and start clean. Many people keep one environment per framework they evaluate, which makes comparisons fair because no leftover package from one trial changes the result of another.

Record the Python version too. Several agent libraries require a recent Python 3 release, and the error shown when the version is too old is often confusing. Write the version you used in a README or a .python-version file so others can match it.