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.pypython

1from memoair import MemoAir
2
3client = MemoAir()
4
5# Ask the agent a question
6response = client.agent.invoke(
7    query="What projects is John working on?",
8    group_ids=["user:john", "org:acme"],
9)
10
11print(response.response)
12# "Based on the knowledge graph, John is working on the following projects:
13#  1. Project Alpha - a machine learning pipeline
14#  2. Project Beta - API modernization"
15
16# Show citations
17print("\nCitations:")
18for citation in response.citations:
19    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.pypython

1from memoair import MemoAir
2
3client = MemoAir()
4
5# Ask the agent to remember something
6response = client.agent.invoke(
7    query="Remember that John just got promoted to Staff Engineer",
8    group_ids=["user:john"],
9    user_role="editor",  # Has write permissions
10)
11
12# Check for pending actions
13if response.has_pending_actions():
14    print("Agent wants to perform the following actions:")
15
16    for action in response.pending_actions:
17        print(f"\n  Tool: {action.tool_name}")
18        print(f"  Args: {action.tool_args}")
19        print(f"  Target: {action.target_graph}")
20
21        # Get user confirmation
22        user_input = input("Approve? (y/n): ")
23
24        if user_input.lower() == 'y':
25            result = client.agent.approve_action(
26                action=action,
27                group_ids=["user:john"],
28            )
29            print(f"  Result: {result.result}")
30        else:
31            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.

1# Execute an action directly
2result = client.agent.execute_action(
3    action_id=action.action_id,
4    tool_name=action.tool_name,
5    tool_args=action.tool_args,
6    target_graph=action.target_graph,
7    group_ids=["user:john"],
8)
9
10print(f"Executed: {result.result}")

POSTclient.agent.approve_action()

HTTP:POST /v1/agent/approve

Convenience wrapper to approve and execute a PendingAction.

1# Approve and execute a pending action
2for action in response.pending_actions:
3    result = client.agent.approve_action(
4        action=action,  # Pass the PendingAction object directly
5        group_ids=["user:john"],
6    )
7    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.

1# Auto-approve mode (use with caution)
2response = client.agent.invoke(
3    query="Add a note that John prefers morning meetings",
4    group_ids=["user:john"],
5    user_role="admin",
6    auto_approve=True,  # No confirmation needed
7)
8
9# The action was already executed
10print(response.response)
11# "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.pypython

1# Multi-turn conversation
2session = []
3
4# Turn 1
5response1 = client.agent.invoke(
6    query="Who is John?",
7    group_ids=["user:john"],
8    session_messages=session,
9)
10session.append({"role": "user", "content": "Who is John?"})
11session.append({"role": "assistant", "content": response1.response})
12
13# Turn 2 (with context)
14response2 = client.agent.invoke(
15    query="What projects is he working on?",  # "he" refers to John
16    group_ids=["user:john"],
17    session_messages=session,
18)
19print(response2.response)