Skip to content

Commit

Permalink
updates docstring examples
Browse files Browse the repository at this point in the history
  • Loading branch information
@BWMac
BWMac committed Jan 22, 2025
1 parent 9b67e63 commit 13c8a0b
Show file tree
Hide file tree
Showing 2 changed files with 466 additions and 15 deletions.
243 changes: 238 additions & 5 deletions synapseclient/models/agent.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -144,14 +144,14 @@ class AgentSession(AgentSessionSynchronousProtocol):
etag: The etag of the agent session.
Note: It is recommended to use the `Agent` class to conduct chat sessions,
but you are free to use this class directly if you wish.
but you are free to use AgentSession directly if you wish.
Example: Start a session and send a prompt.
Start a session with a custom agent by providing the agent's registration ID and calling `start()`.
Then, send a prompt to the agent.
from synapseclient import Synapse
from synapseclient.models.agent import AgentSession, AgentSessionAccessLevel
from synapseclient.models.agent import AgentSession
syn = Synapse()
syn.login()
Expand All @@ -168,7 +168,7 @@ class AgentSession(AgentSessionSynchronousProtocol):
Then, send a prompt to the agent.
from synapseclient import Synapse
from synapseclient.models.agent import AgentSession, AgentSessionAccessLevel
from synapseclient.models.agent import AgentSession
syn = Synapse()
syn.login()
Expand Down Expand Up @@ -259,6 +259,23 @@ async def start_async(
Returns:
The new AgentSession object.
Example: Start a session and send a prompt.
Start a session with a custom agent by providing the agent's registration ID and calling `start()`.
Then, send a prompt to the agent.
from synapseclient import Synapse
from synapseclient.models.agent import AgentSession
syn = Synapse()
syn.login()
my_session = await AgentSession(agent_registration_id="foo").start_async()
await my_session.prompt_async(
prompt="Hello",
enable_trace=True,
print_response=True,
)
"""
session_response = await start_session(
access_level=self.access_level,
Expand All @@ -282,6 +299,23 @@ async def get_async(
Returns:
The retrieved AgentSession object.
Example: Get an existing session and send a prompt.
Retrieve an existing session by providing the session ID and calling `get()`.
Then, send a prompt to the agent.
from synapseclient import Synapse
from synapseclient.models.agent import AgentSession
syn = Synapse()
syn.login()
my_session = await AgentSession(id="foo").get_async()
await my_session.prompt_async(
prompt="Hello",
enable_trace=True,
print_response=True,
)
"""
session_response = await get_session(
id=self.id,
Expand All @@ -307,6 +341,20 @@ async def update_async(
Returns:
The updated AgentSession object.
Example: Update the access level of an existing session.
Retrieve an existing session by providing the session ID and calling `get()`.
Then, update the access level of the session and call `update()`.
from synapseclient import Synapse
from synapseclient.models.agent import AgentSession, AgentSessionAccessLevel
syn = Synapse()
syn.login()
my_session = await AgentSession(id="foo").get_async()
my_session.access_level = AgentSessionAccessLevel.READ_YOUR_PRIVATE_DATA
await my_session.update_async()
"""
session_response = await update_session(
id=self.id,
Expand Down Expand Up @@ -337,6 +385,23 @@ async def prompt_async(
synapse_client: If not passed in and caching was not disabled by
`Synapse.allow_client_caching(False)` this will use the last created
instance from the Synapse class constructor.
Example: Send a prompt within an existing session.
Retrieve an existing session by providing the session ID and calling `get()`.
Then, send a prompt to the agent.
from synapseclient import Synapse
from synapseclient.models.agent import AgentSession
syn = Synapse()
syn.login()
my_session = await AgentSession(id="foo").get_async()
await my_session.prompt_async(
prompt="Hello",
enable_trace=True,
print_response=True,
)
"""
agent_prompt = await AgentPrompt(
prompt=prompt, session_id=self.id, enable_trace=enable_trace
Expand Down Expand Up @@ -401,7 +466,23 @@ class Agent(AgentSynchronousProtocol):
my_agent = Agent(cloud_agent_id="foo")
my_agent.register()
my_agent.prompt(
prompt="Hello",
enable_trace=True,
print_response=True,
)
Example: Get and chat with an existing agent
Retrieve an existing agent by providing the agent's registration ID and calling `get()`.
Then, send a prompt to the agent.
from synapseclient import Synapse
from synapseclient.models.agent import Agent
syn = Synapse()
syn.login()
my_agent = Agent(registration_id="foo").get()
my_agent.prompt(
prompt="Hello",
enable_trace=True,
Expand Down Expand Up @@ -497,6 +578,27 @@ async def register_async(
Returns:
The registered or existing Agent object.
Example: Register and chat with a custom agent
**Only available for internal users (Sage Bionetworks employees)**
Alternatively, you can register a custom agent and chat with it provided
you have already created it.
from synapseclient import Synapse
from synapseclient.models.agent import Agent
syn = Synapse()
syn.login()
my_agent = Agent(cloud_agent_id="foo")
await my_agent.register_async()
await my_agent.prompt_async(
prompt="Hello",
enable_trace=True,
print_response=True,
)
"""
agent_response = await register_agent(
cloud_agent_id=self.cloud_agent_id,
Expand All @@ -518,6 +620,23 @@ async def get_async(self, *, synapse_client: Optional[Synapse] = None) -> "Agent
Returns:
The existing Agent object.
Example: Get and chat with an existing agent
Retrieve an existing agent by providing the agent's registration ID and calling `get()`.
Then, send a prompt to the agent.
from synapseclient import Synapse
from synapseclient.models.agent import Agent
syn = Synapse()
syn.login()
my_agent = await Agent(registration_id="foo").get_async()
await my_agent.prompt_async(
prompt="Hello",
enable_trace=True,
print_response=True,
)
"""
agent_response = await get_agent(
registration_id=self.registration_id,
Expand Down Expand Up @@ -550,6 +669,40 @@ async def start_session_async(
Returns:
The new AgentSession object.
Example: Start a session and send a prompt with the baseline Synapse Agent.
The baseline Synapse Agent is the default agent used when a registration ID is not provided.
from synapseclient import Synapse
from synapseclient.models.agent import Agent
syn = Synapse()
syn.login()
my_agent = Agent()
await my_agent.start_session_async()
await my_agent.prompt_async(
prompt="Can you tell me about the AD Knowledge Portal dataset?",
enable_trace=True,
print_response=True,
)
Example: Start a session and send a prompt with a custom agent.
The baseline Synapse Agent is the default agent used when a registration ID is not provided.
from synapseclient import Synapse
from synapseclient.models.agent import Agent
syn = Synapse()
syn.login()
my_agent = Agent(cloud_agent_id="foo")
await my_agent.start_session_async()
await my_agent.prompt_async(
prompt="Hello",
enable_trace=True,
print_response=True,
)
"""
access_level = AgentSessionAccessLevel(access_level)
session = await AgentSession(
Expand Down Expand Up @@ -577,6 +730,23 @@ async def get_session_async(
Returns:
The existing AgentSession object.
Example: Get an existing session and send a prompt.
Retrieve an existing session by providing the session ID and calling `get()`.
Then, send a prompt to the agent.
from synapseclient import Synapse
from synapseclient.models.agent import Agent
syn = Synapse()
syn.login()
my_session = await Agent().get_session_async(session_id="foo")
await my_session.prompt_async(
prompt="Hello",
enable_trace=True,
print_response=True,
)
"""
session = await AgentSession(id=session_id).get_async(
synapse_client=synapse_client
Expand Down Expand Up @@ -622,11 +792,55 @@ async def prompt_async(
syn.login()
my_agent = Agent()
my_agent.prompt(
await my_agent.prompt_async(
prompt="Add the annotation 'test' to the file 'syn123456789'",
enable_trace=True,
print_response=True,
)
Example: Prompt a custom agent.
If you have already registered a custom agent, you can prompt it by providing the agent's registration ID.
from synapseclient import Synapse
from synapseclient.models.agent import Agent
syn = Synapse()
syn.login()
my_agent = Agent(registration_id="foo")
await my_agent.prompt_async(
prompt="Hello",
enable_trace=True,
print_response=True,
)
Advanced Example: Start and prompt multiple sessions
Here, we connect to a custom agent and start one session with the prompt "Hello".
In the background, this first session is being set as the current session
and future prompts will be sent to this session by default. If we want to send a
prompt to a different session, we can do so by starting it and calling prompt again,
but with our new session as an argument. We now have two sessions, both stored in the
`my_agent.sessions` dictionary. After the second prompt, `my_second_session` is now
the current session.
syn = Synapse()
syn.login()
my_agent = Agent(registration_id="foo").get()
await my_agent.prompt_async(
prompt="Hello",
enable_trace=True,
print_response=True,
)
my_second_session = await my_agent.start_session_async()
await my_agent.prompt_async(
prompt="Hello again",
enable_trace=True,
print_response=True,
session=my_second_session,
)
"""
if session:
await self.get_session_async(
Expand All @@ -645,5 +859,24 @@ async def prompt_async(
)

def get_chat_history(self) -> Union[List[AgentPrompt], None]:
"""Gets the chat history for the current session."""
"""Gets the chat history for the current session.
Example: Get the chat history for the current session.
First, send a prompt to the agent.
Then, retrieve the chat history for the current session by calling `get_chat_history()`.
from synapseclient import Synapse
from synapseclient.models.agent import Agent
syn = Synapse()
syn.login()
my_agent = Agent()
await my_agent.prompt_async(
prompt="Hello",
enable_trace=True,
print_response=True,
)
print(my_agent.get_chat_history())
"""
return self.current_session.chat_history if self.current_session else None
Loading

0 comments on commit 13c8a0b

Please sign in to comment.