Security advisory — Malicious litellm versions 1.82.7 and 1.82.8 were removed from PyPI (potential API key exfiltration). Uninstall them, rotate exposed credentials, and upgrade to a safe release (e.g. 1.82.9+). Run pip show litellm to verify. PyPI · README

Quick Start

Run an agent from Python, or start the local Studio server Near talks to.

Quick Start

Two valid first runs. Pick one. They are not the same loop.

PathEntryLoop
SDKAgent + Task + AgentExecutorClassic task executor in agenticx/core/agent_executor.py
Studio / Nearagx serve then the desktop appAgentRuntime.run_turn in agenticx/runtime/agent_runtime.py
Diagram: two first runs — AgentExecutor.run returns a dict; Studio streams SSE.

Path A — embed in Python

python
1from agenticx import Agent, Task, AgentExecutor
2from agenticx.llms import OpenAIProvider
3from agenticx.tools.function_tool import tool
4

5@tool(name="add", description="Add two integers.")
6def add(a: int, b: int) -> int:
7    return a + b
8

9agent = Agent(
10    name="Analyst",
11    role="Data analysis helper",
12    goal="Answer numeric questions",
13    organization_id="my-org",
14)
15task = Task(
16    id="sum-1",
17    description="What is 42 + 58?",
18    expected_output="The integer sum",
19)
20

21executor = AgentExecutor(
22    llm_provider=OpenAIProvider(model="gpt-4o"),
23    tools=[add],
24)
25result = executor.run(agent=agent, task=task)
26print(result)

You need a working provider key in the environment. Details: Agent Runtime, Tools.

Path B — local Studio for Near

bash
1agx serve --host 127.0.0.1 --port 8000

Desktop usually spawns this for you on 127.0.0.1 with an ephemeral port, then writes ~/.agenticx/serve.port and ~/.agenticx/serve.token. If you start it yourself, Near must point at that host and port.

agx studio is the terminal REPL, not the FastAPI process. See Studio Server.

Path C — one-shot CLI

bash
1agx run "Summarize what AgenticX is in two sentences"

Use this to check that the provider config works before opening the desktop UI.

If nothing happens

  1. agx --version fails → package not on this PATH
  2. Provider 401 → key missing or wrong env
  3. Desktop empty avatars / history → agx serve is not listening (check ~/.agenticx/serve.port)
  4. Tool loop stops early → raise runtime.max_tool_rounds / AGX_MAX_TOOL_ROUNDS in Configuration

Next