Agent reference - VectorShift

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

async Agent.anew(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

async Agent.asave(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.

`deploy=True` vs `deploy=False` — the branch model

Think of an agent like a Git repo:

Working tree — the Agent object in your Python process. Mutations like add_tool, remove_tool, or reassigning instructions happen here.
Main branch — the branch_id on the server. save(deploy=False) writes your working tree to this branch as a new commit. Anything reading by branch_id (the platform editor, your own dev/test code) immediately sees the change.
Deployed version — what callers of the published agent get. Chatbots, interfaces, pipelines that reference the agent by id-without-version, and the platform’s “Run published” button all read this version. save(deploy=True) promotes the current main-branch state to be the new deployed version.

Bumping versions (bump=True) attaches a tagged release to the deploy so consumers can pin to a specific build instead of always tracking the latest deployed. In practice:

Iterating on prompts/tools? save(deploy=False) — fast, no production fallout.
Ready for users? save(deploy=True) (optionally with bump=True + description=... for a labelled version).

Parameters

deploy

bool

default:"False"

When True, promotes the saved state to be the new deployed version that callers of the published agent will hit. When False, only updates the working/main branch — the deployed version is untouched until the next save(deploy=True).

bump

bool

default:"False"

When True (only meaningful with deploy=True), creates a new tagged version on deploy so consumers can pin to it.

description

Optional[str]

default:"None"

Updates the agent description; also used as the changelog when bumping a 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

async Agent.afetch(id: Optional[str] = None, name: Optional[str] = None, username: Optional[str] = None, org_name: Optional[str] = None) -> Agent

Fetches an existing agent. Parameters

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]"

async Agent.alist(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

async Agent.adelete() -> 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.

Tools

`tools`

agent.tools  # list[Tool]  (instance attribute)

The list of tools currently attached to this agent. Mutated in place by add_tool / remove_tool (and by direct agent.tools = [...] assignment). Persisted to the platform on the next agent.save().

`add_tool`

agent.add_tool  # _BoundToolAdder  (instance attribute)

Fluent adder for attaching tools to an agent instance. Every entry in the platform tool catalogue is reachable as a method — agent.add_tool.<tool_type>(...). Each factory call requires a non-empty tool_name= (the LLM-facing name, unique within the agent) — omitting it raises ValueError. The call mutates agent.tools in place; persist with agent.save() afterwards.

from vectorshift.agent.tool import ToolInput, ToolInputType, ToolApprovalConfig

agent.add_tool.google_search(
    tool_name="web_search",
    query=ToolInput(type=ToolInputType.DYNAMIC, description="Search query"),
    num_results=5,
    approval_config=ToolApprovalConfig.LET_AGENT_DECIDE,
)
agent.save()

`AgentTools` catalogue

from vectorshift.agent import AgentTools

Class-level namespace exposing every tool in the platform catalogue — currently 261 tools including web search (exa_ai, google_search, perplexity), knowledge & retrieval (knowledge_base, deep_research, parallel_ai_search), code & data (code_interpreter, dataframe_get_schema, dataframe_raw_query), media (ai_text_to_image, ai_image_to_text, ai_text_to_speech), integrations (integration_* for every connected service), pipelines, transformations, and more. Every AgentTools.<tool_type>(...) factory requires a non-empty tool_name= (unique within the agent); omitting it raises ValueError. Two invocation patterns:

# 1) Pass into Agent.new(tools=[...]) at construction time:
agent = Agent.new(
    name="Researcher",
    type=AgentType.CONVERSATIONAL,
    llm_info=LlmInfo(provider="openai", model_id="gpt-5.1"),
    tools=[
        AgentTools.exa_ai(
            tool_name="search",
            query=ToolInput(type=ToolInputType.DYNAMIC),
            num_results=5,
        ),
        AgentTools.knowledge_base(id=kb.id, tool_name="docs"),
    ],
)

# 2) Or via the bound adder on an existing agent (see `add_tool` above).

The full catalogue is generated from the platform’s tool registry and ships as a typed .pyi stub (vectorshift/agent/agent_tools.pyi) — your editor’s autocomplete is the canonical browseable catalogue. The conversational-agent-tools example and tool-approval-config example show the most common entries end-to-end.

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]]

async Agent.arun(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, 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"

​Lifecycle

​new

​save

​deploy=True vs deploy=False — the branch model

​fetch

​list

​delete

​Tools

​tools

​add_tool

​AgentTools catalogue

​Configuration

​update_instructions

​update_llm_info

​remove_tool

​Running

​run

​Sessions

​create_session

​resume_session

​Serialization

​from_json

​serialize_inputs

​Types

​AgentType

​LlmInfo

​IoConfig

​MemoryConfig

​AgentRunResult

​Tool

​ToolInput

​ToolInputType

​ToolApprovalConfig

Lifecycle

`new`

`save`

`deploy=True` vs `deploy=False` — the branch model

`fetch`

`list`

`delete`

Tools

`tools`

`add_tool`

`AgentTools` catalogue

Configuration

`update_instructions`

`update_llm_info`

`remove_tool`

Running

`run`

Sessions

`create_session`

`resume_session`

Serialization

`from_json`

`serialize_inputs`

Types

`AgentType`

`LlmInfo`

`IoConfig`

`MemoryConfig`

`AgentRunResult`

`Tool`

`ToolInput`

`ToolInputType`

`ToolApprovalConfig`