These are the agents used to power the IBM Granite Playground.

Implemented using beeai-framework, the agents can be exposed with the A2A (or the deprecated ACP) protocol:

• basic chat with Granite (no external sources)
• chat with thinking (no external sources, the LLM will perform additional reasoning steps)
• chat plus search (uses an external search source DuckDuckGo|Google|Tavily)
• deep research (uses external search with additional planning and recursion)

• Python (version range specified in individual pyproject.toml files)
• UV package manager: https://docs.astral.sh/uv/
• An A2A client e.g. Agent Stack recommended
• Access to an LLM e.g. Ollama

This guide will get you started with the out-of-the-box agent configuration. This may not be optimally configured for your desired use case and as such, we recommend looking at the configuration after you have successfully run the agents using the defaults. The configuration options can be overridden with environment variables (including via a .env file).

The default LLM provider is a local Ollama server. You need to have Ollama downloaded and running on your machine with the Granite 4 model. Follow these steps:

1. Go to Ollama and download the installer for your system
2. Start the Ollama server
3. Pull the ibm/granite4 and the nomic-embed-text models

   ollama pull ibm/granite4:latest
   ollama pull nomic-embed-text:latest

An A2A client is required to use the agents. The agents are designed to work with the Agent Stack Platform and take advantage of several A2A extensions offered by the platform. Follow these steps:

1. Refer to the Agent Stack quick start guide to download and install the platform

2. Run the platform

   agentstack platform start
   # wait for the platform to fully start before moving on

There is a agentstack-cli reference you can use for further commands but the above is sufficient to get started.

Select which agent you would like to run and start the agent:

# pick one of these
uv --directory a2a run -m a2a_agents.agent_chat
uv --directory a2a run -m a2a_agents.agent_search
uv --directory a2a run -m a2a_agents.agent_research
uv --directory a2a run -m a2a_agents.agent

After starting the agent, you will see lots of log output. If you're running the Agent Stack Platform then the agent will register itself with the platform and you will see the following log message that indicates success:

INFO     | agentstack_sdk | Agent registered successfully

You can now interact with the agents via the Agent Stack Platform user interface in your web browser. Run the following to start your web browser at the appropriate page:

agentstack ui

The UI will start in your web browser. Select the ☰ hamburger menu (top left) and click on the Granite agent that you are running. Once selected, you can type your prompt into the input box to run the agent.

uv --directory acp run -m acp_agent.agent

curl -X POST \
  --url http://localhost:8000/runs \
  -H 'content-type: application/json' \
  -d '{
      "agent_name": "granite-chat",
      "input": [
        {
          "role": "user",
          "parts": [
            {
              "content": "Hello"
            }
          ]
        }
      ],
      "mode": "stream"
  }'

The core library is designed to use Granite models that can be served from a variety of back ends. To configure the library, ensure environment variables are in place when running the code (this can be done via a .env file). The full configuration options available are documented in the granite_core config.py file where you will find a brief description of each option, the data type it expects, potential limitations on values and a default value.

The agents are configured in a similar way to the core, via environment variables (that can also be set via a .env file). The configurations are in the relevant config.py files for each agent. The agents will start without any additional configuration by adopting default values such as using Granite models served via a local Ollama and search provided by simple a DuckDuckGo implementation. This is sufficient for initial/early experimental usage. However, you are encouraged to explore the options to achieve better performance for your use case.

The following table illustrates some of the main options:

Retriever options don't have default values but must be used if configuring an alternate retriever:

LLM provider options don't have default values but must be used if configuring an alternate LLM provider:

For development work on the agents, you must install pre-commit and the pre-commit hooks prior to modifying the code:

pre-commit install

All pre-commit hooks must be run and pass before code is accepted into the repository.

Unit tests verify that individual components of the codebase work as expected, helping catch bugs early and ensuring long-term reliability.

Unit tests run on the default agent configuration. To run unit tests you need to have ollama installed and the ibm/granite4 model pulled.

uv --directory granite_core run pytest

Guidelines

• Place all core library test files under granite_core/tests/.
• Name test files as test_*.py.
• Use clear, isolated test cases with minimal dependencies.
• Run tests regularly before commits to maintain code quality.

podman build -t granite-playground-agents:latest -f a2a/Dockerfile .

podman run --env-file .env --name granite-playground-agents -p 8000:8000 --rm granite-playground-agents:latest