How to Develop an Agent with Remote Tools#
This guide demonstrates how to:
Define properties to document the types of tool arguments and variables used in prompt templates
Configure remote tools that query external web APIs
Define the configuration for a LLM model
Define an agent with specific instructions and access to tools
Export the Agent Spec configuration for the agent
The assistant demonstrated in this guide focuses on helping users understand their benefits; however, the approach can be applied to other use-cases. The assistant is a flexible agent based on the ReAct framework. It has access to the tools to retrieve user-specific data and perform accurate calculations.
Basic implementation#
1. Define properties#
Properties help describe the inputs and outputs of assistant components, such as tools and nodes. They serve as documentation, particularly important for tools, to guide the agent in correctly passing values to tool arguments.
from pyagentspec.property import ListProperty, StringProperty
agent_title_property = StringProperty(
title="agent_title",
description="The agent title",
default="Benefits Assistant Agent",
)
agent_description_property = StringProperty(
title="agent_description",
description="The agent description",
default=(
"This agent provides employees with accurate and efficient responses to"
"benefits-related inquiries"
),
)
workflow_title_property = StringProperty(
title="workflow_title",
description="The workflow title",
default="Benefits Advisor Workflow",
)
workflow_description_property = StringProperty(
title="workflow_description",
description="The workflow description",
default=(
"This Agent workflow is designed for integration within the benefits product's chatbot, "
"enabling seamless interaction with employees."
),
)
topics_property = StringProperty(
title="topics",
description="The topics",
default=(
"- Medical Insurance"
"\n- General Benefits Coverage"
"\n- Retirement Benefits Coverage"
"\n- Employee Benefits Enrollments"
),
)
special_instructions_property = StringProperty(
title="special_instructions",
description="The special instructions",
default=(
"\n- If insufficient data is available to answer a query, ask the user for clarification or additional information."
"\n- Only entertain questions related to benefits."
"\n- Fetch factual information from documents using the RAG Retriever tool instead of generating it yourself."
"\n- For user-specific details like costs or savings, use the REST tool to obtain only relevant information."
"\n- Use the Calculator Tool for queries requiring calculations."
"\n- Provide relevant details (e.g., insurance company, health plan, names, dates) as input to the RAG Retriever tool for effective semantic search."
"\n- If a question is repeated, respond politely without mentioning the repetition."
"\n- Your goal is to consolidate information retrieved from tools into a coherent answer addressing the user's query."
"\n- Treat the USER_QUERY as the sole source of the user's question."
),
)
format_instructions_property = StringProperty(title="format_instructions")
context_property = StringProperty(title="context")
employee_property = StringProperty(title="employee_id")
task_property = StringProperty(
title="task",
description="A task, expressed as an imperative, of which data to look up in the database",
)
query_property = StringProperty(
title="query",
description="The query string in interrogative form to be used to retrieve documents for addressing user questions.",
)
problem_property = StringProperty(
title="problem",
description="A mathematical problem in natural language.",
)
benefits_enrollment_status_property = StringProperty(
title="benefits_enrollment_status",
description="Output of the tool Benefits_Enrollment_Status_REST_API_Tool",
)
cost_and_contribution_property = StringProperty(
title="cost_and_contribution",
description="Output of the tool Costs_and_Contributions_REST_API_Tool",
)
coverage_and_plan_details_property = StringProperty(
title="coverage_and_plan",
description="Output of the tool Coverage_and_Plan_Details_REST_API_Tool",
)
dependents_and_beneficiaries_property = StringProperty(
title="dependents_and_beneficiaries",
description="Output of the tool Dependents_and_Beneficiaries_REST_API_Tool",
)
providers_and_policy_info_property = StringProperty(
title="providers_and_policy_info",
description="Output of the tool Providers_and_Policy_Information_REST_API_Tool",
)
calculator_output_property = StringProperty(
title="calculator_output",
description="Output of the tool Calculator_Tool",
)
benefits_policy_rag_property = ListProperty(
title="benefits_policy_rag",
description="Output of the tool RAG_Retrieval_Tool",
item_type=StringProperty(),
)
API Reference: Property
2. Define the remote tools#
Tools are separate methods that the agent can decide to call by passing input arguments in order to fulfill user requests. This section focuses on remote tools, which are configured to send HTTP requests to external web APIs.
from urllib.parse import urljoin
from pyagentspec.tools.remotetool import RemoteTool
# Change this url depending on where the API is hosted
remote_tools_url: str = "http://127.0.0.1:HOST_PORT/"
tools = [
RemoteTool(
name="Benefits_Enrollment_Status_REST_API_Tool",
description="Tracks the current status and pending actions related to benefits enrollment.",
url=urljoin(remote_tools_url, "benefits/{{task}}"),
http_method="GET",
inputs=[task_property],
outputs=[benefits_enrollment_status_property],
),
RemoteTool(
name="Costs_and_Contributions_REST_API_Tool",
description="Generates a breakdown of costs and contributions associated with benefits plans.",
url=urljoin(remote_tools_url, "costs"),
http_method="GET",
data={"employee_id": "{{employee_id}}"},
inputs=[employee_property],
outputs=[cost_and_contribution_property],
),
RemoteTool(
name="Coverage_and_Plan_Details_REST_API_Tool",
description="Provides detailed information about the employee's existing benefits coverage and plans.",
url=urljoin(remote_tools_url, "coverage/{{task}}"),
http_method="GET",
inputs=[task_property],
outputs=[coverage_and_plan_details_property],
),
RemoteTool(
name="Dependents_and_Beneficiaries_REST_API_Tool",
description="Retrieves information about dependents and beneficiaries linked to benefits plans.",
url=urljoin(remote_tools_url, "dependents/{{task}}"),
http_method="GET",
inputs=[task_property],
outputs=[dependents_and_beneficiaries_property],
),
RemoteTool(
name="Providers_and_Policy_Information_REST_API_Tool",
description="Offers details about benefits providers and policy-related information.",
url=urljoin(remote_tools_url, "providers/{{task}}"),
http_method="GET",
inputs=[task_property],
outputs=[providers_and_policy_info_property],
),
RemoteTool(
name="RAG_Retrieval_Tool",
description="This tool empowers agents to retrieve HR benefits policy documents or chunks of documents from a knowledge base, enhancing the accuracy of responses.",
url=urljoin(remote_tools_url, "rag"),
data={"query": "{{query}}"},
http_method="GET",
inputs=[query_property],
outputs=[benefits_policy_rag_property],
),
RemoteTool(
name="Calculator_Tool",
description="This tool allows agents to perform real-time mathematical computations for needs like estimates of benefits costs, deductibles, coverages, etc.",
url=urljoin(remote_tools_url, "calculator"),
data={"problem": "{{problem}}"},
http_method="POST",
inputs=[problem_property],
outputs=[calculator_output_property],
),
]
API Reference: RemoteTool
Note
Never commit sensitive data such as API keys or authentication tokens when using RemoteTool. Use secret management solutions instead.
3. Define a LLM model#
The decision mechanism of Agents is powered by a Large Language Model. Defining the agent with Agent Spec requires to pass the configuration for the LLM. There are several options such as using OCI GenAI Service or self hosting a model with vLLM.
from pyagentspec.llms import OciGenAiConfig
from pyagentspec.llms.ociclientconfig import OciClientConfigWithApiKey
client_config = OciClientConfigWithApiKey(
name="Oci Client Config",
service_endpoint="https://url-to-service-endpoint.com",
auth_profile="DEFAULT",
auth_file_location="~/.oci/config"
)
llm_config = OciGenAiConfig(
name="Oci GenAI Config",
model_id="provider.model-id",
compartment_id="compartment-id",
client_config=client_config,
)
from pyagentspec.llms import VllmConfig
llm_config = VllmConfig(
name="Llama 3.1 8B instruct",
url="VLLM_URL",
model_id="model-id",
)
from pyagentspec.llms import OllamaConfig
llm_config = OllamaConfig(
name="Ollama Config",
model_id="model-id",
)
API Reference: VllmConfig
4. Define the agent#
The agent is defined with custom instructions that include placeholder variables and the list of accessible tools.
from pyagentspec.agent import Agent
system_prompt = """You are a helpful agent. Your official title is: {{agent_title}}.
The following statement describes your responsibilities:
"{{agent_description}}".
You are part of the workflow {{workflow_title}} within the company.
The following is a quick description of the workflow:
"{{workflow_description}}".
Your tasks are related to the following topics with their special instructions:
{{topics}}
Here are some extra special instructions:
{{special_instructions}}
Your answer is intended to be customer-facing, be sure to be professional in your response.
Do not invent answers or information.
{{format_instructions}}
{{context}}
"""
agent = Agent(
name="Benefits Advisor",
llm_config=llm_config,
tools=tools,
system_prompt=system_prompt,
inputs=[
agent_title_property,
agent_description_property,
workflow_title_property,
workflow_description_property,
topics_property,
format_instructions_property,
special_instructions_property,
context_property,
],
)
API Reference: Agent
5. Export the Agent Spec configuration#
The Agent Spec configuration is generated in JSON format. These configurations can be loaded and executed in Agent Spec-compatible systems such as the WayFlow runtime. See, for example, How to Execute Agent Spec Configurations with WayFlow.
if __name__ == "__main__":
from pyagentspec.serialization import AgentSpecSerializer
serialized_agent = AgentSpecSerializer().to_json(agent)
# you can print the serialized form or save it to a file
print(serialized_agent)
API Reference: AgentSpecSerializer.
Here is what the Agent Spec representation will look like ↓
Click here to see the assistant configuration.
{
"component_type": "Agent",
"id": "92ec5e14-616a-43bc-9d8b-9003d41b62a8",
"name": "Benefits Advisor",
"description": null,
"metadata": {},
"inputs": [
{
"description": "The agent title",
"title": "agent_title",
"default": "Benefits Assistant Agent",
"type": "string"
},
{
"description": "The agent description",
"title": "agent_description",
"default": "This agent provides employees with accurate and efficient responses tobenefits-related inquiries",
"type": "string"
},
{
"description": "The workflow title",
"title": "workflow_title",
"default": "Benefits Advisor Workflow",
"type": "string"
},
{
"description": "The workflow description",
"title": "workflow_description",
"default": "This Agent workflow is designed for integration within the benefits product's chatbot, enabling seamless interaction with employees.",
"type": "string"
},
{
"description": "The topics",
"title": "topics",
"default": "- Medical Insurance\n- General Benefits Coverage\n- Retirement Benefits Coverage\n- Employee Benefits Enrollments",
"type": "string"
},
{
"title": "format_instructions",
"type": "string"
},
{
"description": "The special instructions",
"title": "special_instructions",
"default": "\n- If insufficient data is available to answer a query, ask the user for clarification or additional information.\n- Only entertain questions related to benefits.\n- Fetch factual information from documents using the RAG Retriever tool instead of generating it yourself.\n- For user-specific details like costs or savings, use the REST tool to obtain only relevant information.\n- Use the Calculator Tool for queries requiring calculations.\n- Provide relevant details (e.g., insurance company, health plan, names, dates) as input to the RAG Retriever tool for effective semantic search.\n- If a question is repeated, respond politely without mentioning the repetition.\n- Your goal is to consolidate information retrieved from tools into a coherent answer addressing the user's query.\n- Treat the USER_QUERY as the sole source of the user's question.",
"type": "string"
},
{
"title": "context",
"type": "string"
}
],
"outputs": [],
"llm_config": {
"component_type": "VllmConfig",
"id": "33fbdf52-bb7b-4cb7-b169-782c2a368a4c",
"name": "Vllm model",
"description": null,
"metadata": {},
"default_generation_parameters": null,
"url": "vllm_url",
"model_id": "model_id"
},
"system_prompt": "You are a helpful agent. Your official title is: {{agent_title}}.\nThe following statement describes your responsibilities:\n\"{{agent_description}}\".\n\nYou are part of the workflow {{workflow_title}} within the company.\nThe following is a quick description of the workflow:\n\"{{workflow_description}}\".\n\nYour tasks are related to the following topics with their special instructions:\n{{topics}}\n\nHere are some extra special instructions:\n{{special_instructions}}\n\nYour answer is intended to be customer-facing, be sure to be professional in your response.\nDo not invent answers or information.\n\n{{format_instructions}}\n\n{{context}}\n",
"tools": [
{
"component_type": "RemoteTool",
"id": "802966ae-5992-4f6f-867f-c7a9c0f3a624",
"name": "Benefits_Enrollment_Status_REST_API_Tool",
"description": "Tracks the current status and pending actions related to benefits enrollment.",
"metadata": {},
"inputs": [
{
"description": "A task, expressed as an imperative, of which data to look up in the database",
"title": "task",
"type": "string"
}
],
"outputs": [
{
"description": "Output of the tool Benefits_Enrollment_Status_REST_API_Tool",
"title": "benefits_enrollment_status",
"type": "string"
}
],
"url": "http://127.0.0.1:HOST_PORT/benefits/{{task}}",
"http_method": "GET",
"api_spec_uri": null,
"data": {},
"query_params": {},
"headers": {}
},
{
"component_type": "RemoteTool",
"id": "c74ddba5-c3bc-4493-9805-3b423595ca9d",
"name": "Costs_and_Contributions_REST_API_Tool",
"description": "Generates a breakdown of costs and contributions associated with benefits plans.",
"metadata": {},
"inputs": [
{
"title": "employee_id",
"type": "string"
}
],
"outputs": [
{
"description": "Output of the tool Costs_and_Contributions_REST_API_Tool",
"title": "cost_and_contribution",
"type": "string"
}
],
"url": "http://127.0.0.1:HOST_PORT/costs",
"http_method": "GET",
"api_spec_uri": null,
"data": {
"employee_id": "{{employee_id}}"
},
"query_params": {},
"headers": {}
},
{
"component_type": "RemoteTool",
"id": "70c1bde5-7c34-4408-bd05-9183b881be17",
"name": "Coverage_and_Plan_Details_REST_API_Tool",
"description": "Provides detailed information about the employee's existing benefits coverage and plans.",
"metadata": {},
"inputs": [
{
"description": "A task, expressed as an imperative, of which data to look up in the database",
"title": "task",
"type": "string"
}
],
"outputs": [
{
"description": "Output of the tool Coverage_and_Plan_Details_REST_API_Tool",
"title": "coverage_and_plan",
"type": "string"
}
],
"url": "http://127.0.0.1:HOST_PORT/coverage/{{task}}",
"http_method": "GET",
"api_spec_uri": null,
"data": {},
"query_params": {},
"headers": {}
},
{
"component_type": "RemoteTool",
"id": "15b41806-a999-48dc-8b59-29d2ab3af466",
"name": "Dependents_and_Beneficiaries_REST_API_Tool",
"description": "Retrieves information about dependents and beneficiaries linked to benefits plans.",
"metadata": {},
"inputs": [
{
"description": "A task, expressed as an imperative, of which data to look up in the database",
"title": "task",
"type": "string"
}
],
"outputs": [
{
"description": "Output of the tool Dependents_and_Beneficiaries_REST_API_Tool",
"title": "dependents_and_beneficiaries",
"type": "string"
}
],
"url": "http://127.0.0.1:HOST_PORT/dependents/{{task}}",
"http_method": "GET",
"api_spec_uri": null,
"data": {},
"query_params": {},
"headers": {}
},
{
"component_type": "RemoteTool",
"id": "3d6dd5ec-d7d9-4da0-b300-b70b6832849a",
"name": "Providers_and_Policy_Information_REST_API_Tool",
"description": "Offers details about benefits providers and policy-related information.",
"metadata": {},
"inputs": [
{
"description": "A task, expressed as an imperative, of which data to look up in the database",
"title": "task",
"type": "string"
}
],
"outputs": [
{
"description": "Output of the tool Providers_and_Policy_Information_REST_API_Tool",
"title": "providers_and_policy_info",
"type": "string"
}
],
"url": "http://127.0.0.1:HOST_PORT/providers/{{task}}",
"http_method": "GET",
"api_spec_uri": null,
"data": {},
"query_params": {},
"headers": {}
},
{
"component_type": "RemoteTool",
"id": "a1c88588-ddf0-4760-bef8-799007390b33",
"name": "RAG_Retrieval_Tool",
"description": "This tool empowers agents to retrieve HR benefits policy documents or chunks of documents from a knowledge base, enhancing the accuracy of responses.",
"metadata": {},
"inputs": [
{
"description": "The query string in interrogative form to be used to retrieve documents for addressing user questions.",
"title": "query",
"type": "string"
}
],
"outputs": [
{
"description": "Output of the tool RAG_Retrieval_Tool",
"title": "benefits_policy_rag",
"items": {
"type": "string"
},
"type": "array"
}
],
"url": "http://127.0.0.1:HOST_PORT/rag",
"http_method": "GET",
"api_spec_uri": null,
"data": {
"query": "{{query}}"
},
"query_params": {},
"headers": {}
},
{
"component_type": "RemoteTool",
"id": "2edd172c-b745-45d8-a6b9-07906e5d6923",
"name": "Calculator_Tool",
"description": "This tool allows agents to perform real-time mathematical computations for needs like estimates of benefits costs, deductibles, coverages, etc.",
"metadata": {},
"inputs": [
{
"description": "A mathematical problem in natural language.",
"title": "problem",
"type": "string"
}
],
"outputs": [
{
"description": "Output of the tool Calculator_Tool",
"title": "calculator_output",
"type": "string"
}
],
"url": "http://127.0.0.1:HOST_PORT/calculator",
"http_method": "POST",
"api_spec_uri": null,
"data": {
"problem": "{{problem}}"
},
"query_params": {},
"headers": {}
}
],
"agentspec_version": "25.4.1"
}
component_type: Agent
id: 292195eb-fb2a-4877-a4a2-515b3c69e7e3
name: Benefits Advisor
description: null
metadata: {}
inputs:
- description: The agent title
title: agent_title
default: Benefits Assistant Agent
type: string
- description: The agent description
title: agent_description
default: This agent provides employees with accurate and efficient responses tobenefits-related
inquiries
type: string
- description: The workflow title
title: workflow_title
default: Benefits Advisor Workflow
type: string
- description: The workflow description
title: workflow_description
default: This Agent workflow is designed for integration within the benefits product's
chatbot, enabling seamless interaction with employees.
type: string
- description: The topics
title: topics
default: '- Medical Insurance
- General Benefits Coverage
- Retirement Benefits Coverage
- Employee Benefits Enrollments'
type: string
- title: format_instructions
type: string
- description: The special instructions
title: special_instructions
default: '
- If insufficient data is available to answer a query, ask the user for clarification
or additional information.
- Only entertain questions related to benefits.
- Fetch factual information from documents using the RAG Retriever tool instead
of generating it yourself.
- For user-specific details like costs or savings, use the REST tool to obtain
only relevant information.
- Use the Calculator Tool for queries requiring calculations.
- Provide relevant details (e.g., insurance company, health plan, names, dates)
as input to the RAG Retriever tool for effective semantic search.
- If a question is repeated, respond politely without mentioning the repetition.
- Your goal is to consolidate information retrieved from tools into a coherent
answer addressing the user''s query.
- Treat the USER_QUERY as the sole source of the user''s question.'
type: string
- title: context
type: string
outputs: []
llm_config:
component_type: VllmConfig
id: d7f7636a-48b3-42b3-b704-d43692ee5505
name: Vllm model
description: null
metadata: {}
default_generation_parameters: null
url: vllm_url
model_id: model_id
system_prompt: 'You are a helpful agent. Your official title is: {{agent_title}}.
The following statement describes your responsibilities:
"{{agent_description}}".
You are part of the workflow {{workflow_title}} within the company.
The following is a quick description of the workflow:
"{{workflow_description}}".
Your tasks are related to the following topics with their special instructions:
{{topics}}
Here are some extra special instructions:
{{special_instructions}}
Your answer is intended to be customer-facing, be sure to be professional in your
response.
Do not invent answers or information.
{{format_instructions}}
{{context}}
'
tools:
- component_type: RemoteTool
id: 1d052f2f-ae1d-47b2-ac8d-4bfc231c73b2
name: Benefits_Enrollment_Status_REST_API_Tool
description: Tracks the current status and pending actions related to benefits enrollment.
metadata: {}
inputs:
- description: A task, expressed as an imperative, of which data to look up in the
database
title: task
type: string
outputs:
- description: Output of the tool Benefits_Enrollment_Status_REST_API_Tool
title: benefits_enrollment_status
type: string
url: http://127.0.0.1:HOST_PORT/benefits/{{task}}
http_method: GET
api_spec_uri: null
data: {}
query_params: {}
headers: {}
- component_type: RemoteTool
id: 48799e60-eccd-4e1e-a1fd-9fc00d60de1e
name: Costs_and_Contributions_REST_API_Tool
description: Generates a breakdown of costs and contributions associated with benefits
plans.
metadata: {}
inputs:
- title: employee_id
type: string
outputs:
- description: Output of the tool Costs_and_Contributions_REST_API_Tool
title: cost_and_contribution
type: string
url: http://127.0.0.1:HOST_PORT/costs
http_method: GET
api_spec_uri: null
data:
employee_id: '{{employee_id}}'
query_params: {}
headers: {}
- component_type: RemoteTool
id: 1117282d-d092-4958-94d1-8043f00ab730
name: Coverage_and_Plan_Details_REST_API_Tool
description: Provides detailed information about the employee's existing benefits
coverage and plans.
metadata: {}
inputs:
- description: A task, expressed as an imperative, of which data to look up in the
database
title: task
type: string
outputs:
- description: Output of the tool Coverage_and_Plan_Details_REST_API_Tool
title: coverage_and_plan
type: string
url: http://127.0.0.1:HOST_PORT/coverage/{{task}}
http_method: GET
api_spec_uri: null
data: {}
query_params: {}
headers: {}
- component_type: RemoteTool
id: 2ef04e43-3097-4046-8108-fddb14493b95
name: Dependents_and_Beneficiaries_REST_API_Tool
description: Retrieves information about dependents and beneficiaries linked to
benefits plans.
metadata: {}
inputs:
- description: A task, expressed as an imperative, of which data to look up in the
database
title: task
type: string
outputs:
- description: Output of the tool Dependents_and_Beneficiaries_REST_API_Tool
title: dependents_and_beneficiaries
type: string
url: http://127.0.0.1:HOST_PORT/dependents/{{task}}
http_method: GET
api_spec_uri: null
data: {}
query_params: {}
headers: {}
- component_type: RemoteTool
id: e068c758-8903-4c1f-8304-848227439e7e
name: Providers_and_Policy_Information_REST_API_Tool
description: Offers details about benefits providers and policy-related information.
metadata: {}
inputs:
- description: A task, expressed as an imperative, of which data to look up in the
database
title: task
type: string
outputs:
- description: Output of the tool Providers_and_Policy_Information_REST_API_Tool
title: providers_and_policy_info
type: string
url: http://127.0.0.1:HOST_PORT/providers/{{task}}
http_method: GET
api_spec_uri: null
data: {}
query_params: {}
headers: {}
- component_type: RemoteTool
id: a3a3faa5-9b9e-47fc-a588-8619df752ed0
name: RAG_Retrieval_Tool
description: This tool empowers agents to retrieve HR benefits policy documents
or chunks of documents from a knowledge base, enhancing the accuracy of responses.
metadata: {}
inputs:
- description: The query string in interrogative form to be used to retrieve documents
for addressing user questions.
title: query
type: string
outputs:
- description: Output of the tool RAG_Retrieval_Tool
title: benefits_policy_rag
items:
type: string
type: array
url: http://127.0.0.1:HOST_PORT/rag
http_method: GET
api_spec_uri: null
data:
query: '{{query}}'
query_params: {}
headers: {}
- component_type: RemoteTool
id: c64aae7c-5987-4e57-ad21-89781f3587c7
name: Calculator_Tool
description: This tool allows agents to perform real-time mathematical computations
for needs like estimates of benefits costs, deductibles, coverages, etc.
metadata: {}
inputs:
- description: A mathematical problem in natural language.
title: problem
type: string
outputs:
- description: Output of the tool Calculator_Tool
title: calculator_output
type: string
url: http://127.0.0.1:HOST_PORT/calculator
http_method: POST
api_spec_uri: null
data:
problem: '{{problem}}'
query_params: {}
headers: {}
agentspec_version: 25.4.1
Recap#
This guide covered how to:
Define properties to document tool arguments and variables used in prompt templates
Define remote tools configured to query web APIs
Define the configuration for a LLM model
Define an agent with custom instructions and tool access
Export the Agent Spec configuration for the agent
Below is the complete code from this guide.
1
2from pyagentspec.property import ListProperty, StringProperty
3
4agent_title_property = StringProperty(
5 title="agent_title",
6 description="The agent title",
7 default="Benefits Assistant Agent",
8)
9
10agent_description_property = StringProperty(
11 title="agent_description",
12 description="The agent description",
13 default=(
14 "This agent provides employees with accurate and efficient responses to"
15 "benefits-related inquiries"
16 ),
17)
18
19workflow_title_property = StringProperty(
20 title="workflow_title",
21 description="The workflow title",
22 default="Benefits Advisor Workflow",
23)
24
25workflow_description_property = StringProperty(
26 title="workflow_description",
27 description="The workflow description",
28 default=(
29 "This Agent workflow is designed for integration within the benefits product's chatbot, "
30 "enabling seamless interaction with employees."
31 ),
32)
33
34topics_property = StringProperty(
35 title="topics",
36 description="The topics",
37 default=(
38 "- Medical Insurance"
39 "\n- General Benefits Coverage"
40 "\n- Retirement Benefits Coverage"
41 "\n- Employee Benefits Enrollments"
42 ),
43)
44
45special_instructions_property = StringProperty(
46 title="special_instructions",
47 description="The special instructions",
48 default=(
49 "\n- If insufficient data is available to answer a query, ask the user for clarification or additional information."
50 "\n- Only entertain questions related to benefits."
51 "\n- Fetch factual information from documents using the RAG Retriever tool instead of generating it yourself."
52 "\n- For user-specific details like costs or savings, use the REST tool to obtain only relevant information."
53 "\n- Use the Calculator Tool for queries requiring calculations."
54 "\n- Provide relevant details (e.g., insurance company, health plan, names, dates) as input to the RAG Retriever tool for effective semantic search."
55 "\n- If a question is repeated, respond politely without mentioning the repetition."
56 "\n- Your goal is to consolidate information retrieved from tools into a coherent answer addressing the user's query."
57 "\n- Treat the USER_QUERY as the sole source of the user's question."
58 ),
59)
60
61format_instructions_property = StringProperty(title="format_instructions")
62context_property = StringProperty(title="context")
63employee_property = StringProperty(title="employee_id")
64
65task_property = StringProperty(
66 title="task",
67 description="A task, expressed as an imperative, of which data to look up in the database",
68)
69
70query_property = StringProperty(
71 title="query",
72 description="The query string in interrogative form to be used to retrieve documents for addressing user questions.",
73)
74
75problem_property = StringProperty(
76 title="problem",
77 description="A mathematical problem in natural language.",
78)
79
80benefits_enrollment_status_property = StringProperty(
81 title="benefits_enrollment_status",
82 description="Output of the tool Benefits_Enrollment_Status_REST_API_Tool",
83)
84
85cost_and_contribution_property = StringProperty(
86 title="cost_and_contribution",
87 description="Output of the tool Costs_and_Contributions_REST_API_Tool",
88)
89
90coverage_and_plan_details_property = StringProperty(
91 title="coverage_and_plan",
92 description="Output of the tool Coverage_and_Plan_Details_REST_API_Tool",
93)
94
95dependents_and_beneficiaries_property = StringProperty(
96 title="dependents_and_beneficiaries",
97 description="Output of the tool Dependents_and_Beneficiaries_REST_API_Tool",
98)
99
100providers_and_policy_info_property = StringProperty(
101 title="providers_and_policy_info",
102 description="Output of the tool Providers_and_Policy_Information_REST_API_Tool",
103)
104
105calculator_output_property = StringProperty(
106 title="calculator_output",
107 description="Output of the tool Calculator_Tool",
108)
109
110benefits_policy_rag_property = ListProperty(
111 title="benefits_policy_rag",
112 description="Output of the tool RAG_Retrieval_Tool",
113 item_type=StringProperty(),
114)
115
116# .. end-define-properties:
117
118# .. define-tools:
119
120from urllib.parse import urljoin
121
122from pyagentspec.tools.remotetool import RemoteTool
123
124# Change this url depending on where the API is hosted
125remote_tools_url: str = "http://127.0.0.1:HOST_PORT/"
126
127tools = [
128 RemoteTool(
129 name="Benefits_Enrollment_Status_REST_API_Tool",
130 description="Tracks the current status and pending actions related to benefits enrollment.",
131 url=urljoin(remote_tools_url, "benefits/{{task}}"),
132 http_method="GET",
133 inputs=[task_property],
134 outputs=[benefits_enrollment_status_property],
135 ),
136 RemoteTool(
137 name="Costs_and_Contributions_REST_API_Tool",
138 description="Generates a breakdown of costs and contributions associated with benefits plans.",
139 url=urljoin(remote_tools_url, "costs"),
140 http_method="GET",
141 data={"employee_id": "{{employee_id}}"},
142 inputs=[employee_property],
143 outputs=[cost_and_contribution_property],
144 ),
145 RemoteTool(
146 name="Coverage_and_Plan_Details_REST_API_Tool",
147 description="Provides detailed information about the employee's existing benefits coverage and plans.",
148 url=urljoin(remote_tools_url, "coverage/{{task}}"),
149 http_method="GET",
150 inputs=[task_property],
151 outputs=[coverage_and_plan_details_property],
152 ),
153 RemoteTool(
154 name="Dependents_and_Beneficiaries_REST_API_Tool",
155 description="Retrieves information about dependents and beneficiaries linked to benefits plans.",
156 url=urljoin(remote_tools_url, "dependents/{{task}}"),
157 http_method="GET",
158 inputs=[task_property],
159 outputs=[dependents_and_beneficiaries_property],
160 ),
161 RemoteTool(
162 name="Providers_and_Policy_Information_REST_API_Tool",
163 description="Offers details about benefits providers and policy-related information.",
164 url=urljoin(remote_tools_url, "providers/{{task}}"),
165 http_method="GET",
166 inputs=[task_property],
167 outputs=[providers_and_policy_info_property],
168 ),
169 RemoteTool(
170 name="RAG_Retrieval_Tool",
171 description="This tool empowers agents to retrieve HR benefits policy documents or chunks of documents from a knowledge base, enhancing the accuracy of responses.",
172 url=urljoin(remote_tools_url, "rag"),
173 data={"query": "{{query}}"},
174 http_method="GET",
175 inputs=[query_property],
176 outputs=[benefits_policy_rag_property],
177 ),
178 RemoteTool(
179 name="Calculator_Tool",
180 description="This tool allows agents to perform real-time mathematical computations for needs like estimates of benefits costs, deductibles, coverages, etc.",
181 url=urljoin(remote_tools_url, "calculator"),
182 data={"problem": "{{problem}}"},
183 http_method="POST",
184 inputs=[problem_property],
185 outputs=[calculator_output_property],
186 ),
187]
188
189# .. end-define-tools:
190from pyagentspec.llms.vllmconfig import VllmConfig
191
192llm_config = VllmConfig(
193 name="Vllm model",
194 url="vllm_url",
195 model_id="model_id",
196)
197# .. define-agent:
198
199
200from pyagentspec.agent import Agent
201
202system_prompt = """You are a helpful agent. Your official title is: {{agent_title}}.
203The following statement describes your responsibilities:
204"{{agent_description}}".
205
206You are part of the workflow {{workflow_title}} within the company.
207The following is a quick description of the workflow:
208"{{workflow_description}}".
209
210Your tasks are related to the following topics with their special instructions:
211{{topics}}
212
213Here are some extra special instructions:
214{{special_instructions}}
215
216Your answer is intended to be customer-facing, be sure to be professional in your response.
217Do not invent answers or information.
218
219{{format_instructions}}
220
221{{context}}
222"""
223
224agent = Agent(
225 name="Benefits Advisor",
226 llm_config=llm_config,
227 tools=tools,
228 system_prompt=system_prompt,
229 inputs=[
230 agent_title_property,
231 agent_description_property,
232 workflow_title_property,
233 workflow_description_property,
234 topics_property,
235 format_instructions_property,
236 special_instructions_property,
237 context_property,
238 ],
239)
240
241# .. end-define-agent:
242
243# .. export-serialization:
244
245if __name__ == "__main__":
246
247 from pyagentspec.serialization import AgentSpecSerializer
248
249 serialized_agent = AgentSpecSerializer().to_json(agent)
250
251 # you can print the serialized form or save it to a file
252 print(serialized_agent)
253
Next steps#
Having learned how to define an agent, you may now proceed to how to use the WayFlow runtime to execute it.