Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vectorshift.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Lifecycle

​
new

Agent.new(name: str, llm_info: LlmInfo, tools: Optional[list[Tool]] = None, instructions: Optional[str] = None, inputs: Optional[Dict[str, IoConfig]] = None, outputs: Optional[Dict[str, IoConfig]] = None, agent_type: Optional[AgentType] = None, type: Optional[AgentType] = None, memory_config: Optional[MemoryConfig] = None) -> Agent
Create a new agent with the specified parameters. Parameters
​
name
str
required
The name of the agent.
​
llm_info
LlmInfo
required
Configuration for the language model to use. See LlmInfo.
​
tools
Optional[list[Tool]]
default:"None"
List of tools available to the agent. See Tool.
​
instructions
Optional[str]
default:"None"
Instructions for the agent.
​
inputs
Optional[Dict[str, IoConfig]]
default:"None"
Dictionary mapping input names to their configurations. See IoConfig.
​
outputs
Optional[Dict[str, IoConfig]]
default:"None"
Dictionary mapping output names to their configurations. See IoConfig.
​
agent_type
Optional[AgentType]
default:"None"
The type of agent (FUNCTIONAL or CONVERSATIONAL). See AgentType.
​
type
Optional[AgentType]
default:"None"
Alias for agent_type. See AgentType.
​
memory_config
Optional[MemoryConfig]
default:"None"
Memory configuration (conversational agents only). See MemoryConfig.
Returns
​
returns
Agent
A new Agent instance.
Raises
​
Exception
exception
If the agent creation fails.

​
save

Agent.save(deploy: bool = False, bump: bool = False, description: Optional[str] = None) -> dict
Save the agent with its current configuration. Updates the agent on the server with the current name, LLM configuration, tools, instructions, inputs and outputs. Parameters
​
deploy
bool
default:"False"
Whether to deploy the agent after saving.
​
bump
bool
default:"False"
Whether to bump the agent version.
​
description
Optional[str]
default:"None"
Optional description for this save/version.
Returns
​
returns
dict
dict: A dictionary containing the status of the save operation.
Raises
​
Exception
exception
If the agent update fails.

​
fetch

Agent.fetch(id: Optional[str] = None, name: Optional[str] = None, username: Optional[str] = None, org_name: Optional[str] = None) -> Agent
Fetches an existing agent. Parameters
​
id
Optional[str]
default:"None"
The unique identifier of the agent to fetch.
​
name
Optional[str]
default:"None"
The name of the agent to fetch.
​
username
Optional[str]
default:"None"
The username of the agent owner.
​
org_name
Optional[str]
default:"None"
The organization name of the agent owner.
Returns
​
returns
Agent
Agent: The fetched Agent instance.
Raises
​
ValueError
exception
If neither id nor name is provided.
​
Exception
exception
If the agent couldn’t be fetched.

​
list

Agent.list(limit: int = 50, offset: int = 0, include_shared: bool = False) -> "list[Agent]"
List agents for the authenticated user. Parameters
​
limit
int
default:"50"
Maximum number of agents to return.
​
offset
int
default:"0"
Number of agents to skip.
​
include_shared
bool
default:"False"
Whether to include agents shared with the user.
Returns
​
returns
list[Agent]
list[Agent]: List of Agent instances (or lightweight stubs with id only if the server returns object_ids without full objects).

​
delete

Agent.delete() -> dict
Deletes an existing agent. Returns
​
returns
dict
dict: A dictionary containing the status of the deletion operation.
Raises
​
Exception
exception
If the agent couldn’t be deleted.

​
Configuration

​
update_instructions

Agent.update_instructions(instructions: str) -> None
Update the instructions for the agent. Parameters
​
instructions
str
required

​
update_llm_info

Agent.update_llm_info(llm_info: LlmInfo) -> None
Update the LLM configuration for the agent. Parameters
​
llm_info
LlmInfo
required
See LlmInfo.

​
remove_tool

Agent.remove_tool(tool_or_name: Union[Tool, str]) -> None
Remove a tool by instance, name, or tool_type. Parameters
​
tool_or_name
Union[Tool, str]
required
See Tool.

​
Running

​
run

