tools-only Basic Agent Cookbook
Build a tool-calling AI agent with structured outputs using DSPy. For RAG tools, memory, and framework integrations, see here.
Docs to reference if needed:
- DSPy signatures: https://dspy.ai/learn/programming/signatures/
- DSPy language models: https://dspy.ai/learn/programming/language_models/
- LiteLLM providers: https://docs.litellm.ai/docs/
Core Rules
- Use a virtual environment via
venv - Use
uvfor Python project/dependency management. - Do not manually author
pyproject.tomloruv.lock; letuvgenerate/update them. - Use this install set:
uv add dspy python-dotenv - Customise this cookbook to the users specification, ask them for details if not given.
Env Rules
Mandatory:
- An LLM provider API key (e.g.
OPENAI_API_KEY,ANTHROPIC_API_KEY,GEMINI_API_KEY) WEAVIATE_URLWEAVIATE_API_KEY
Optional:
- Matching provider keys listed in
environment_requirements.md
If the user explicitly requests a non-Weaviate agent, WEAVIATE_URL and WEAVIATE_API_KEY can be omitted.
Agent Response Signature
The structured output that defines what the LLM returns when selecting tools.
import dspy
from typing import Any, Dict
class AgentResponse(dspy.Signature):
# Input Fields
history: dspy.History = dspy.InputField()
user_prompt: str = dspy.InputField()
available_tools: str = dspy.InputField()
# Output Fields
response: str = dspy.OutputField(
description="The response to the user's prompt whilst the tool is running. Update the user on the progress of their request (if a tool is picked), or the final response to the user (if no tool is picked)."
)
tool: str | None = dspy.OutputField(
description="The tool that needs to be used. Return None if no tool is needed."
)
tool_inputs: Dict[str, Any] | None = dspy.OutputField(
description=(
"The inputs for the tool. Return an empty dictionary (still include the field) if no inputs are needed. "
"The key is the name of the input, the value is the value of the input."
)
)
Extend AgentResponse as needed: add confidence: float for certainty scoring, requires_clarification: bool for follow-up questions, or modify description strings to shape agent behaviour for a specific domain.
Router Agent (Single Step)
Wraps the agent response into a class that manages conversation history and tool execution.
from typing import Callable, List, Tuple
class RouterAgent:
def __init__(self, model: str, tools: List[Callable] = []):
self.tools: list[Callable] = tools
self.model = dspy.LM(model)
self.agent = dspy.ChainOfThought(AgentResponse)
self.conversation_history = dspy.History(messages=[])
def add_conversation_history(self, message: str, response: dspy.Prediction):
self.conversation_history.messages.append({"user_prompt": message, **response})
def get_tools_and_descriptions(self) -> str:
return "\n".join(
[
f"{tool.__name__}:\nDescription: {tool.__doc__ or ''}\nInputs: { {k: v for k, v in tool.__annotations__.items() if k != 'return'} }"
for tool in self.tools
]
)
def get_response(self, user_prompt: str) -> Tuple[str, str | None]:
result = self.agent(
history=self.conversation_history,
user_prompt=user_prompt,
available_tools=self.get_tools_and_descriptions(),
lm=self.model,
)
self.add_conversation_history(message=user_prompt, response=result)
if result.tool and result.tool.lower() not in ["null", "none"]:
tool_function = next(
(tool for tool in self.tools if tool.__name__ == result.tool), None
)
if tool_function is None:
raise ValueError(f"Tool {result.tool} not found")
tool_inputs = {k: v for k, v in result.tool_inputs.items() if k != "return"}
tool_result = tool_function(**tool_inputs)
else:
tool_result = None
return result.response, tool_result
Usage:
router = RouterAgent(
model="<model_name>", # e.g. claude-sonnet-4-5, gpt-5.2, gemini-2.5-pro
tools=[your_tool_function]
)
response, tool_result = router.get_response("user query here")
Tool Design
Tools are Python functions. The agent reads __name__, __doc__, and __annotations__ to decide when to use them.
def your_tool(param1: str, param2: int) -> str:
"""Clear description of what this tool does and when to use it."""
# tool logic here
return "result as string"
Key rules:
- Docstrings directly influence when the agent selects the tool. Be specific: "Get current weather conditions for a city" is better than "Get weather".
- Type hints guide what inputs the agent provides. Complex types like
filters: List[Dict]may need additional description in the docstring. - Return strings or string-serializable data.
Sequential Multi-Step Agent
For tasks requiring multiple tool calls in succession, add a followup signature and loop.
Followup signature (receives tool_output from the previous step):
class AgentFollowup(dspy.Signature):
# Input Fields
history: dspy.History = dspy.InputField()
user_prompt: str = dspy.InputField()
tool_output: str = dspy.InputField(description="The output of the previous tool.")
available_tools: str = dspy.InputField(
description="The available tools and their descriptions."
)
# Output Fields
response: str = dspy.OutputField(
description="The response to the user's prompt whilst the tool is running. Update the user on the progress of their request (if a tool is picked), or the final response to the user (if no tool is picked)."
)
tool: str | None = dspy.OutputField(
description="The tool that needs to be used. Return None if no tool is needed."
)
tool_inputs: Dict[str, Any] | None = dspy.OutputField(
description="The inputs for the tool. Return an empty dictionary (still include the field) if no inputs are needed. The key is the name of the input, the value is the value of the input.",
)
Modify RouterAgent to loop until the agent stops requesting tools:
class RouterAgent:
def __init__(self, model: str, tools: List[Callable] = []):
self.tools: list[Callable] = tools
self.model = dspy.LM(model)
self.agent = dspy.ChainOfThought(AgentResponse)
self.followup_agent = dspy.ChainOfThought(AgentFollowup)
self.conversation_history = dspy.History(messages=[])
def add_conversation_history(self, message: str, response: dspy.Prediction):
self.conversation_history.messages.append({"user_prompt": message, **response})
def get_tools_and_descriptions(self) -> str:
return "\n".join(
[
f"{tool.__name__}:\nDescription: {tool.__doc__ or ''}\nInputs: { {k: v for k, v in tool.__annotations__.items() if k != 'return'} }"
for tool in self.tools
]
)
def get_response(self, user_prompt: str) -> str:
result = self.agent(
history=self.conversation_history,
user_prompt=user_prompt,
available_tools=self.get_tools_and_descriptions(),
lm=self.model,
)
self.add_conversation_history(message=user_prompt, response=result)
max_iter = 10
iter = 0
while result.tool is not None and result.tool.lower() not in ["null", "none"]:
iter += 1
if iter > max_iter:
break
tool_function = next(
(tool for tool in self.tools if tool.__name__ == result.tool), None
)
if tool_function is None:
raise ValueError(f"Tool {result.tool} not found")
tool_inputs = {k: v for k, v in result.tool_inputs.items() if k != "return"}
tool_result = tool_function(**tool_inputs)
result = self.followup_agent(
history=self.conversation_history,
tool_output=tool_result,
available_tools=self.get_tools_and_descriptions(),
lm=self.model,
)
self.add_conversation_history(message=tool_result, response=result)
return result.response
max_iter controls how many tool calls can occur before forced termination. Increase for complex multi-step tasks, decrease to limit costs and runaway loops.
User-specific Customisations
If not specified ask the user about these points before implementing their respective strategies:
LLM Framework
You can use DSPy (works with all LiteLLM providers) or LiteLLM itself.
Alternatively, users can use a single model provider. What model provider will they use?
- OpenAI (https://platform.openai.com/docs/libraries)
- Anthropic (https://platform.claude.com/docs/)
- Google GenAI (https://ai.google.dev/gemini-api/docs/libraries)
- Other (such as locally hosted models), use best judgement
These may require additional installs.
Model Selection
What model(s) will the user use? Consider a mixed approach: capable model for main agent routing, cheaper model for auxiliary tasks like memory creation.
Tools
What tools does the user need? List their functions, inputs, and expected outputs. The agent is only as capable as its tools.
Single-step vs Multi-step
Does the user need a single tool call per query, or should the agent chain multiple tools in sequence? Only use multi-step if the use case requires it.
Troubleshooting
- DSPy signature warnings about missing fields: ensure all input fields are passed or mark optional fields appropriately.
- Tool not found errors: ensure tool function names match exactly what the agent outputs.
- Agent loops indefinitely: lower
max_iteror add more explicit termination conditions. - For any other issues, refer to the official library/package documentation and use web search extensively for troubleshooting.
Done Criteria
- Create test scripts to check each function works independently with test data. Tear down tests after completion, or create a proper test suite with pytest (requires install)
- User has completed specification of the app.