Skip to main content

Getting Started

This guide shows how to install and start using parley.

The following article on 📝 level-up coding on medium also gives a hands-on guide and overview of parley.

Installation​

Parley is published on PyPI and can be installed with either uv (recommended) or pip.

Basic Installation​

This installs the base package without optional extras:

# Using uv (recommended)
uv add Parley

# Using pip
pip install Parley

Optional Dependencies​

Parley exposes several extras to enable additional functionality:

# Install with all optional dependencies
uv add "parley[all]"

# HTTP support (for web-based agents)
uv add "parley[http]"

# All supported LLM libraries
uv add "parley[llms]"

# Optional local PDF ingestion for RAG
uv add "parley[rag-pdf]"

# Development (all extras + testing tools)
uv add "parley[dev]"
Optional extras

You usually only need the extras that match your use case. parley[llms] installs every supported LLM SDK, so production projects may prefer installing only the provider libraries they actually use. Dependency-free in-memory and SQLite RAG are part of the base package; parley[rag-pdf] is needed only when the built-in loader reads local PDF files.

For development from source:

git clone https://github.com/AwsafOnom/Parley.git
cd Parley
uv pip install -e ".[dev]"
A2A from the first agent

Even the smallest Parley agent uses the A2A model: AgentCard declares identity and capabilities, while Task, Message, Part, and Artifact carry work and results. transport="http" serves Parley's native API by default. Add a2a=True when the agent should also expose and consume the A2A 1.0 JSON-RPC boundary. This is additive: native endpoints and native peer calls remain available. See A2A Core and 1.0 Compatibility for the exact scope.

First Agent​

Below is a compact example that wires together an agent, HTTP transport, an OpenAI-compatible LLM wrapper, and built-in, native, and MCP tools:

from parley.agents import Agent
from parley.models import AgentCard
from parley.tools import current_datetime, web_search
from parley.tools.adapters import MCPToolAdapter
from parley.llms.api import OpenAILLM
from parley.discovery import Registry

# Initialize Registry for A2A Discovery
registry = Registry(url="http://127.0.0.1:9000", transport="http")
registry.start(background=True)

# Define the agent card
agent_card = AgentCard(
    name="example_agent",
    description="A dummy agent",
    url="http://127.0.0.1:8020",
)

# OpenAI API LLM. If model is omitted, OpenAILLM uses its built-in default.
llm = OpenAILLM(model="gpt-4o-mini")

# Initialize the agent
agent = Agent(agent_card, transport="http", a2a=True, llm=llm, registry=registry)

# Add opt-in built-in tools
agent.add_tool(current_datetime())
agent.add_tool(web_search())

# Add Native tool
@agent.tool(name="add", description="Add two numbers")
async def add_numbers(a: int, b: int):
    return a + b

# Add MCP tools and return them as Parley native tools
mcp_adapter = MCPToolAdapter(transport="sse", url="https://api.example.com/mcp/sse")
mcp_tools = mcp_adapter.get_tools()
for mcp_tool in mcp_tools:
    agent.add_tool(mcp_tool)

# Start the agent
agent.start()

This example demonstrates the core pieces of Parley:

  • AgentCard to describe the agent.
  • Transport (here the "http" shortcut) for native agent communication, with a2a=True adding the A2A 1.0 inbound and outbound adapters.
  • LLM backend (OpenAILLM).
  • Built-in tools registered explicitly as ordinary Tool instances.
  • Native tools (Python functions decorated with @agent.tool).
  • MCP tools registered via MCPToolAdapter.

The built-ins require no additional package extra. web_search() defaults to Brave and reads BRAVE_SEARCH_API_KEY only when invoked. Pass engine="wikipedia" for documented, keyless English Wikipedia search or engine="duckduckgo" for keyless, best-effort DuckDuckGo HTML search. It declares network.read, and registering it does not perform a network request. Built-ins are opt-in, and the default capability policy is allow-by-default, so configure a restrictive CapabilityPolicy when network access should be denied or approval-gated. See Tools for the complete API and safety behavior.

Using the CLI​

Create a runnable one-file starter agent:

parley init agent
uv run python agent.py

The default starter uses the top-level API:

from parley import Agent, AgentCard, LocalTraceTelemetry, Task, create_llm

It runs locally without an API key by executing a tool call directly. If OPENAI_API_KEY is set, it also enables LLM inference. Use --template tool for a tool-only starter or --force to overwrite an existing file.