Agent.run(inputs: Any = None, additional_instructions: Optional[str] = None, *, files: Optional[Sequence[Union[Path, bytes, io.IOBase]]] = None, session_id: Optional[str] = None, keep_alive: bool = False, include_deltas: bool = False) -> Union[AgentRunResult, Coroutine[Any, Any, ConversationalAgentRunResult]]
Run the agent. Dispatches on :attr:agent_type:
  • Functional — agent.run(inputs=\{...\}) runs synchronously and returns an :class:AgentRunResult.
  • Conversational (experimental) — await agent.run("...") opens a hidden session, posts one turn, waits for the final message, and returns a :class:ConversationalAgentRunResult. Pass session_id to resume an existing session for one turn; pass keep_alive=True to keep a hidden session reachable across calls. include_deltas=False (default) drops MESSAGE_DELTA events from result.events so long turns don’t bloat the result; pass True to keep them for debugging — final_message is unaffected either way. The primary supported path for conversational agents is still :meth:create_session; this is a convenience wrapper for ask-once-and-wait flows.
Parameters
​
inputs
Any
default:"None"
​
additional_instructions
Optional[str]
default:"None"
​
files
Optional[Sequence[Union[Path, bytes, io.IOBase]]]
default:"None"
​
session_id
Optional[str]
default:"None"
​
keep_alive
bool
default:"False"
​
include_deltas
bool
default:"False"
Returns
​
returns
Union[AgentRunResult, Coroutine[Any, Any, ConversationalAgentRunResult]]
See AgentRunResult.
Raises
​
ValueError
exception
If the call shape does not match the agent type.
​
ConversationalRunActionRequiredError
exception
If the conversational turn requires approval/reauth — use :meth:create_session or :meth:resume_session to handle it.

​
Sessions

​
create_session

async Agent.create_session(session_id: Optional[str] = None) -> Session
Create a real-time session for this conversational agent. Parameters
​
session_id
Optional[str]
default:"None"
Optional session ID to resume an existing session.
Returns
​
returns
Session
Session: A Session instance (not yet connected; use as async context manager).
Raises
​
ValueError
exception
If agent is functional (use run() instead).

​
resume_session

async Agent.resume_session(session_id: str) -> Session
Resume an existing session by ID. Parameters
​
session_id
str
required
The session ID to reconnect to.
Returns
​
returns
Session
Session: A Session instance (not yet connected; use as async context manager).
Raises
​
ValueError
exception
If agent is functional or session_id is empty.

​
Serialization

​
from_json

Agent.from_json(data: dict) -> Agent
Create an agent instance from a JSON dictionary. Parameters
​
data
dict
required
Returns
​
returns
Agent

​
serialize_inputs

Agent.serialize_inputs(inputs: dict[str, Any]) -> dict[str, Any]
Parameters
​
inputs
dict[str, Any]
required
Returns
​
returns
dict[str, Any]

​
Types

Configuration objects, response shapes, and enums used by the methods above.

​
AgentType

Members
  • FUNCTIONAL = "functional"
  • CONVERSATIONAL = "conversational"

​
LlmInfo

Fields
​
provider
str
required
​
model_id
str
required
​
api_key
Optional[str]
​
fine_tuned_model_id
Optional[str]
​
endpoint
Optional[str]
​
deployment_id
Optional[str]
​
stream_response
bool
default:"False"
​
json_output
bool
default:"True"
​
show_source
bool
default:"False"
​
show_confidence
bool
default:"False"
​
enable_tools
bool
default:"True"
​
toxic_input_filtration
bool
default:"False"
​
detect_pii
Optional[vectorshift.agent.object.DetectPii]
​
base_url
Optional[str]
​
max_retries
Optional[int]
​
retry_interval_ms
Optional[int]

​
IoConfig

Fields
​
io_type
str
required
​
description
Optional[str]
default:"''"
​
server_id
Optional[str]

​
MemoryConfig

MemoryConfig(enable_session_memory: ‘bool’ = True, enable_global_memory: ‘bool’ = False) Fields
​
enable_session_memory
bool
default:"True"
​
enable_global_memory
bool
default:"False"

​
AgentRunResult

AgentRunResult(outputs: ‘dict[str, Any]’, run_id: ‘str’, status: ‘str’, error: ‘Optional[str]’ = None) Fields
​
outputs
dict[str, Any]
required
​
run_id
str
required
​
status
str
required
​
error
Optional[str]

​
Tool

​
ToolInput

Fields
​
type
str
default:"'static'"
​
value
Optional[Any]
​
description
Optional[str]

​
ToolInputType

Members
  • STATIC = "static"
  • DYNAMIC = "dynamic"

​
ToolApprovalConfig

Members
  • AUTO_RUN = "auto_run"
  • LET_AGENT_DECIDE = "let_agent_decide"
  • REQUIRES_APPROVAL = "requires_approval"