Home/Documentation

Agent

The Agent resource provides a conversational interface with tool use. The agent can search knowledge, create facts, and manage memory—with optional approval workflows for write operations.

POSTclient.agent.invoke()
HTTP:POST /v1/agent/invoke

Send a query to the agent and get a response with citations and optional pending actions.

Parameters

querystrRequired

The user query to send to the agent.

group_idslist[str]Required

Group IDs the agent has access to for context.

user_rolestrOptionalDefault: "viewer"

User role for permission checks: "viewer", "editor", or "admin".

auto_approveboolOptionalDefault: False

If True, automatically execute write operations without approval.

session_messageslist[dict]Optional

Previous messages in this conversation session for context.

Returns

InvokeResponse with:

  • response: str - The agent's text response
  • citations: list[Citation] - Facts used to generate the response
  • tool_trace: list[ToolTrace] - Record of tool calls made
  • pending_actions: list[PendingAction] - Write operations awaiting approval
  • has_pending_actions() - Check if approval is needed

Example

basic_invoke.py
PYTHON
from memoair import MemoAir
 
client = MemoAir()
 
# Ask the agent a question
response = client.agent.invoke(
    query="What projects is John working on?",
    group_ids=["user:john", "org:acme"],
)
 
print(response.response)
# "Based on the knowledge graph, John is working on the following projects:
#  1. Project Alpha - a machine learning pipeline
#  2. Project Beta - API modernization"
 
# Show citations
print("\nCitations:")
for citation in response.citations:
    print(f"  - {citation.fact}")

Approval Workflow

By default, write operations (creating facts, updating memory) require explicit approval. This prevents the agent from making unauthorized changes to your knowledge graph.

approval_workflow.py
PYTHON
from memoair import MemoAir
 
client = MemoAir()
 
# Ask the agent to remember something
response = client.agent.invoke(
    query="Remember that John just got promoted to Staff Engineer",
    group_ids=["user:john"],
    user_role="editor",  # Has write permissions
)
 
# Check for pending actions
if response.has_pending_actions():
    print("Agent wants to perform the following actions:")
 
    for action in response.pending_actions:
        print(f"\n  Tool: {action.tool_name}")
        print(f"  Args: {action.tool_args}")
        print(f"  Target: {action.target_graph}")
 
        # Get user confirmation
        user_input = input("Approve? (y/n): ")
 
        if user_input.lower() == 'y':
            result = client.agent.approve_action(
                action=action,
                group_ids=["user:john"],
            )
            print(f"  Result: {result.result}")
        else:
            print("  Skipped")
POSTclient.agent.execute_action()
HTTP:POST /v1/agent/execute

Execute a pending action directly. Lower-level than approve_action().

Parameters

action_idstrRequired

Unique ID of the action to execute.

tool_namestrRequired

Name of the tool to execute.

tool_argsdictRequired

Arguments to pass to the tool.

target_graphstrRequired

Which graph the action affects.

group_idslist[str]Required

Group IDs for context.

PYTHON
# Execute an action directly
result = client.agent.execute_action(
    action_id=action.action_id,
    tool_name=action.tool_name,
    tool_args=action.tool_args,
    target_graph=action.target_graph,
    group_ids=["user:john"],
)
 
print(f"Executed: {result.result}")
POSTclient.agent.approve_action()
HTTP:POST /v1/agent/approve

Convenience wrapper to approve and execute a PendingAction.

PYTHON
# Approve and execute a pending action
for action in response.pending_actions:
    result = client.agent.approve_action(
        action=action,  # Pass the PendingAction object directly
        group_ids=["user:john"],
    )
    print(f"Approved: {result.result}")

Auto-Approve Mode

For trusted automation scenarios, you can enable auto-approval to let the agent execute write operations immediately.

Warning: Use auto_approve=True with caution. The agent will create and modify facts without confirmation.

PYTHON
# Auto-approve mode (use with caution)
response = client.agent.invoke(
    query="Add a note that John prefers morning meetings",
    group_ids=["user:john"],
    user_role="admin",
    auto_approve=True,  # No confirmation needed
)
 
# The action was already executed
print(response.response)
# "I've added to John's preferences that he prefers morning meetings."

Session Context

For multi-turn conversations, pass previous messages to maintain context:

session_context.py
PYTHON
# Multi-turn conversation
session = []
 
# Turn 1
response1 = client.agent.invoke(
    query="Who is John?",
    group_ids=["user:john"],
    session_messages=session,
)
session.append({"role": "user", "content": "Who is John?"})
session.append({"role": "assistant", "content": response1.response})
 
# Turn 2 (with context)
response2 = client.agent.invoke(
    query="What projects is he working on?",  # "he" refers to John
    group_ids=["user:john"],
    session_messages=session,
)
print(response2.response)